Red Hat Virtualization

4.0
REST API Guide

Using the Red Hat Virtualization REST Application Programming Interface

Red Hat Virtualization Documentation Team

Red Hat Virtualization 4.0 REST API Guide

Using the Red Hat Virtualization REST Application Programming Interface

Red Hat Virtualization Documentation Team

rhev-docs@redhat.com
Legal Notice
Copyright © 2017 Red Hat, Inc.

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

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

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

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

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

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

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

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

The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other countries
and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or
sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract
This guide describes the Red Hat Virtualization Manager Representational State Transfer
Application Programming Interface. This guide is generated from documentation comments in the
ovirt-engine-api-model code, and is currently partially complete. Updated versions of this
documentation will be published as new content becomes available.
 Table of Contents

Table of Contents
.CHAPTER
. . . . . . . . .1.. .INTRODUCTION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
...........
1.1. REPRESENTATIONAL STATE TRANSFER 13
1.2. API PREREQUISITES 13

.CHAPTER
. . . . . . . . .2.. .AUTHENTICATION
. . . . . . . . . . . . . . . . AND
. . . . .SECURITY
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
...........
2.1. TLS/SSL CERTIFICATION 15
2.2. AUTHENTICATION 17

.CHAPTER
. . . . . . . . .3.. .QUICK
. . . . . .START
. . . . . . .EXAMPLE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
...........
3.1. EXAMPLE: ACCESS API ENTRY POINT 22
3.2. EXAMPLE: LIST DATA CENTERS 24
3.3. EXAMPLE: LIST HOST CLUSTERS 25
3.4. EXAMPLE: LIST LOGICAL NETWORKS 26
3.5. EXAMPLE: LIST HOSTS 27
3.6. EXAMPLE: CREATE NFS DATA STORAGE 28
3.7. EXAMPLE: CREATE NFS ISO STORAGE 30
3.8. EXAMPLE: ATTACH STORAGE DOMAINS TO DATA CENTER 31
3.9. EXAMPLE: CREATE VIRTUAL MACHINE 32
3.10. EXAMPLE: CREATE A VIRTUAL MACHINE NIC 34
3.11. EXAMPLE: CREATE VIRTUAL DISK 35
3.12. EXAMPLE: ATTACH ISO IMAGE TO VIRTUAL MACHINE 36
3.13. EXAMPLE: START THE VIRTUAL MACHINE 37

. . . . . . . . . .4.. .REQUESTS
CHAPTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
...........

.CHAPTER
. . . . . . . . .5.. .SERVICES
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
...........
5.1. AFFINITYGROUP 65
5.2. AFFINITYGROUPVM 66
5.3. AFFINITYGROUPVMS 67
5.4. AFFINITYGROUPS 68
5.5. AFFINITYLABEL 69
5.6. AFFINITYLABELHOST 70
5.7. AFFINITYLABELHOSTS 71
5.8. AFFINITYLABELVM 72
5.9. AFFINITYLABELVMS 72
5.10. AFFINITYLABELS 73
5.11. ASSIGNEDAFFINITYLABEL 74
5.12. ASSIGNEDAFFINITYLABELS 75
5.13. ASSIGNEDCPUPROFILE 76
5.14. ASSIGNEDCPUPROFILES 77
5.15. ASSIGNEDDISKPROFILE 78
5.16. ASSIGNEDDISKPROFILES 78
5.17. ASSIGNEDNETWORK 79
5.18. ASSIGNEDNETWORKS 80
5.19. ASSIGNEDPERMISSIONS 81
5.20. ASSIGNEDROLES 83
5.21. ASSIGNEDTAG 84
5.22. ASSIGNEDTAGS 85
5.23. ASSIGNEDVNICPROFILE 87
5.24. ASSIGNEDVNICPROFILES 87
5.25. ATTACHEDSTORAGEDOMAIN 88
5.26. ATTACHEDSTORAGEDOMAINS 90
5.27. BALANCE 91

1
Red Hat Virtualization 4.0 REST API Guide

5.27. BALANCE 91
5.28. BALANCES 92
5.29. BOOKMARK 93
5.30. BOOKMARKS 95
5.31. CLUSTER 96
5.32. CLUSTERLEVEL 100
5.33. CLUSTERLEVELS 101
5.34. CLUSTERS 102
5.35. COPYABLE 103
5.36. CPUPROFILE 104
5.37. CPUPROFILES 105
5.38. DATACENTER 106
5.39. DATACENTERS 108
5.40. DISK 111
5.41. DISKATTACHMENT 114
5.42. DISKATTACHMENTS 116
5.43. DISKPROFILE 117
5.44. DISKPROFILES 119
5.45. DISKSNAPSHOT 120
5.46. DISKSNAPSHOTS 120
5.47. DISKS 121
5.48. DOMAIN 123
5.49. DOMAINGROUP 124
5.50. DOMAINGROUPS 124
5.51. DOMAINUSER 125
5.52. DOMAINUSERS 126
5.53. DOMAINS 127
5.54. ENGINEKATELLOERRATA 128
5.55. EVENT 130
5.56. EVENTS 131
5.57. EXTERNALCOMPUTERESOURCE 135
5.58. EXTERNALCOMPUTERESOURCES 136
5.59. EXTERNALDISCOVEREDHOST 136
5.60. EXTERNALDISCOVEREDHOSTS 137
5.61. EXTERNALHOST 137
5.62. EXTERNALHOSTGROUP 138
5.63. EXTERNALHOSTGROUPS 138
5.64. EXTERNALHOSTPROVIDER 139
5.65. EXTERNALHOSTPROVIDERS 141
5.66. EXTERNALHOSTS 142
5.67. EXTERNALPROVIDER 142
5.68. EXTERNALPROVIDERCERTIFICATE 143
5.69. EXTERNALPROVIDERCERTIFICATES 144
5.70. EXTERNALVMIMPORTS 144
5.71. FENCEAGENT 145
5.72. FENCEAGENTS 147
5.73. FILE 147
5.74. FILES 148
5.75. FILTER 149
5.76. FILTERS 150
5.77. GLUSTERBRICK 151
5.78. GLUSTERBRICKS 153
5.79. GLUSTERHOOK 159
5.80. GLUSTERHOOKS 161

2
 Table of Contents

5.80. GLUSTERHOOKS 161

5.81. GLUSTERVOLUME 161
5.82. GLUSTERVOLUMES 169
5.83. GRAPHICSCONSOLE 171
5.84. GRAPHICSCONSOLES 172
5.85. GROUP 173
5.86. GROUPS 174
5.87. HOST 175
5.88. HOSTDEVICE 189
5.89. HOSTDEVICES 190
5.90. HOSTHOOK 190
5.91. HOSTHOOKS 191
5.92. HOSTNIC 191
5.93. HOSTNICS 192
5.94. HOSTNUMANODE 193
5.95. HOSTNUMANODES 194
5.96. HOSTSTORAGE 194
5.97. HOSTS 196
5.98. ICON 198
5.99. ICONS 199
5.100. IMAGE 200
5.101. IMAGETRANSFER 201
5.102. IMAGETRANSFERS 205
5.103. IMAGES 206
5.104. INSTANCETYPE 206
5.105. INSTANCETYPENIC 208
5.106. INSTANCETYPENICS 209
5.107. INSTANCETYPEWATCHDOG 210
5.108. INSTANCETYPEWATCHDOGS 211
5.109. INSTANCETYPES 212
5.110. ISCSIBOND 215
5.111. ISCSIBONDS 217
5.112. JOB 218
5.113. JOBS 220
5.114. KATELLOERRATA 222
5.115. KATELLOERRATUM 223
5.116. MACPOOL 224
5.117. MACPOOLS 226
5.118. MEASURABLE 227
5.119. MOVEABLE 227
5.120. NETWORK 227
5.121. NETWORKATTACHMENT 230
5.122. NETWORKATTACHMENTS 231
5.123. NETWORKFILTER 232
5.124. NETWORKFILTERS 233
5.125. NETWORKLABEL 234
5.126. NETWORKLABELS 235
5.127. NETWORKS 236
5.128. OPENSTACKIMAGE 238
5.129. OPENSTACKIMAGEPROVIDER 240
5.130. OPENSTACKIMAGEPROVIDERS 242
5.131. OPENSTACKIMAGES 243
5.132. OPENSTACKNETWORK 244
5.133. OPENSTACKNETWORKPROVIDER 245

3
Red Hat Virtualization 4.0 REST API Guide

5.133. OPENSTACKNETWORKPROVIDER 245

5.134. OPENSTACKNETWORKPROVIDERS 247
5.135. OPENSTACKNETWORKS 248
5.136. OPENSTACKSUBNET 249
5.137. OPENSTACKSUBNETS 250
5.138. OPENSTACKVOLUMEAUTHENTICATIONKEY 251
5.139. OPENSTACKVOLUMEAUTHENTICATIONKEYS 252
5.140. OPENSTACKVOLUMEPROVIDER 253
5.141. OPENSTACKVOLUMEPROVIDERS 255
5.142. OPENSTACKVOLUMETYPE 256
5.143. OPENSTACKVOLUMETYPES 257
5.144. OPERATINGSYSTEM 257
5.145. OPERATINGSYSTEMS 258
5.146. PERMISSION 258
5.147. PERMIT 259
5.148. PERMITS 260
5.149. QOS 262
5.150. QOSS 263
5.151. QUOTA 264
5.152. QUOTACLUSTERLIMIT 266
5.153. QUOTACLUSTERLIMITS 267
5.154. QUOTASTORAGELIMIT 268
5.155. QUOTASTORAGELIMITS 268
5.156. QUOTAS 269
5.157. ROLE 271
5.158. ROLES 272
5.159. SCHEDULINGPOLICIES 274
5.160. SCHEDULINGPOLICY 275
5.161. SCHEDULINGPOLICYUNIT 276
5.162. SCHEDULINGPOLICYUNITS 277
5.163. SNAPSHOT 278
5.164. SNAPSHOTCDROM 279
5.165. SNAPSHOTCDROMS 280
5.166. SNAPSHOTDISK 280
5.167. SNAPSHOTDISKS 281
5.168. SNAPSHOTNIC 281
5.169. SNAPSHOTNICS 282
5.170. SNAPSHOTS 282
5.171. SSHPUBLICKEY 284
5.172. SSHPUBLICKEYS 285
5.173. STATISTIC 286
5.174. STATISTICS 286
5.175. STEP 288
5.176. STEPS 289
5.177. STORAGE 291
5.178. STORAGEDOMAIN 293
5.179. STORAGEDOMAINCONTENTDISK 297
5.180. STORAGEDOMAINCONTENTDISKS 298
5.181. STORAGEDOMAINSERVERCONNECTION 299
5.182. STORAGEDOMAINSERVERCONNECTIONS 299
5.183. STORAGEDOMAINTEMPLATE 300
5.184. STORAGEDOMAINTEMPLATES 303
5.185. STORAGEDOMAINVM 303
5.186. STORAGEDOMAINVMDISKATTACHMENT 306

4
 Table of Contents

5.186. STORAGEDOMAINVMDISKATTACHMENT 306

5.187. STORAGEDOMAINVMDISKATTACHMENTS 307
5.188. STORAGEDOMAINVMS 307
5.189. STORAGEDOMAINS 309
5.190. STORAGESERVERCONNECTION 311
5.191. STORAGESERVERCONNECTIONEXTENSION 313
5.192. STORAGESERVERCONNECTIONEXTENSIONS 315
5.193. STORAGESERVERCONNECTIONS 316
5.194. SYSTEM 317
5.195. SYSTEMPERMISSIONS 319
5.196. TAG 321
5.197. TAGS 323
5.198. TEMPLATE 325
5.199. TEMPLATECDROM 328
5.200. TEMPLATECDROMS 329
5.201. TEMPLATEDISK 330
5.202. TEMPLATEDISKATTACHMENT 331
5.203. TEMPLATEDISKATTACHMENTS 332
5.204. TEMPLATEDISKS 333
5.205. TEMPLATENIC 334
5.206. TEMPLATENICS 335
5.207. TEMPLATEWATCHDOG 336
5.208. TEMPLATEWATCHDOGS 337
5.209. TEMPLATES 338
5.210. UNMANAGEDNETWORK 340
5.211. UNMANAGEDNETWORKS 341
5.212. USER 342
5.213. USERS 343
5.214. VIRTUALFUNCTIONALLOWEDNETWORK 345
5.215. VIRTUALFUNCTIONALLOWEDNETWORKS 346
5.216. VM 347
5.217. VMAPPLICATION 361
5.218. VMAPPLICATIONS 362
5.219. VMCDROM 364
5.220. VMCDROMS 366
5.221. VMDISK 367
5.222. VMDISKS 369
5.223. VMGRAPHICSCONSOLE 370
5.224. VMHOSTDEVICE 372
5.225. VMHOSTDEVICES 373
5.226. VMNIC 375
5.227. VMNICS 378
5.228. VMNUMANODE 380
5.229. VMNUMANODES 381
5.230. VMPOOL 382
5.231. VMPOOLS 385
5.232. VMREPORTEDDEVICE 387
5.233. VMREPORTEDDEVICES 387
5.234. VMSESSION 388
5.235. VMSESSIONS 388
5.236. VMWATCHDOG 389
5.237. VMWATCHDOGS 392
5.238. VMS 393
5.239. VNICPROFILE 399

5
Red Hat Virtualization 4.0 REST API Guide

5.239. VNICPROFILE 399

5.240. VNICPROFILES 400
5.241. WEIGHT 402
5.242. WEIGHTS 403

. . . . . . . . . .6.. .TYPES
CHAPTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .405
............
6.1. ACCESSPROTOCOL ENUM 405
6.2. ACTION STRUCT 405
6.3. AFFINITYGROUP STRUCT 410
6.4. AFFINITYLABEL STRUCT 411
6.5. AGENT STRUCT 412
6.6. AGENTCONFIGURATION STRUCT 413
6.7. API STRUCT 414
6.8. APISUMMARY STRUCT 415
6.9. APISUMMARYITEM STRUCT 416
6.10. APPLICATION STRUCT 416
6.11. ARCHITECTURE ENUM 417
6.12. AUTHORIZEDKEY STRUCT 417
6.13. AUTONUMASTATUS ENUM 418
6.14. BALANCE STRUCT 418
6.15. BIOS STRUCT 419
6.16. BLOCKSTATISTIC STRUCT 419
6.17. BONDING STRUCT 419
6.18. BOOKMARK STRUCT 420
6.19. BOOT STRUCT 421
6.20. BOOTDEVICE ENUM 421
6.21. BOOTMENU STRUCT 421
6.22. BOOTPROTOCOL ENUM 421
6.23. BRICKPROFILEDETAIL STRUCT 422
6.24. CDROM STRUCT 423
6.25. CERTIFICATE STRUCT 424
6.26. CLOUDINIT STRUCT 424
6.27. CLUSTER STRUCT 425
6.28. CLUSTERLEVEL STRUCT 432
6.29. CONFIGURATION STRUCT 433
6.30. CONFIGURATIONTYPE ENUM 434
6.31. CONSOLE STRUCT 435
6.32. CORE STRUCT 435
6.33. CPU STRUCT 435
6.34. CPUMODE ENUM 436
6.35. CPUPROFILE STRUCT 436
6.36. CPUTOPOLOGY STRUCT 437
6.37. CPUTUNE STRUCT 437
6.38. CPUTYPE STRUCT 438
6.39. CREATIONSTATUS ENUM 438
6.40. CUSTOMPROPERTY STRUCT 438
6.41. DATACENTER STRUCT 439
6.42. DATACENTERSTATUS ENUM 441
6.43. DEVICE STRUCT 442
6.44. DISK STRUCT 443
6.45. DISKATTACHMENT STRUCT 448
6.46. DISKFORMAT ENUM 449
6.47. DISKINTERFACE ENUM 449
6.48. DISKPROFILE STRUCT 450

6
 Table of Contents

6.48. DISKPROFILE STRUCT 450

6.49. DISKSNAPSHOT STRUCT 451
6.50. DISKSTATUS ENUM 456
6.51. DISKSTORAGETYPE ENUM 456
6.52. DISKTYPE ENUM 456
6.53. DISPLAY STRUCT 457
6.54. DISPLAYTYPE ENUM 458
6.55. DNS STRUCT 458
6.56. DOMAIN STRUCT 459
6.57. ENTITYEXTERNALSTATUS ENUM 459
6.58. ENTITYPROFILEDETAIL STRUCT 460
6.59. ERRORHANDLING STRUCT 460
6.60. EVENT STRUCT 461
6.61. EXTERNALCOMPUTERESOURCE STRUCT 463
6.62. EXTERNALDISCOVEREDHOST STRUCT 464
6.63. EXTERNALHOST STRUCT 465
6.64. EXTERNALHOSTGROUP STRUCT 465
6.65. EXTERNALHOSTPROVIDER STRUCT 466
6.66. EXTERNALPROVIDER STRUCT 468
6.67. EXTERNALSTATUS ENUM 469
6.68. EXTERNALSYSTEMTYPE ENUM 470
6.69. EXTERNALVMIMPORT STRUCT 470
6.70. EXTERNALVMPROVIDERTYPE ENUM 472
6.71. FAULT STRUCT 472
6.72. FENCETYPE ENUM 472
6.73. FENCINGPOLICY STRUCT 473
6.74. FILE STRUCT 473
6.75. FILTER STRUCT 474
6.76. FLOPPY STRUCT 475
6.77. FOPSTATISTIC STRUCT 476
6.78. GLUSTERBRICK STRUCT 476
6.79. GLUSTERBRICKADVANCEDDETAILS STRUCT 478
6.80. GLUSTERBRICKMEMORYINFO STRUCT 480
6.81. GLUSTERBRICKSTATUS ENUM 480
6.82. GLUSTERCLIENT STRUCT 480
6.83. GLUSTERHOOK STRUCT 481
6.84. GLUSTERHOOKSTATUS ENUM 482
6.85. GLUSTERMEMORYPOOL STRUCT 482
6.86. GLUSTERSERVERHOOK STRUCT 483
6.87. GLUSTERSTATE ENUM 484
6.88. GLUSTERVOLUME STRUCT 485
6.89. GLUSTERVOLUMEPROFILEDETAILS STRUCT 486
6.90. GLUSTERVOLUMESTATUS ENUM 487
6.91. GLUSTERVOLUMETYPE ENUM 487
6.92. GRACEPERIOD STRUCT 489
6.93. GRAPHICSCONSOLE STRUCT 490
6.94. GRAPHICSTYPE ENUM 491
6.95. GROUP STRUCT 491
6.96. GUESTOPERATINGSYSTEM STRUCT 492
6.97. HARDWAREINFORMATION STRUCT 493
6.98. HIGHAVAILABILITY STRUCT 493
6.99. HOOK STRUCT 494
6.100. HOOKCONTENTTYPE ENUM 494
6.101. HOOKSTAGE ENUM 495

7
Red Hat Virtualization 4.0 REST API Guide

6.101. HOOKSTAGE ENUM 495

6.102. HOOKSTATUS ENUM 495
6.103. HOST STRUCT 495
6.104. HOSTDEVICE STRUCT 504
6.105. HOSTDEVICEPASSTHROUGH STRUCT 505
6.106. HOSTNIC STRUCT 505
6.107. HOSTNICVIRTUALFUNCTIONSCONFIGURATION STRUCT 509
6.108. HOSTPROTOCOL ENUM 510
6.109. HOSTSTATUS ENUM 510
6.110. HOSTSTORAGE STRUCT 513
6.111. HOSTTYPE ENUM 515
6.112. HOSTEDENGINE STRUCT 515
6.113. ICON STRUCT 516
6.114. IDENTIFIED STRUCT 517
6.115. IMAGE STRUCT 517
6.116. IMAGETRANSFER STRUCT 518
6.117. IMAGETRANSFERPHASE ENUM 519
6.118. INHERITABLEBOOLEAN ENUM 521
6.119. INITIALIZATION STRUCT 521
6.120. INSTANCETYPE STRUCT 523
6.121. IO STRUCT 530
6.122. IP STRUCT 530
6.123. IPADDRESSASSIGNMENT STRUCT 531
6.124. IPVERSION ENUM 532
6.125. ISCSIBOND STRUCT 532
6.126. ISCSIDETAILS STRUCT 533
6.127. JOB STRUCT 534
6.128. JOBSTATUS ENUM 535
6.129. KATELLOERRATUM STRUCT 536
6.130. KDUMPSTATUS ENUM 538
6.131. KERNEL STRUCT 538
6.132. KSM STRUCT 538
6.133. LOGSEVERITY ENUM 539
6.134. LOGICALUNIT STRUCT 539
6.135. LUNSTATUS ENUM 541
6.136. MAC STRUCT 541
6.137. MACPOOL STRUCT 541
6.138. MEMORYOVERCOMMIT STRUCT 543
6.139. MEMORYPOLICY STRUCT 543
6.140. MESSAGEBROKERTYPE ENUM 543
6.141. METHOD STRUCT 544
6.142. MIGRATEONERROR ENUM 544
6.143. MIGRATIONBANDWIDTH STRUCT 544
6.144. MIGRATIONBANDWIDTHASSIGNMENTMETHOD ENUM 545
6.145. MIGRATIONOPTIONS STRUCT 545
6.146. MIGRATIONPOLICY STRUCT 546
6.147. NETWORK STRUCT 546
6.148. NETWORKATTACHMENT STRUCT 549
6.149. NETWORKCONFIGURATION STRUCT 554
6.150. NETWORKFILTER STRUCT 554
6.151. NETWORKLABEL STRUCT 555
6.152. NETWORKPLUGINTYPE ENUM 556
6.153. NETWORKSTATUS ENUM 556
6.154. NETWORKUSAGE ENUM 556

8
 Table of Contents

6.154. NETWORKUSAGE ENUM 556

6.155. NFSPROFILEDETAIL STRUCT 557
6.156. NFSVERSION ENUM 557
6.157. NIC STRUCT 558
6.158. NICCONFIGURATION STRUCT 560
6.159. NICINTERFACE ENUM 561
6.160. NICSTATUS ENUM 561
6.161. NUMANODE STRUCT 562
6.162. NUMANODEPIN STRUCT 563
6.163. NUMATUNEMODE ENUM 563
6.164. OPENSTACKIMAGE STRUCT 564
6.165. OPENSTACKIMAGEPROVIDER STRUCT 564
6.166. OPENSTACKNETWORK STRUCT 566
6.167. OPENSTACKNETWORKPROVIDER STRUCT 566
6.168. OPENSTACKNETWORKPROVIDERTYPE ENUM 568
6.169. OPENSTACKPROVIDER STRUCT 569
6.170. OPENSTACKSUBNET STRUCT 570
6.171. OPENSTACKVOLUMEPROVIDER STRUCT 571
6.172. OPENSTACKVOLUMETYPE STRUCT 573
6.173. OPENSTACKVOLUMEAUTHENTICATIONKEY STRUCT 573
6.174. OPENSTACKVOLUMEAUTHENTICATIONKEYUSAGETYPE ENUM 574
6.175. OPERATINGSYSTEM STRUCT 575
6.176. OPERATINGSYSTEMINFO STRUCT 576
6.177. OPTION STRUCT 576
6.178. OSTYPE ENUM 577
6.179. PACKAGE STRUCT 579
6.180. PAYLOAD STRUCT 579
6.181. PAYLOADENCODING ENUM 579
6.182. PERMISSION STRUCT 580
6.183. PERMIT STRUCT 581
6.184. PMPROXY STRUCT 582
6.185. PMPROXYTYPE ENUM 582
6.186. POLICYUNITTYPE ENUM 582
6.187. PORTMIRRORING STRUCT 582
6.188. POWERMANAGEMENT STRUCT 583
6.189. POWERMANAGEMENTSTATUS ENUM 584
6.190. PRODUCT STRUCT 584
6.191. PRODUCTINFO STRUCT 585
6.192. PROFILEDETAIL STRUCT 586
6.193. PROPERTY STRUCT 586
6.194. PROXYTICKET STRUCT 587
6.195. QOS STRUCT 587
6.196. QOSTYPE ENUM 591
6.197. QUOTA STRUCT 592
6.198. QUOTACLUSTERLIMIT STRUCT 594
6.199. QUOTAMODETYPE ENUM 595
6.200. QUOTASTORAGELIMIT STRUCT 595
6.201. RANGE STRUCT 596
6.202. RATE STRUCT 596
6.203. REPORTEDCONFIGURATION STRUCT 597
6.204. REPORTEDDEVICE STRUCT 597
6.205. REPORTEDDEVICETYPE ENUM 598
6.206. RESOLUTIONTYPE ENUM 598
6.207. RNGDEVICE STRUCT 598

9
Red Hat Virtualization 4.0 REST API Guide

6.207. RNGDEVICE STRUCT 598

6.208. RNGSOURCE ENUM 599
6.209. ROLE STRUCT 599
6.210. ROLETYPE ENUM 600
6.211. SCHEDULINGPOLICY STRUCT 600
6.212. SCHEDULINGPOLICYUNIT STRUCT 601
6.213. SCSIGENERICIO ENUM 602
6.214. SELINUX STRUCT 602
6.215. SELINUXMODE ENUM 603
6.216. SERIALNUMBER STRUCT 603
6.217. SERIALNUMBERPOLICY ENUM 603
6.218. SESSION STRUCT 604
6.219. SKIPIFCONNECTIVITYBROKEN STRUCT 605
6.220. SKIPIFSDACTIVE STRUCT 606
6.221. SNAPSHOT STRUCT 606
6.222. SNAPSHOTSTATUS ENUM 617
6.223. SNAPSHOTTYPE ENUM 617
6.224. SPECIALOBJECTS STRUCT 617
6.225. SPM STRUCT 618
6.226. SPMSTATUS ENUM 618
6.227. SSH STRUCT 618
6.228. SSHAUTHENTICATIONMETHOD ENUM 619
6.229. SSHPUBLICKEY STRUCT 619
6.230. SSO STRUCT 620
6.231. SSOMETHOD ENUM 620
6.232. STATISTIC STRUCT 621
6.233. STATISTICKIND ENUM 623
6.234. STATISTICUNIT ENUM 623
6.235. STEP STRUCT 624
6.236. STEPENUM ENUM 625
6.237. STEPSTATUS ENUM 626
6.238. STORAGECONNECTION STRUCT 627
6.239. STORAGECONNECTIONEXTENSION STRUCT 629
6.240. STORAGEDOMAIN STRUCT 630
6.241. STORAGEDOMAINSTATUS ENUM 633
6.242. STORAGEDOMAINTYPE ENUM 634
6.243. STORAGEFORMAT ENUM 634
6.244. STORAGETYPE ENUM 635
6.245. SWITCHTYPE ENUM 636
6.246. TAG STRUCT 636
6.247. TEMPLATE STRUCT 637
6.248. TEMPLATESTATUS ENUM 643
6.249. TEMPLATEVERSION STRUCT 644
6.250. TICKET STRUCT 644
6.251. TIMEZONE STRUCT 645
6.252. TRANSPARENTHUGEPAGES STRUCT 645
6.253. TRANSPORTTYPE ENUM 645
6.254. UNMANAGEDNETWORK STRUCT 646
6.255. USB STRUCT 646
6.256. USBTYPE ENUM 647
6.257. USER STRUCT 647
6.258. VALUE STRUCT 649
6.259. VALUETYPE ENUM 649
6.260. VCPUPIN STRUCT 650

10
 Table of Contents

6.260. VCPUPIN STRUCT 650

6.261. VENDOR STRUCT 650
6.262. VERSION STRUCT 650
6.263. VIRTIOSCSI STRUCT 651
6.264. VIRTUALNUMANODE STRUCT 651
6.265. VLAN STRUCT 653
6.266. VM STRUCT 653
6.267. VMAFFINITY ENUM 663
6.268. VMBASE STRUCT 664
6.269. VMDEVICETYPE ENUM 669
6.270. VMPLACEMENTPOLICY STRUCT 670
6.271. VMPOOL STRUCT 670
6.272. VMPOOLTYPE ENUM 672
6.273. VMSTATUS ENUM 672
6.274. VMSUMMARY STRUCT 675
6.275. VMTYPE ENUM 675
6.276. VNICPASSTHROUGH STRUCT 676
6.277. VNICPASSTHROUGHMODE ENUM 676
6.278. VNICPROFILE STRUCT 676
6.279. VOLUMEGROUP STRUCT 677
6.280. WATCHDOG STRUCT 678
6.281. WATCHDOGACTION ENUM 679
6.282. WATCHDOGMODEL ENUM 680
6.283. WEIGHT STRUCT 680

.APPENDIX
. . . . . . . . . A.
. . .PRIMITIVE
. . . . . . . . . TYPES
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .682
............
A.1. STRING PRIMITIVE 682
A.2. BOOLEAN PRIMITIVE 682
A.3. INTEGER PRIMITIVE 682
A.4. DECIMAL PRIMITIVE 683
A.5. DATE PRIMITIVE 683

11
Red Hat Virtualization 4.0 REST API Guide

12
 CHAPTER 1. INTRODUCTION

CHAPTER 1. INTRODUCTION
The Red Hat Virtualization Manager provides a Representational State Transfer (REST) API. The
API provides software developers and system administrators with control over their Red Hat
Virtualization environment outside of the standard web interface. The API is useful for developers
and administrators to integrate the functionality of a Red Hat Virtualization environment with custom
scripts 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 HTTP
protocol can use the API.

Self descriptive - Client applications require minimal knowledge of the virtualization

infrastructure, as many details are discovered at runtime.

Resource-based model - The resource-based REST model provides a natural way to manage a
virtualization platform.

This provides developers and administrators with the ability to:

Integrate with enterprise IT systems.

Integrate with third-party virtualization software.

Perform automated maintenance or error-checking tasks.

Automate repetitive tasks in a Red Hat Virtualization environment with scripts.

This documentation acts as a reference for the Red Hat Virtualization API. It aims to provide
developers and administrators with instructions and examples to help harness the functionality of
their 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 a
specific service and their representations. A resource representation is a key abstraction of
information that corresponds to one specific managed element on a server. A client sends a request
to a server element located at a Uniform Resource Identifier (URI) and performs operations with
standard HTTP methods, such as GET, POST, PUT, and DELETE. This provides a stateless
communication between the client and server where each request acts independently of any other
request, 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 .

13
Red Hat Virtualization 4.0 REST API Guide

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 the
Hypertext Transfer Protocol at http://www.ietf.org/rfc/rfc2616.txt.

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

14
 CHAPTER 2. AUTHENTICATION AND SECURITY

CHAPTER 2. AUTHENTICATION AND SECURITY

2.1. TLS/SSL CERTIFICATION

The Red Hat Virtualization API requires Hypertext Transfer Protocol Secure (HTTPS) [1] for secure
interaction with client software, such as the SDK and CLI components. This involves obtaining the
CA 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 client
machine using one of these methods:

Method 1
The preferred method for obtaining the CA certificate is to use the openssl s_client
command line tool to perform a real TLS handshake with the server, and then extract the
certificates 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.23416
verify 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-----
MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
-----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-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----

The text between the -----BEGIN CERTIFICATE----- and -----END

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

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

15
Red Hat Virtualization 4.0 REST API Guide

FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----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 not
obtain the correct CA certificate if it has been manually replaced by the
administrator of the server.

Method 2
If you cannot use the openssl s_client method described above, you can instead use a
command 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 on
multiple 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 the
browser’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 certification
options and save it as ca.crt.

Method 4
Log in to the Red Hat Virtualization Manager, export the certificate from the truststore, and
copy it to your client machine.

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

16
 CHAPTER 2. AUTHENTICATION AND SECURITY

2. Export the certificate from the truststore using the Java keytool management
utility:

# 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 myuser@myclient.example.com:/home/myuser/.

Each of these methods results in a certificate file named ca.crt on your client machine. You must
then 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 your
client 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 be
authenticated 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, as
described in RFC 6749.

OAuth is a sophisticated protocol, with several mechanisms for obtaining authorization and access
tokens. For use with the Red Hat Virtualization API, the only supported one is the Resource Owner
Password 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 Virtualization
Manager single sign-on service:

POST /ovirt-engine/sso/oauth/token HTTP/1.1

Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

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

Table 2.1. OAuth token request parameters

17
Red Hat Virtualization 4.0 REST API Guide

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 to
be 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 with
the 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 service
will 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 not
manipulate 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 in
the HTTP Authorization header, and using the Bearer scheme. For example, to get the list of
virtual machines, send a request like this:

GET /ovirt-engine/api/vms HTTP/1.1

Host: myengine.example.com
Accept: application/xml
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=

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

18
 CHAPTER 2. AUTHENTICATION AND SECURITY

HTTP/1.1 401 Unauthorized

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

2.2.2. Basic Authentication

Important

Basic authentication is supported only for backwards compatibility; it is deprecated since

version 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 not
include an appropriate Authorization header, the server sends a 401 Authorization
Required response:

HEAD /ovirt-engine/api HTTP/1.1

Host: myengine.example.com

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. Encode an appropriate
Red 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

==

19
Red Hat Virtualization 4.0 REST API Guide

Provide the Base64-encoded credentials as shown:

HEAD /ovirt-engine/api HTTP/1.1

Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK

Important

Basic authentication involves potentially sensitive information, such as passwords, sent

as 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 a
newline character. This breaks the header and causes a faulty request. The
Authorization header requires the encoded credentials on a single line within the
header.

2.2.3. Authentication Sessions

The API also provides authentication session support. Send an initial request with authentication
details, 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.1

Host: myengine.example.com
Authorization: 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 headers
with the JSESSIONID= value. The Authorization header is no longer needed when
using an authenticated session.

20
 CHAPTER 2. AUTHENTICATION AND SECURITY

HEAD /ovirt-engine/api HTTP/1.1

Host: myengine.example.com
Prefer: persistent-auth
Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK

HTTP/1.1 200 OK
...

3. When the session is no longer required, perform a request to the sever without the
Prefer: persistent-auth header.

HEAD /ovirt-engine/api HTTP/1.1

Host: myengine.example.com
Authorization: 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 Access
Authentication.

21
Red Hat Virtualization 4.0 REST API Guide

CHAPTER 3. QUICK START EXAMPLE

This chapter provides an example to demonstrate the REST API’s ability to setup a basic Red Hat
Virtualization 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 uses
CentOS 7 for our installation ISO example; and

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

This example uses curl to demonstrate API requests with a client application. Note that any
application capable of HTTP requests can substitute for curl.

Important

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

Important

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

Note

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

Note

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

3.1. EXAMPLE: ACCESS API ENTRY POINT

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

22
 CHAPTER 3. QUICK START EXAMPLE

GET /ovirt-engine/api HTTP/1.1

Version: 4
Accept: application/xml

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

GET /ovirt-engine/api/v4 HTTP/1.1

Accept: 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 result will be an object of type Api:

<api>
<link href="/ovirt-engine/api/clusters" rel="clusters"/>
<link href="/ovirt-engine/api/datacenters" rel="datacenters"/>
...
<product_info>
<name>oVirt Engine</name>
<vendor>ovirt.org</vendor>
<version>
<build>0</build>
<full_version>4.0.0-0.0.el7</full_version>
<major>4</major>
<minor>0</minor>
<revision>0</revision>
</version>
</product_info>
<special_objects>
<blank_template href="..." id="..."/>
<root_tag href="..." id="..."/>
</special_objects>
<summary>
<hosts>
<active>23</active>
<total>30</total>
</hosts>
<storage_domains>
<active>5</active>
<total>6</total>
</storage_domains>
<users>
<active>12</active>
<total>102</total>
</users>
<vms>
<active>253</active>

23
Red Hat Virtualization 4.0 REST API Guide

<total>545</total>
</vms>
</summary>
<time>2016-10-06T15:38:18.548+02:00</time>
</api>

Important

When neither the header nor the URL prefix are used, the server will automatically select
a version. The default is version 4. You can change the default version using the
ENGINE_API_DEFAULT_VERSION configuration parameter:

# echo "ENGINE_API_DEFAULT_VERSION=3" > \

/etc/ovirt-engine/engine.conf.d/99-set-default-version.conf
# systemctl restart ovirt-engine

Changing this parameter affects all users of the API that don’t specify the version
explicitly.

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

The entry point also contains other data such as product_info, special_objects and summary. This
data is covered in chapters outside this example.

3.2. EXAMPLE: LIST DATA CENTERS

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

The following request retrieves a representation of the data centers:

GET /ovirt-engine/api/datacenters HTTP/1.1

Accept: 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/datacenters

The result will be a list of objects of type DataCenter:

<data_centers>
<data_center href="/ovirt-engine/api/datacenters/001" id="001">
<name>Default</name>
<description>The default Data Center</description>

24
 CHAPTER 3. QUICK START EXAMPLE

<link href="/ovirt-engine/api/datacenters/001/clusters"
rel="clusters"/>
<link href="/ovirt-engine/api/datacenters/001/storagedomains"
rel="storagedomains"/>
...
<local>false</local>
<quota_mode>disabled</quota_mode>
<status>up</status>
<supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</data_center>
...
</data_centers>

Note the id of your Default data center. It identifies this data center in relation to other resources
of your virtual environment.

The data center also contains a link to the service that manages the storage domains attached to
the data center:

<link href="/ovirt-engine/api/datacenters/001/storagedomains"
rel="storagedomains"/>

That service is used to attach storage domains from the main storagedomains collection, which
this example covers later.

3.3. EXAMPLE: LIST HOST CLUSTERS

Red Hat Virtualization creates a Default hosts cluster on installation. This example uses the
Default cluster to group resources in your Red Hat Virtualization environment.

The following request retrieves a representation of the cluster collection:

GET /ovirt-engine/api/clusters HTTP/1.1

Accept: 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/clusters

25
Red Hat Virtualization 4.0 REST API Guide

The result will be a list of objects of type Cluster:

<clusters>
<cluster href="/ovirt-engine/api/clusters/002" id="002">
<name>Default</name>
<description>The default server cluster</description>
<link href="/ovirt-engine/api/clusters/002/networks" rel="networks"/>
<link href="/ovirt-engine/api/clusters/002" rel="permissions"/>
...
<cpu>
<architecture>x86_64</architecture>
<type>Intel Conroe Family</type>
</cpu>
<version>
<major>4</major>
<minor>0</minor>
</version>
<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
</cluster>
...
</clusters>

Note the id of your Default host cluster. It identifies this host cluster in relation to other resources
of your virtual environment.

The Default cluster is associated with the Default data center through a relationship using the
id and href attributes of the data_center link:

<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>

The networks link is a reference to the service that manages the networks associated to this
cluster. The next section examines the networks collection in more detail.

3.4. EXAMPLE: LIST LOGICAL NETWORKS

Red Hat Virtualization creates a default ovirtmgmt network on installation. This network acts as
the management network for Red Hat Virtualization Manager to access hosts.

This network is associated with our Default cluster and is a member of the Default data center.
This example uses the ovirtmgmt network to connect our virtual machines.

The following request retrieves the list of logical networks:

GET /ovirt-engine/api/networks HTTP/1.1

Accept: application/xml

Same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \

26
 CHAPTER 3. QUICK START EXAMPLE

--header 'Accept: application/xml' \

--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/networks

The result will be a list of objects of type Network:

<networks>
<network href="/ovirt-engine/api/networks/003" id="003">
<name>ovirtmgmt</name>
<description>Management Network</description>
<link href="/ovirt-engine/api/networks/003/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/networks/003/vnicprofiles"
rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/003/networklabels"
rel="networklabels"/>
<mtu>0</mtu>
<stp>false</stp>
<usages>
<usage>vm</usage>
</usages>
<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
</network>
...
</networks>

The ovirtmgmt network is attached to the Default data center through a relationship using the
data center’s id.

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

3.5. EXAMPLE: LIST HOSTS

This example retrieves the list of hosts and shows a host named myhost registered with the
virtualization environment:

GET /ovirt-engine/api/hosts HTTP/1.1

Accept: 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/hosts

The result will be a list of objects of type Host:

<hosts>
<host href="/ovirt-engine/api/hosts/004" id="004">

27
Red Hat Virtualization 4.0 REST API Guide

<name>myhost</name>
<link href="/ovirt-engine/api/hosts/004/nics" rel="nics"/>
...
<address>node40.example.com</address>
<cpu>
<name>Intel Core Processor (Haswell, no TSX)</name>
<speed>3600</speed>
<topology>
<cores>1</cores>
<sockets>2</sockets>
<threads>1</threads>
</topology>
</cpu>
<memory>8371830784</memory>
<os>
<type>RHEL</type>
<version>
<full_version>7 - 2.1511.el7.centos.2.10</full_version>
<major>7</major>
</version>
</os>
<port>54321</port>
<status>up</status>
<cluster href="/ovirt-engine/api/clusters/002" id="002"/>
</host>
...
</hosts>

Note the id of your host. It identifies this host in relation to other resources of your virtual
environment.

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

3.6. EXAMPLE: CREATE NFS DATA STORAGE

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

You can enable the wipe after delete option by default on the storage domain. To configure this
specify wipe_after_delete in the POST request. This option can be edited after the domain is
created, but doing so will not change the wipe after delete property of disks that already exist.

The request should be like this:

POST /ovirt-engine/api/storagedomains HTTP/1.1

Accept: application/xml
Content-type: application/xml

And the request body should be like this:

<storage_domain>
<name>mydata</name>
<type>data</type>

28
 CHAPTER 3. QUICK START EXAMPLE

<description>My data</description>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/mydata</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>

The same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
<name>mydata</name>
<description>My data</description>
<type>data</type>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/mydata</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains

The server uses host myhost to create a NFS data storage domain called mydata with an export
path of mynfs.example.com:/exports/mydata. The API also returns the following
representation of the newly created storage domain resource (of type StorageDomain):

<storage_domain href="/ovirt-engine/api/storagedomains/005" id="005">

<name>mydata</name>
<description>My data</description>
<available>42949672960</available>
<committed>0</committed>
<master>false</master>
<status>unattached</status>
<storage>
<address>mynfs.example.com</address>
<path>/exports/mydata</path>
<type>nfs</type>
</storage>
<storage_format>v3</storage_format>
<type>data</type>
<used>9663676416</used>

29
Red Hat Virtualization 4.0 REST API Guide

</storage_domain>

3.7. EXAMPLE: CREATE NFS ISO STORAGE

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

The request should be like this:

POST /ovirt-engine/api/storagedomains HTTP/1.1

Accept: application/xml
Content-type: application/xml

And the request body should be like this:

<storage_domain>
<name>myisos</name>
<description>My ISOs</description>
<type>iso</type>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/myisos</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>

The same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
<name>myisos</name>
<description>My ISOs</description>
<type>iso</type>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/myisos</path>
</storage>
<host>
<name>myhost</name>

30
 CHAPTER 3. QUICK START EXAMPLE

</host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains

The server uses host myhost to create a NFS ISO storage domain called myisos with an export
path of mynfs.example.com:/exports/myisos. The API also returns the following
representation of the newly created storage domain resource (of type StorageDomain):

<storage_domain href="/ovirt-engine/api/storagedomains/006" id="006">

<name>myiso</name>
<description>My ISOs</description>
<available>42949672960</available>
<committed>0</committed>
<master>false</master>
<status>unattached</status>
<storage>
<address>mynfs.example.com</address>
<path>/exports/myisos</path>
<type>nfs</type>
</storage>
<storage_format>v1</storage_format>
<type>iso</type>
<used>9663676416</used>
</storage_domain>

3.8. EXAMPLE: ATTACH STORAGE DOMAINS TO DATA CENTER

The following example attaches the mydata and myisos storage domains to the Default data
center.

To attach the mydata storage domain, send a request like this:

POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1

Accept: application/xml
Content-type: application/xml

With a request body like this:

<storage_domain>
<name>mydata</name>
</storage_domain>

Same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>

31
Red Hat Virtualization 4.0 REST API Guide

<name>mydata</name>
</storage_domain>
' \
https://myengine.example.com/ovirt-
engine/api/datacenters/001/storagedomains

To attach the myisos storage domain, send a request like this:

POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1

Accept: application/xml
Content-type: application/xml

With a request body like this:

<storage_domain>
<name>myisos</name>
</storage_domain>

Same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
<name>myisos</name>
</storage_domain>
' \
https://myengine.example.com/ovirt-
engine/api/datacenters/001/storagedomains

3.9. EXAMPLE: CREATE VIRTUAL MACHINE

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

The request should be contain an object of type Vm describing the virtual machine to create:

POST /ovirt-engine/api/vms HTTP/1.1

Accept: application/xml
Content-type: application/xml

And the request body should be like this:

<vm>
<name>myvm</name>
<description>My VM</description>
<cluster>
<name>Default</name>

32
 CHAPTER 3. QUICK START EXAMPLE

</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
</os>
</vm>

Same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<vm>
<name>myvm</name>
<description>My VM</description>
<cluster>
<name>Default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
</os>
</vm>
' \
https://myengine.example.com/ovirt-engine/api/vms

The response body will be an object of the Vm type:

<vm href="/ovirt-engine/api/vms/007" id="007">

<name>myvm</name>
<link href="/ovirt-engine/api/vms/007/diskattachments"
rel="diskattachments"/>
<link href="/ovirt-engine/api/vms/007/nics" rel="nics"/>
...
<cpu>
<architecture>x86_64</architecture>
<topology>

33
Red Hat Virtualization 4.0 REST API Guide

<cores>1</cores>
<sockets>1</sockets>
<threads>1</threads>
</topology>
</cpu>
<memory>1073741824</memory>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
<type>other</type>
</os>
<type>desktop</type>
<cluster href="/ovirt-engine/api/clusters/002" id="002"/>
<status>down</status>
<original_template href="/ovirt-engine/api/templates/000" id="00"/>
<template href="/ovirt-engine/api/templates/000" id="000"/>
</vm>

3.10. EXAMPLE: CREATE A VIRTUAL MACHINE NIC

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

The request should be like this:

POST /ovirt-engine/api/vms/007/nics HTTP/1.1

Content-Type: application/xml
Accept: application/xml

The request body should contain an object of type Nic describing the NIC to be created:

<nic>
<name>mynic</name>
<description>My network interface card</description>
</nic>

Same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<nic>
<name>mynic</name>

34
 CHAPTER 3. QUICK START EXAMPLE

<description>My network interface card</description>

</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/nics

3.11. EXAMPLE: CREATE VIRTUAL DISK

The following example creates an 8 GiB copy-on-write disk for the example virtual machine.

The request should be like this:

POST /ovirt-engine/api/vms/007/diskattachments HTTP/1.1

Content-Type: application/xml
Accept: application/xml

The request body should be an object of type DiskAttachment describing the disk and how it will be
attached to the virtual machine:

<disk_attachment>
<bootable>false</bootable>
<interface>virtio</interface>
<active>true</active>
<disk>
<description>My disk</description>
<format>cow</format>
<name>mydisk</name>
<provisioned_size>8589934592</provisioned_size>
<storage_domains>
<storage_domain>
<name>mydata</name>
</storage_domain>
</storage_domains>
</disk>
</disk_attachment>

Same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<disk_attachment>
<bootable>false</bootable>
<interface>virtio</interface>
<active>true</active>
<disk>
<description>My disk</description>
<format>cow</format>
<name>mydisk</name>
<provisioned_size>8589934592</provisioned_size>

35
Red Hat Virtualization 4.0 REST API Guide

<storage_domains>
<storage_domain>
<name>mydata</name>
</storage_domain>
</storage_domains>
</disk>
</disk_attachment>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/diskattachments

The storage_domains attribute tells the API to store the disk on the mydata storage domain.

3.12. EXAMPLE: ATTACH ISO IMAGE TO VIRTUAL MACHINE

The boot media for our example virtual machine requires an CD-ROM or DVD ISO image for an
operating system installation. This example uses a CentOS 7 image for installation.

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

Once the ISO is uploaded, an API can be used to request the list of files from the ISO storage
domain:

GET /ovirt-engine/api/storagedomains/006/files HTTP/1.1

Accept: application/xml

Same request, using the curl command:

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

The server returns the following list of objects of type File, one for each available ISO (or floppy)
image:

<files>
<file href="..." id="CentOS-7-x86_64-Minimal.iso">
<name>CentOS-7-x86_64-Minimal.iso</name>
</file>
...
</files>

An API user attaches the CentOS-7-x86_64-Minimal.iso to our example virtual machine.

Attaching an ISO image is equivalent to using the Change CD button in the administration or user
portal applications.

The request should be like this:

PUT /ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-
000000000000 HTTP/1.1

36
 CHAPTER 3. QUICK START EXAMPLE

Accept: application/xml
Content-type: application/xml

The request body should be an object of type Cdrom containing an inner file attribute to indicate
the identifier of the ISO (or floppy) image:

<cdrom>
<file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom>

Same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request PUT \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<cdrom>
<file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/cdroms/00000000-
0000-0000-0000-000000000000

For more details see the documentation of the service that manages virtual machine CD-ROMS.

3.13. EXAMPLE: START THE VIRTUAL MACHINE

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

The request should be like this:

POST /ovirt-engine/api/vms/007/start HTTP/1.1

Accept: application/xml
Content-type: application/xml

The request body should be like this:

<action>
<vm>
<os>
<boot>
<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm>
</action>

37
Red Hat Virtualization 4.0 REST API Guide

Same request, using the curl command:

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<action>
<vm>
<os>
<boot>
<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm>
</action>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/start

The additional request body sets the virtual machine’s boot device to CD-ROM for this boot only.
This enables the virtual machine to install the operating system from the attached ISO image. The
boot device reverts back to disk for all future boots.

38
 CHAPTER 4. REQUESTS

CHAPTER 4. REQUESTS
This section enumerates all the requests that are available in the API.

POST /affinitylabels

GET /affinitylabels

GET /affinitylabels/{label:id}

PUT /affinitylabels/{label:id}

DELETE /affinitylabels/{label:id}

POST /affinitylabels/{label:id}/hosts

GET /affinitylabels/{label:id}/hosts

DELETE /affinitylabels/{label:id}/hosts/{host:id}

GET /affinitylabels/{label:id}/hosts/{host:id}

POST /affinitylabels/{label:id}/vms

GET /affinitylabels/{label:id}/vms

DELETE /affinitylabels/{label:id}/vms/{vm:id}

GET /affinitylabels/{label:id}/vms/{vm:id}

POST /bookmarks

GET /bookmarks

GET /bookmarks/{bookmark:id}

PUT /bookmarks/{bookmark:id}

DELETE /bookmarks/{bookmark:id}

GET /clusterlevels

GET /clusterlevels/{level:id}

POST /clusters

GET /clusters

GET /clusters/{cluster:id}

PUT /clusters/{cluster:id}

DELETE /clusters/{cluster:id}

POST /clusters/{cluster:id}/affinitygroups

GET /clusters/{cluster:id}/affinitygroups

GET /clusters/{cluster:id}/affinitygroups/{group:id}

PUT /clusters/{cluster:id}/affinitygroups/{group:id}

39
Red Hat Virtualization 4.0 REST API Guide

DELETE /clusters/{cluster:id}/affinitygroups/{group:id}

POST /clusters/{cluster:id}/affinitygroups/{group:id}/vms

GET /clusters/{cluster:id}/affinitygroups/{group:id}/vms

DELETE /clusters/{cluster:id}/affinitygroups/{group:id}/vms/{vm:id}

POST /clusters/{cluster:id}/cpuprofiles

GET /clusters/{cluster:id}/cpuprofiles

GET /clusters/{cluster:id}/cpuprofiles/{profile:id}

DELETE /clusters/{cluster:id}/cpuprofiles/{profile:id}

GET /clusters/{cluster:id}/glusterhooks

GET /clusters/{cluster:id}/glusterhooks/{hook:id}

DELETE /clusters/{cluster:id}/glusterhooks/{hook:id}

POST /clusters/{cluster:id}/glusterhooks/{hook:id}/disable

POST /clusters/{cluster:id}/glusterhooks/{hook:id}/enable

POST /clusters/{cluster:id}/glusterhooks/{hook:id}/resolve

POST /clusters/{cluster:id}/glustervolumes

GET /clusters/{cluster:id}/glustervolumes

GET /clusters/{cluster:id}/glustervolumes/{volume:id}

DELETE /clusters/{cluster:id}/glustervolumes/{volume:id}

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/getprofilestatistics

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks

GET /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks

DELETE /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/activate

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/migrate

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/stopmigrate

GET /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}

DELETE /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/replace

GET /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/statistics

GET /clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/statistics/{statistic:id}

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/rebalance

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/resetalloptions

40
 CHAPTER 4. REQUESTS

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/resetoption

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/setoption

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/start

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/startprofile

GET /clusters/{cluster:id}/glustervolumes/{volume:id}/statistics

GET /clusters/{cluster:id}/glustervolumes/{volume:id}/statistics/{statistic:id}

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/stop

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/stopprofile

POST /clusters/{cluster:id}/glustervolumes/{volume:id}/stoprebalance

GET /clusters/{cluster:id}/networkfilters

GET /clusters/{cluster:id}/networkfilters/{networkfilter:id}

POST /clusters/{cluster:id}/networks

GET /clusters/{cluster:id}/networks

GET /clusters/{cluster:id}/networks/{network:id}

DELETE /clusters/{cluster:id}/networks/{network:id}

PUT /clusters/{cluster:id}/networks/{network:id}

POST /clusters/{cluster:id}/permissions

GET /clusters/{cluster:id}/permissions

GET /clusters/{cluster:id}/permissions/{permission:id}

DELETE /clusters/{cluster:id}/permissions/{permission:id}

POST /clusters/{cluster:id}/resetemulatedmachine

POST /cpuprofiles

GET /cpuprofiles

GET /cpuprofiles/{profile:id}

PUT /cpuprofiles/{profile:id}

DELETE /cpuprofiles/{profile:id}

POST /cpuprofiles/{profile:id}/permissions

GET /cpuprofiles/{profile:id}/permissions

GET /cpuprofiles/{profile:id}/permissions/{permission:id}

DELETE /cpuprofiles/{profile:id}/permissions/{permission:id}

POST /datacenters

GET /datacenters

41
Red Hat Virtualization 4.0 REST API Guide

GET /datacenters/{datacenter:id}

PUT /datacenters/{datacenter:id}

DELETE /datacenters/{datacenter:id}

POST /datacenters/{datacenter:id}/clusters

GET /datacenters/{datacenter:id}/clusters

GET /datacenters/{datacenter:id}/clusters/{cluster:id}

PUT /datacenters/{datacenter:id}/clusters/{cluster:id}

DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}

PUT /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}

DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}/vms

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}/vms

DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/affinitygroups/{group:id}/vms/{vm:id}

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/cpuprofiles

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/cpuprofiles

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/cpuprofiles/{profile:id}

DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/cpuprofiles/{profile:id}

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}

DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}/disable

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}/enable

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glusterhooks/{hook:id}/resolve

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}

DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}

POST
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/getprofilestatistics

42
 CHAPTER 4. REQUESTS

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks

DELETE
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks

POST
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/activate

POST
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/migrate

POST
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/stopmigrate

GET
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}

DELETE
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}

POST
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/replace

GET
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/statistics

GET
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/glusterbricks/{brick:id}/statistics

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/rebalance

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/resetalloptions

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/resetoption

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/setoption

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/start

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/startprofile

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/statistics

GET
/datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/statistics/{statistic:id}

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/stop

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/stopprofile

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/glustervolumes/{volume:id}/stoprebalance

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/networkfilters

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/networkfilters/{networkfilter:id}

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/networks

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/networks

43
Red Hat Virtualization 4.0 REST API Guide

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/networks/{network:id}

DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/networks/{network:id}

PUT /datacenters/{datacenter:id}/clusters/{cluster:id}/networks/{network:id}

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/permissions

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/permissions

GET /datacenters/{datacenter:id}/clusters/{cluster:id}/permissions/{permission:id}

DELETE /datacenters/{datacenter:id}/clusters/{cluster:id}/permissions/{permission:id}

POST /datacenters/{datacenter:id}/clusters/{cluster:id}/resetemulatedmachine

POST /datacenters/{datacenter:id}/iscsibonds

GET /datacenters/{datacenter:id}/iscsibonds

GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}

PUT /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}

DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}

POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks

GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks

GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}

PUT /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}

DELETE /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}

POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/networklabels

GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/networklabels

GET
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/networklabels/{label:id}

DELETE
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/networklabels/{label:id}

POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/permissions

GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/permissions

GET
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/permissions/{permission:id}

DELETE
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/permissions/{permission:id}

POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles

GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles

GET
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}

44
 CHAPTER 4. REQUESTS

DELETE
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}

POST
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions

GET
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions

GET
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions

DELETE
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions

POST /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections

GET /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections

GET
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections/{storageconnection:id}

PUT
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections/{storageconnection:id}

DELETE
/datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections/{storageconnection:id}

POST /datacenters/{datacenter:id}/networks

GET /datacenters/{datacenter:id}/networks

GET /datacenters/{datacenter:id}/networks/{network:id}

PUT /datacenters/{datacenter:id}/networks/{network:id}

DELETE /datacenters/{datacenter:id}/networks/{network:id}

POST /datacenters/{datacenter:id}/networks/{network:id}/networklabels

GET /datacenters/{datacenter:id}/networks/{network:id}/networklabels

GET /datacenters/{datacenter:id}/networks/{network:id}/networklabels/{label:id}

DELETE /datacenters/{datacenter:id}/networks/{network:id}/networklabels/{label:id}

POST /datacenters/{datacenter:id}/networks/{network:id}/permissions

GET /datacenters/{datacenter:id}/networks/{network:id}/permissions

GET /datacenters/{datacenter:id}/networks/{network:id}/permissions/{permission:id}

DELETE /datacenters/{datacenter:id}/networks/{network:id}/permissions/{permission:id}

POST /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles

GET /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles

GET /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}

DELETE /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}

45
Red Hat Virtualization 4.0 REST API Guide

POST /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions

GET /datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions

GET
/datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}

DELETE
/datacenters/{datacenter:id}/networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}

POST /datacenters/{datacenter:id}/permissions

GET /datacenters/{datacenter:id}/permissions

GET /datacenters/{datacenter:id}/permissions/{permission:id}

DELETE /datacenters/{datacenter:id}/permissions/{permission:id}

POST /datacenters/{datacenter:id}/qoss

GET /datacenters/{datacenter:id}/qoss

GET /datacenters/{datacenter:id}/qoss/{qos:id}

PUT /datacenters/{datacenter:id}/qoss/{qos:id}

DELETE /datacenters/{datacenter:id}/qoss/{qos:id}

POST /datacenters/{datacenter:id}/quotas

GET /datacenters/{datacenter:id}/quotas

GET /datacenters/{datacenter:id}/quotas/{quota:id}

PUT /datacenters/{datacenter:id}/quotas/{quota:id}

DELETE /datacenters/{datacenter:id}/quotas/{quota:id}

POST /datacenters/{datacenter:id}/quotas/{quota:id}/permissions

GET /datacenters/{datacenter:id}/quotas/{quota:id}/permissions

GET /datacenters/{datacenter:id}/quotas/{quota:id}/permissions/{permission:id}

DELETE /datacenters/{datacenter:id}/quotas/{quota:id}/permissions/{permission:id}

POST /datacenters/{datacenter:id}/quotas/{quota:id}/quotaclusterlimits

GET /datacenters/{datacenter:id}/quotas/{quota:id}/quotaclusterlimits

GET /datacenters/{datacenter:id}/quotas/{quota:id}/quotaclusterlimits/{limit:id}

DELETE /datacenters/{datacenter:id}/quotas/{quota:id}/quotaclusterlimits/{limit:id}

POST /datacenters/{datacenter:id}/quotas/{quota:id}/quotastoragelimits

GET /datacenters/{datacenter:id}/quotas/{quota:id}/quotastoragelimits

GET /datacenters/{datacenter:id}/quotas/{quota:id}/quotastoragelimits/{limit:id}

DELETE /datacenters/{datacenter:id}/quotas/{quota:id}/quotastoragelimits/{limit:id}

POST /datacenters/{datacenter:id}/storagedomains

46
 CHAPTER 4. REQUESTS

GET /datacenters/{datacenter:id}/storagedomains

GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}

DELETE /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}

POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/activate

POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/deactivate

POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks

GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks

GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}

DELETE /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}

POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/copy

POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/export

POST /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/move

POST
/datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/permissions

GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/permissions

GET
/datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/permissions/{permission:id}

DELETE
/datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/permissions/{permission:id}

GET /datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/statistics

GET
/datacenters/{datacenter:id}/storagedomains/{storagedomain:id}/disks/{disk:id}/statistics/{statistic:id}

POST /diskprofiles

GET /diskprofiles

GET /diskprofiles/{diskprofile:id}

PUT /diskprofiles/{diskprofile:id}

DELETE /diskprofiles/{diskprofile:id}

POST /diskprofiles/{diskprofile:id}/permissions

GET /diskprofiles/{diskprofile:id}/permissions

GET /diskprofiles/{diskprofile:id}/permissions/{permission:id}

DELETE /diskprofiles/{diskprofile:id}/permissions/{permission:id}

POST /disks

GET /disks

GET /disks/{disk:id}

47
Red Hat Virtualization 4.0 REST API Guide

DELETE /disks/{disk:id}

POST /disks/{disk:id}/copy

POST /disks/{disk:id}/export

POST /disks/{disk:id}/move

POST /disks/{disk:id}/permissions

GET /disks/{disk:id}/permissions

GET /disks/{disk:id}/permissions/{permission:id}

DELETE /disks/{disk:id}/permissions/{permission:id}

GET /disks/{disk:id}/statistics

GET /disks/{disk:id}/statistics/{statistic:id}

GET /domains

GET /domains/{domain:id}

GET /domains/{domain:id}/groups

GET /domains/{domain:id}/groups/{group:id}

GET /domains/{domain:id}/users

GET /domains/{domain:id}/users/{user:id}

POST /events

GET /events

POST /events/undelete

GET /events/{event:id}

DELETE /events/{event:id}

POST /externalhostproviders

GET /externalhostproviders

GET /externalhostproviders/{provider:id}

PUT /externalhostproviders/{provider:id}

DELETE /externalhostproviders/{provider:id}

GET /externalhostproviders/{provider:id}/certificates

GET /externalhostproviders/{provider:id}/certificates/{certificate:id}

GET /externalhostproviders/{provider:id}/computeresources

GET /externalhostproviders/{provider:id}/computeresources/{resource:id}

GET /externalhostproviders/{provider:id}/discoveredhosts

48
 CHAPTER 4. REQUESTS

GET /externalhostproviders/{provider:id}/discoveredhosts/{host:id}

GET /externalhostproviders/{provider:id}/hostgroups

GET /externalhostproviders/{provider:id}/hostgroups/{group:id}

GET /externalhostproviders/{provider:id}/hosts

GET /externalhostproviders/{provider:id}/hosts/{host:id}

POST /externalhostproviders/{provider:id}/importcertificates

POST /externalhostproviders/{provider:id}/testconnectivity

POST /externalvmimports

POST /groups

GET /groups

GET /groups/{group:id}

DELETE /groups/{group:id}

POST /groups/{group:id}/permissions

GET /groups/{group:id}/permissions

GET /groups/{group:id}/permissions/{permission:id}

DELETE /groups/{group:id}/permissions/{permission:id}

GET /groups/{group:id}/roles

GET /groups/{group:id}/roles/{role:id}

DELETE /groups/{group:id}/roles/{role:id}

PUT /groups/{group:id}/roles/{role:id}

POST /groups/{group:id}/roles/{role:id}/permits

GET /groups/{group:id}/roles/{role:id}/permits

GET /groups/{group:id}/roles/{role:id}/permits/{permit:id}

DELETE /groups/{group:id}/roles/{role:id}/permits/{permit:id}

POST /groups/{group:id}/tags

GET /groups/{group:id}/tags

GET /groups/{group:id}/tags/{tag:id}

DELETE /groups/{group:id}/tags/{tag:id}

POST /hosts

GET /hosts

GET /hosts/{host:id}

PUT /hosts/{host:id}

49
Red Hat Virtualization 4.0 REST API Guide

DELETE /hosts/{host:id}

POST /hosts/{host:id}/activate

POST /hosts/{host:id}/affinitylabels

GET /hosts/{host:id}/affinitylabels

GET /hosts/{host:id}/affinitylabels/{label:id}

DELETE /hosts/{host:id}/affinitylabels/{label:id}

POST /hosts/{host:id}/approve

POST /hosts/{host:id}/commitnetconfig

POST /hosts/{host:id}/deactivate

GET /hosts/{host:id}/devices

GET /hosts/{host:id}/devices/{device:id}

POST /hosts/{host:id}/enrollcertificate

POST /hosts/{host:id}/fence

POST /hosts/{host:id}/fenceagents

GET /hosts/{host:id}/fenceagents

GET /hosts/{host:id}/fenceagents/{agent:id}

PUT /hosts/{host:id}/fenceagents/{agent:id}

DELETE /hosts/{host:id}/fenceagents/{agent:id}

POST /hosts/{host:id}/forceselectspm

GET /hosts/{host:id}/hooks

GET /hosts/{host:id}/hooks/{hook:id}

POST /hosts/{host:id}/install

POST /hosts/{host:id}/iscsidiscover

POST /hosts/{host:id}/iscsilogin

GET /hosts/{host:id}/katelloerrata

GET /hosts/{host:id}/katelloerrata/{katelloerratum:id}

POST /hosts/{host:id}/networkattachments

GET /hosts/{host:id}/networkattachments

GET /hosts/{host:id}/networkattachments/{attachment:id}

PUT /hosts/{host:id}/networkattachments/{attachment:id}

DELETE /hosts/{host:id}/networkattachments/{attachment:id}

GET /hosts/{host:id}/nics

50
 CHAPTER 4. REQUESTS

GET /hosts/{host:id}/nics/{nic:id}

POST /hosts/{host:id}/nics/{nic:id}/networkattachments

GET /hosts/{host:id}/nics/{nic:id}/networkattachments

GET /hosts/{host:id}/nics/{nic:id}/networkattachments/{attachment:id}

PUT /hosts/{host:id}/nics/{nic:id}/networkattachments/{attachment:id}

DELETE /hosts/{host:id}/nics/{nic:id}/networkattachments/{attachment:id}

POST /hosts/{host:id}/nics/{nic:id}/networklabels

GET /hosts/{host:id}/nics/{nic:id}/networklabels

GET /hosts/{host:id}/nics/{nic:id}/networklabels/{label:id}

DELETE /hosts/{host:id}/nics/{nic:id}/networklabels/{label:id}

GET /hosts/{host:id}/nics/{nic:id}/statistics

GET /hosts/{host:id}/nics/{nic:id}/statistics/{statistic:id}

POST /hosts/{host:id}/nics/{nic:id}/updatevirtualfunctionsconfiguration

POST /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowedlabels

GET /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowedlabels

GET /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowedlabels/{label:id}

DELETE /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowedlabels/{label:id}

POST /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowednetworks

GET /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowednetworks

GET /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowednetworks/{network:id}

DELETE /hosts/{host:id}/nics/{nic:id}/virtualfunctionallowednetworks/{network:id}

GET /hosts/{host:id}/numanodes

GET /hosts/{host:id}/numanodes/{node:id}

GET /hosts/{host:id}/numanodes/{node:id}/statistics

GET /hosts/{host:id}/numanodes/{node:id}/statistics/{statistic:id}

POST /hosts/{host:id}/permissions

GET /hosts/{host:id}/permissions

GET /hosts/{host:id}/permissions/{permission:id}

DELETE /hosts/{host:id}/permissions/{permission:id}

POST /hosts/{host:id}/refresh

POST /hosts/{host:id}/setupnetworks

GET /hosts/{host:id}/statistics

51
Red Hat Virtualization 4.0 REST API Guide

GET /hosts/{host:id}/statistics/{statistic:id}

GET /hosts/{host:id}/storage

GET /hosts/{host:id}/storage/{storage:id}

POST /hosts/{host:id}/storageconnectionextensions

GET /hosts/{host:id}/storageconnectionextensions

GET /hosts/{host:id}/storageconnectionextensions/{storageconnectionextension:id}

PUT /hosts/{host:id}/storageconnectionextensions/{storageconnectionextension:id}

DELETE /hosts/{host:id}/storageconnectionextensions/{storageconnectionextension:id}

POST /hosts/{host:id}/tags

GET /hosts/{host:id}/tags

GET /hosts/{host:id}/tags/{tag:id}

DELETE /hosts/{host:id}/tags/{tag:id}

GET /hosts/{host:id}/unmanagednetworks

GET /hosts/{host:id}/unmanagednetworks/{unmanagednetwork:id}

DELETE /hosts/{host:id}/unmanagednetworks/{unmanagednetwork:id}

POST /hosts/{host:id}/unregisteredstoragedomainsdiscover

POST /hosts/{host:id}/upgrade

GET /icons

GET /icons/{icon:id}

POST /imagetransfers

GET /imagetransfers

GET /imagetransfers/{imagetransfer:id}

POST /imagetransfers/{imagetransfer:id}/extend

POST /imagetransfers/{imagetransfer:id}/finalize

POST /imagetransfers/{imagetransfer:id}/pause

POST /imagetransfers/{imagetransfer:id}/resume

POST /instancetypes

GET /instancetypes

GET /instancetypes/{instancetype:id}

PUT /instancetypes/{instancetype:id}

DELETE /instancetypes/{instancetype:id}

POST /instancetypes/{instancetype:id}/graphicsconsoles

52
 CHAPTER 4. REQUESTS

GET /instancetypes/{instancetype:id}/graphicsconsoles

GET /instancetypes/{instancetype:id}/graphicsconsoles/{console:id}

DELETE /instancetypes/{instancetype:id}/graphicsconsoles/{console:id}

POST /instancetypes/{instancetype:id}/nics

GET /instancetypes/{instancetype:id}/nics

GET /instancetypes/{instancetype:id}/nics/{nic:id}

PUT /instancetypes/{instancetype:id}/nics/{nic:id}

DELETE /instancetypes/{instancetype:id}/nics/{nic:id}

POST /instancetypes/{instancetype:id}/watchdogs

GET /instancetypes/{instancetype:id}/watchdogs

GET /instancetypes/{instancetype:id}/watchdogs/{watchdog:id}

PUT /instancetypes/{instancetype:id}/watchdogs/{watchdog:id}

DELETE /instancetypes/{instancetype:id}/watchdogs/{watchdog:id}

POST /jobs

GET /jobs

GET /jobs/{job:id}

POST /jobs/{job:id}/clear

POST /jobs/{job:id}/end

POST /jobs/{job:id}/steps

GET /jobs/{job:id}/steps

GET /jobs/{job:id}/steps/{step:id}

POST /jobs/{job:id}/steps/{step:id}/end

GET /jobs/{job:id}/steps/{step:id}/statistics

GET /jobs/{job:id}/steps/{step:id}/statistics/{statistic:id}

GET /katelloerrata

GET /katelloerrata/{katelloerratum:id}

POST /macpools

GET /macpools

GET /macpools/{macpool:id}

PUT /macpools/{macpool:id}

DELETE /macpools/{macpool:id}

GET /networkfilters

53
Red Hat Virtualization 4.0 REST API Guide

GET /networkfilters/{networkfilter:id}

POST /networks

GET /networks

GET /networks/{network:id}

PUT /networks/{network:id}

DELETE /networks/{network:id}

POST /networks/{network:id}/networklabels

GET /networks/{network:id}/networklabels

GET /networks/{network:id}/networklabels/{label:id}

DELETE /networks/{network:id}/networklabels/{label:id}

POST /networks/{network:id}/permissions

GET /networks/{network:id}/permissions

GET /networks/{network:id}/permissions/{permission:id}

DELETE /networks/{network:id}/permissions/{permission:id}

POST /networks/{network:id}/vnicprofiles

GET /networks/{network:id}/vnicprofiles

GET /networks/{network:id}/vnicprofiles/{profile:id}

DELETE /networks/{network:id}/vnicprofiles/{profile:id}

POST /networks/{network:id}/vnicprofiles/{profile:id}/permissions

GET /networks/{network:id}/vnicprofiles/{profile:id}/permissions

GET /networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}

DELETE /networks/{network:id}/vnicprofiles/{profile:id}/permissions/{permission:id}

POST /openstackimageproviders

GET /openstackimageproviders

GET /openstackimageproviders/{provider:id}

PUT /openstackimageproviders/{provider:id}

DELETE /openstackimageproviders/{provider:id}

GET /openstackimageproviders/{provider:id}/certificates

GET /openstackimageproviders/{provider:id}/certificates/{certificate:id}

GET /openstackimageproviders/{provider:id}/images

GET /openstackimageproviders/{provider:id}/images/{image:id}

POST /openstackimageproviders/{provider:id}/images/{image:id}/import

54
 CHAPTER 4. REQUESTS

POST /openstackimageproviders/{provider:id}/importcertificates

POST /openstackimageproviders/{provider:id}/testconnectivity

POST /openstacknetworkproviders

GET /openstacknetworkproviders

GET /openstacknetworkproviders/{provider:id}

PUT /openstacknetworkproviders/{provider:id}

DELETE /openstacknetworkproviders/{provider:id}

GET /openstacknetworkproviders/{provider:id}/certificates

GET /openstacknetworkproviders/{provider:id}/certificates/{certificate:id}

POST /openstacknetworkproviders/{provider:id}/importcertificates

GET /openstacknetworkproviders/{provider:id}/networks

GET /openstacknetworkproviders/{provider:id}/networks/{network:id}

POST /openstacknetworkproviders/{provider:id}/networks/{network:id}/import

POST /openstacknetworkproviders/{provider:id}/networks/{network:id}/subnets

GET /openstacknetworkproviders/{provider:id}/networks/{network:id}/subnets

GET /openstacknetworkproviders/{provider:id}/networks/{network:id}/subnets/{subnet:id}

DELETE /openstacknetworkproviders/{provider:id}/networks/{network:id}/subnets/{subnet:id}

POST /openstacknetworkproviders/{provider:id}/testconnectivity

POST /openstackvolumeproviders

GET /openstackvolumeproviders

GET /openstackvolumeproviders/{provider:id}

PUT /openstackvolumeproviders/{provider:id}

DELETE /openstackvolumeproviders/{provider:id}

POST /openstackvolumeproviders/{provider:id}/authenticationkeys

GET /openstackvolumeproviders/{provider:id}/authenticationkeys

GET /openstackvolumeproviders/{provider:id}/authenticationkeys/{key:id}

PUT /openstackvolumeproviders/{provider:id}/authenticationkeys/{key:id}

DELETE /openstackvolumeproviders/{provider:id}/authenticationkeys/{key:id}

GET /openstackvolumeproviders/{provider:id}/certificates

GET /openstackvolumeproviders/{provider:id}/certificates/{certificate:id}

POST /openstackvolumeproviders/{provider:id}/importcertificates

POST /openstackvolumeproviders/{provider:id}/testconnectivity

55
Red Hat Virtualization 4.0 REST API Guide

GET /openstackvolumeproviders/{provider:id}/volumetypes

GET /openstackvolumeproviders/{provider:id}/volumetypes/{type:id}

GET /operatingsystems

GET /operatingsystems/{operatingsystem:id}

POST /permissions

GET /permissions

GET /permissions/{permission:id}

DELETE /permissions/{permission:id}

POST /roles

GET /roles

GET /roles/{role:id}

DELETE /roles/{role:id}

PUT /roles/{role:id}

POST /roles/{role:id}/permits

GET /roles/{role:id}/permits

GET /roles/{role:id}/permits/{permit:id}

DELETE /roles/{role:id}/permits/{permit:id}

POST /schedulingpolicies

GET /schedulingpolicies

GET /schedulingpolicies/{policy:id}

PUT /schedulingpolicies/{policy:id}

DELETE /schedulingpolicies/{policy:id}

POST /schedulingpolicies/{policy:id}/balances

GET /schedulingpolicies/{policy:id}/balances

GET /schedulingpolicies/{policy:id}/balances/{balance:id}

DELETE /schedulingpolicies/{policy:id}/balances/{balance:id}

POST /schedulingpolicies/{policy:id}/filters

GET /schedulingpolicies/{policy:id}/filters

GET /schedulingpolicies/{policy:id}/filters/{filter:id}

DELETE /schedulingpolicies/{policy:id}/filters/{filter:id}

POST /schedulingpolicies/{policy:id}/weights

GET /schedulingpolicies/{policy:id}/weights

56
 CHAPTER 4. REQUESTS

GET /schedulingpolicies/{policy:id}/weights/{weight:id}

DELETE /schedulingpolicies/{policy:id}/weights/{weight:id}

GET /schedulingpolicyunits

GET /schedulingpolicyunits/{unit:id}

DELETE /schedulingpolicyunits/{unit:id}

POST /storageconnections

GET /storageconnections

GET /storageconnections/{storageconnection:id}

PUT /storageconnections/{storageconnection:id}

DELETE /storageconnections/{storageconnection:id}

POST /storagedomains

GET /storagedomains

GET /storagedomains/{storagedomain:id}

PUT /storagedomains/{storagedomain:id}

DELETE /storagedomains/{storagedomain:id}

POST /storagedomains/{storagedomain:id}/diskprofiles

GET /storagedomains/{storagedomain:id}/diskprofiles

GET /storagedomains/{storagedomain:id}/diskprofiles/{profile:id}

DELETE /storagedomains/{storagedomain:id}/diskprofiles/{profile:id}

POST /storagedomains/{storagedomain:id}/disks

GET /storagedomains/{storagedomain:id}/disks

GET /storagedomains/{storagedomain:id}/disks/{disk:id}

DELETE /storagedomains/{storagedomain:id}/disks/{disk:id}

POST /storagedomains/{storagedomain:id}/disks/{disk:id}/copy

POST /storagedomains/{storagedomain:id}/disks/{disk:id}/export

POST /storagedomains/{storagedomain:id}/disks/{disk:id}/move

POST /storagedomains/{storagedomain:id}/disks/{disk:id}/permissions

GET /storagedomains/{storagedomain:id}/disks/{disk:id}/permissions

GET /storagedomains/{storagedomain:id}/disks/{disk:id}/permissions/{permission:id}

DELETE /storagedomains/{storagedomain:id}/disks/{disk:id}/permissions/{permission:id}

GET /storagedomains/{storagedomain:id}/disks/{disk:id}/statistics

GET /storagedomains/{storagedomain:id}/disks/{disk:id}/statistics/{statistic:id}

57
Red Hat Virtualization 4.0 REST API Guide

GET /storagedomains/{storagedomain:id}/disksnapshots

GET /storagedomains/{storagedomain:id}/disksnapshots/{snapshot:id}

DELETE /storagedomains/{storagedomain:id}/disksnapshots/{snapshot:id}

GET /storagedomains/{storagedomain:id}/files

GET /storagedomains/{storagedomain:id}/files/{file:id}

GET /storagedomains/{storagedomain:id}/images

GET /storagedomains/{storagedomain:id}/images/{image:id}

POST /storagedomains/{storagedomain:id}/images/{image:id}/import

POST /storagedomains/{storagedomain:id}/isattached

POST /storagedomains/{storagedomain:id}/permissions

GET /storagedomains/{storagedomain:id}/permissions

GET /storagedomains/{storagedomain:id}/permissions/{permission:id}

DELETE /storagedomains/{storagedomain:id}/permissions/{permission:id}

POST /storagedomains/{storagedomain:id}/refreshluns

POST /storagedomains/{storagedomain:id}/storageconnections

GET /storagedomains/{storagedomain:id}/storageconnections

GET /storagedomains/{storagedomain:id}/storageconnections/{connection:id}

DELETE /storagedomains/{storagedomain:id}/storageconnections/{connection:id}

GET /storagedomains/{storagedomain:id}/templates

GET /storagedomains/{storagedomain:id}/templates/{template:id}

DELETE /storagedomains/{storagedomain:id}/templates/{template:id}

GET /storagedomains/{storagedomain:id}/templates/{template:id}/disks

GET /storagedomains/{storagedomain:id}/templates/{template:id}/disks/{disk:id}

POST /storagedomains/{storagedomain:id}/templates/{template:id}/import

POST /storagedomains/{storagedomain:id}/templates/{template:id}/register

POST /storagedomains/{storagedomain:id}/updateovfstore

GET /storagedomains/{storagedomain:id}/vms

GET /storagedomains/{storagedomain:id}/vms/{vm:id}

DELETE /storagedomains/{storagedomain:id}/vms/{vm:id}

GET /storagedomains/{storagedomain:id}/vms/{vm:id}/diskattachments

GET /storagedomains/{storagedomain:id}/vms/{vm:id}/diskattachments/{attachment:id}

GET /storagedomains/{storagedomain:id}/vms/{vm:id}/disks

58
 CHAPTER 4. REQUESTS

GET /storagedomains/{storagedomain:id}/vms/{vm:id}/disks/{disk:id}

POST /storagedomains/{storagedomain:id}/vms/{vm:id}/import

POST /storagedomains/{storagedomain:id}/vms/{vm:id}/register

POST /tags

GET /tags

GET /tags/{tag:id}

PUT /tags/{tag:id}

DELETE /tags/{tag:id}

POST /templates

GET /templates

GET /templates/{template:id}

PUT /templates/{template:id}

DELETE /templates/{template:id}

GET /templates/{template:id}/cdroms

GET /templates/{template:id}/cdroms/{cdrom:id}

GET /templates/{template:id}/diskattachments

GET /templates/{template:id}/diskattachments/{attachment:id}

DELETE /templates/{template:id}/diskattachments/{attachment:id}

POST /templates/{template:id}/export

POST /templates/{template:id}/graphicsconsoles

GET /templates/{template:id}/graphicsconsoles

GET /templates/{template:id}/graphicsconsoles/{console:id}

DELETE /templates/{template:id}/graphicsconsoles/{console:id}

POST /templates/{template:id}/nics

GET /templates/{template:id}/nics

GET /templates/{template:id}/nics/{nic:id}

PUT /templates/{template:id}/nics/{nic:id}

DELETE /templates/{template:id}/nics/{nic:id}

POST /templates/{template:id}/permissions

GET /templates/{template:id}/permissions

GET /templates/{template:id}/permissions/{permission:id}

DELETE /templates/{template:id}/permissions/{permission:id}

59
Red Hat Virtualization 4.0 REST API Guide

POST /templates/{template:id}/tags

GET /templates/{template:id}/tags

GET /templates/{template:id}/tags/{tag:id}

DELETE /templates/{template:id}/tags/{tag:id}

POST /templates/{template:id}/watchdogs

GET /templates/{template:id}/watchdogs

GET /templates/{template:id}/watchdogs/{watchdog:id}

PUT /templates/{template:id}/watchdogs/{watchdog:id}

DELETE /templates/{template:id}/watchdogs/{watchdog:id}

POST /users

GET /users

GET /users/{user:id}

DELETE /users/{user:id}

POST /users/{user:id}/permissions

GET /users/{user:id}/permissions

GET /users/{user:id}/permissions/{permission:id}

DELETE /users/{user:id}/permissions/{permission:id}

GET /users/{user:id}/roles

GET /users/{user:id}/roles/{role:id}

DELETE /users/{user:id}/roles/{role:id}

PUT /users/{user:id}/roles/{role:id}

POST /users/{user:id}/roles/{role:id}/permits

GET /users/{user:id}/roles/{role:id}/permits

GET /users/{user:id}/roles/{role:id}/permits/{permit:id}

DELETE /users/{user:id}/roles/{role:id}/permits/{permit:id}

POST /users/{user:id}/sshpublickeys

GET /users/{user:id}/sshpublickeys

GET /users/{user:id}/sshpublickeys/{key:id}

PUT /users/{user:id}/sshpublickeys/{key:id}

DELETE /users/{user:id}/sshpublickeys/{key:id}

POST /users/{user:id}/tags

GET /users/{user:id}/tags

60
 CHAPTER 4. REQUESTS

GET /users/{user:id}/tags/{tag:id}

DELETE /users/{user:id}/tags/{tag:id}

POST /vmpools

GET /vmpools

GET /vmpools/{pool:id}

PUT /vmpools/{pool:id}

DELETE /vmpools/{pool:id}

POST /vmpools/{pool:id}/allocatevm

POST /vmpools/{pool:id}/permissions

GET /vmpools/{pool:id}/permissions

GET /vmpools/{pool:id}/permissions/{permission:id}

DELETE /vmpools/{pool:id}/permissions/{permission:id}

POST /vms

GET /vms

GET /vms/{vm:id}

PUT /vms/{vm:id}

DELETE /vms/{vm:id}

POST /vms/{vm:id}/affinitylabels

GET /vms/{vm:id}/affinitylabels

GET /vms/{vm:id}/affinitylabels/{label:id}

DELETE /vms/{vm:id}/affinitylabels/{label:id}

GET /vms/{vm:id}/applications

GET /vms/{vm:id}/applications/{application:id}

POST /vms/{vm:id}/cancelmigration

GET /vms/{vm:id}/cdroms

GET /vms/{vm:id}/cdroms/{cdrom:id}

PUT /vms/{vm:id}/cdroms/{cdrom:id}

POST /vms/{vm:id}/clone

POST /vms/{vm:id}/commitsnapshot

POST /vms/{vm:id}/detach

POST /vms/{vm:id}/diskattachments

GET /vms/{vm:id}/diskattachments

61
Red Hat Virtualization 4.0 REST API Guide

GET /vms/{vm:id}/diskattachments/{attachment:id}

DELETE /vms/{vm:id}/diskattachments/{attachment:id}

PUT /vms/{vm:id}/diskattachments/{attachment:id}

POST /vms/{vm:id}/export

POST /vms/{vm:id}/freezefilesystems

POST /vms/{vm:id}/graphicsconsoles

GET /vms/{vm:id}/graphicsconsoles

GET /vms/{vm:id}/graphicsconsoles/{console:id}

DELETE /vms/{vm:id}/graphicsconsoles/{console:id}

POST /vms/{vm:id}/hostdevices

GET /vms/{vm:id}/hostdevices

GET /vms/{vm:id}/hostdevices/{device:id}

DELETE /vms/{vm:id}/hostdevices/{device:id}

GET /vms/{vm:id}/katelloerrata

GET /vms/{vm:id}/katelloerrata/{katelloerratum:id}

POST /vms/{vm:id}/logon

POST /vms/{vm:id}/maintenance

POST /vms/{vm:id}/migrate

POST /vms/{vm:id}/nics

GET /vms/{vm:id}/nics

GET /vms/{vm:id}/nics/{nic:id}

PUT /vms/{vm:id}/nics/{nic:id}

DELETE /vms/{vm:id}/nics/{nic:id}

POST /vms/{vm:id}/nics/{nic:id}/activate

POST /vms/{vm:id}/nics/{nic:id}/deactivate

GET /vms/{vm:id}/nics/{nic:id}/reporteddevices

GET /vms/{vm:id}/nics/{nic:id}/reporteddevices/{reporteddevice:id}

GET /vms/{vm:id}/nics/{nic:id}/statistics

GET /vms/{vm:id}/nics/{nic:id}/statistics/{statistic:id}

POST /vms/{vm:id}/numanodes

GET /vms/{vm:id}/numanodes

GET /vms/{vm:id}/numanodes/{node:id}

62
 CHAPTER 4. REQUESTS

PUT /vms/{vm:id}/numanodes/{node:id}

DELETE /vms/{vm:id}/numanodes/{node:id}

POST /vms/{vm:id}/permissions

GET /vms/{vm:id}/permissions

GET /vms/{vm:id}/permissions/{permission:id}

DELETE /vms/{vm:id}/permissions/{permission:id}

POST /vms/{vm:id}/previewsnapshot

POST /vms/{vm:id}/reboot

POST /vms/{vm:id}/reordermacaddresses

GET /vms/{vm:id}/reporteddevices

GET /vms/{vm:id}/reporteddevices/{reporteddevice:id}

GET /vms/{vm:id}/sessions

GET /vms/{vm:id}/sessions/{session:id}

POST /vms/{vm:id}/shutdown

POST /vms/{vm:id}/snapshots

GET /vms/{vm:id}/snapshots

GET /vms/{vm:id}/snapshots/{snapshot:id}

DELETE /vms/{vm:id}/snapshots/{snapshot:id}

GET /vms/{vm:id}/snapshots/{snapshot:id}/cdroms

GET /vms/{vm:id}/snapshots/{snapshot:id}/cdroms/{cdrom:id}

GET /vms/{vm:id}/snapshots/{snapshot:id}/disks

GET /vms/{vm:id}/snapshots/{snapshot:id}/disks/{disk:id}

GET /vms/{vm:id}/snapshots/{snapshot:id}/nics

GET /vms/{vm:id}/snapshots/{snapshot:id}/nics/{nic:id}

POST /vms/{vm:id}/snapshots/{snapshot:id}/restore

POST /vms/{vm:id}/start

GET /vms/{vm:id}/statistics

GET /vms/{vm:id}/statistics/{statistic:id}

POST /vms/{vm:id}/stop

POST /vms/{vm:id}/suspend

POST /vms/{vm:id}/tags

GET /vms/{vm:id}/tags

63
Red Hat Virtualization 4.0 REST API Guide

GET /vms/{vm:id}/tags/{tag:id}

DELETE /vms/{vm:id}/tags/{tag:id}

POST /vms/{vm:id}/thawfilesystems

POST /vms/{vm:id}/ticket

POST /vms/{vm:id}/undosnapshot

POST /vms/{vm:id}/watchdogs

GET /vms/{vm:id}/watchdogs

GET /vms/{vm:id}/watchdogs/{watchdog:id}

PUT /vms/{vm:id}/watchdogs/{watchdog:id}

DELETE /vms/{vm:id}/watchdogs/{watchdog:id}

POST /vnicprofiles

GET /vnicprofiles

GET /vnicprofiles/{profile:id}

PUT /vnicprofiles/{profile:id}

DELETE /vnicprofiles/{profile:id}

POST /vnicprofiles/{profile:id}/permissions

GET /vnicprofiles/{profile:id}/permissions

GET /vnicprofiles/{profile:id}/permissions/{permission:id}

DELETE /vnicprofiles/{profile:id}/permissions/{permission:id}

64
 CHAPTER 5. SERVICES

CHAPTER 5. SERVICES
This section enumerates all the services that are available in the API.

5.1. AFFINITYGROUP
This service manages a single affinity group.

Table 5.1. Methods summary

Name Summary

get Retrieve the affinity group details.

remove Remove the affinity group.

update Update the affinity group.

5.1.1. get GET

Retrieve the affinity group details.

<affinity_group id="00000000-0000-0000-0000-000000000000">
<name>AF_GROUP_001</name>
<cluster id="00000000-0000-0000-0000-000000000000"/>
<positive>true</positive>
<enforcing>true</enforcing>
</affinity_group>

Table 5.2. Parameters summary

Name Type Direction Summary

group AffinityGrou Out The affinity group.

p

5.1.2. remove DELETE

Remove the affinity group.

DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456

65
Red Hat Virtualization 4.0 REST API Guide

Table 5.3. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.1.3. update PUT

Update the affinity group.

Table 5.4. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

group AffinityGrou In/Out The affinity group.

p

5.2. AFFINITYGROUPVM

This service manages a single virtual machine to affinity group assignment.

Table 5.5. Methods summary

Name Summary

remove Remove this virtual machine from the affinity group.

5.2.1. remove DELETE

Remove this virtual machine from the affinity group.

Table 5.6. Parameters summary

66
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.3. AFFINITYGROUPVMS
This service manages a collection of all virtual machines assigned to an affinity group.

Table 5.7. Methods summary

Name Summary

add Add a virtual machine to the affinity group.

list List all virtual machines assigned to this affinity group.

5.3.1. add POST

Add a virtual machine to the affinity group.

For example to add the virtual machine 000-000 to affinity group 123-456 send a request to:

POST /ovirt-engine/api/clusters/000-000/affinitygroups/123-456/vms

With the following body:

<vm id="000-000"/>

Table 5.8. Parameters summary

Name Type Direction Summary

vm Vm In/Out

5.3.2. list GET

List all virtual machines assigned to this affinity group.

Table 5.9. Parameters summary

67
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

max Integer In Sets the maximum number of virtual machines to

return.

vms Vm[] Out

5.3.2.1. max

Sets the maximum number of virtual machines to return. If not specified all the virtual machines are
returned.

5.4. AFFINITYGROUPS
Affinity groups service manages virtual machine relationships and dependencies.

Table 5.10. Methods summary

Name Summary

add Create a new affinity group.

list List existing affinity groups.

5.4.1. add POST

Create a new affinity group.

Post a request like in the example below to create a new affinity group:

POST /ovirt-engine/api/clusters/000-000/affinitygroups

And use the following example in its body:

<affinity_group>
<name>AF_GROUP_001</name>
<positive>true</positive>
<enforcing>true</enforcing>
</affinity_group>

Table 5.11. Parameters summary

68
 CHAPTER 5. SERVICES

Name Type Direction Summary

group AffinityGrou In/Out The affinity group object to create.

p

5.4.2. list GET

List existing affinity groups.

Table 5.12. Parameters summary

Name Type Direction Summary

groups AffinityGrou Out The list of existing affinity groups.

p[]

max Integer In Sets the maximum number of affinity groups to

return.

5.4.2.1. max

Sets the maximum number of affinity groups to return. If not specified all the affinity groups are
returned.

5.5. AFFINITYLABEL

Single affinity label details.

Table 5.13. Methods summary

Name Summary

get Retrieves details about a label.

remove Removes a label from system and clears all assignments of the removed label.

update Updates a label.

69
Red Hat Virtualization 4.0 REST API Guide

5.5.1. get GET

Retrieves details about a label.

Table 5.14. Parameters summary

Name Type Direction Summary

label AffinityLabel Out

5.5.2. remove DELETE

Removes a label from system and clears all assignments of the removed label.

5.5.3. update PUT

Updates a label.

This call will update all metadata like name or description.

Table 5.15. Parameters summary

Name Type Direction Summary

label AffinityLabel In/Out

5.6. AFFINITYLABELHOST

This service represents a host that has a specific label when accessed through the
affinitylabels/hosts subcollection.

Table 5.16. Methods summary

Name Summary

get Retrieves details about a host that has this label assigned.

remove Remove a label from a host.

5.6.1. get GET

70
 CHAPTER 5. SERVICES

Retrieves details about a host that has this label assigned.

Table 5.17. Parameters summary

Name Type Direction Summary

host Host Out

5.6.2. remove DELETE

Remove a label from a host.

5.7. AFFINITYLABELHOSTS

This service represents list of hosts that have a specific label when accessed through the
affinitylabels/hosts subcollection.

Table 5.18. Methods summary

Name Summary

add Add a label to a host.

list List all hosts with the label.

5.7.1. add POST

Add a label to a host.

Table 5.19. Parameters summary

Name Type Direction Summary

host Host In/Out

5.7.2. list GET

List all hosts with the label.

Table 5.20. Parameters summary

71
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

hosts Host[] Out

5.8. AFFINITYLABELVM

This service represents a vm that has a specific label when accessed through the affinitylabels/vms
subcollection.

Table 5.21. Methods summary

Name Summary

get Retrieves details about a vm that has this label assigned.

remove Remove a label from a vm.

5.8.1. get GET

Retrieves details about a vm that has this label assigned.

Table 5.22. Parameters summary

Name Type Direction Summary

vm Vm Out

5.8.2. remove DELETE

Remove a label from a vm.

5.9. AFFINITYLABELVMS
This service represents list of vms that have a specific label when accessed through the
affinitylabels/vms subcollection.

Table 5.23. Methods summary

72
 CHAPTER 5. SERVICES

Name Summary

add Add a label to a vm.

list List all vms with the label.

5.9.1. add POST

Add a label to a vm.

Table 5.24. Parameters summary

Name Type Direction Summary

vm Vm In/Out

5.9.2. list GET

List all vms with the label.

Table 5.25. Parameters summary

Name Type Direction Summary

vms Vm[] Out

5.10. AFFINITYLABELS

Manages the affinity labels available in the system.

Table 5.26. Methods summary

Name Summary

add Creates a new label.

73
Red Hat Virtualization 4.0 REST API Guide

Name Summary

list Lists all labels present in the system.

5.10.1. add POST

Creates a new label. The label is automatically attached to all entities mentioned in the vms or hosts
lists.

Table 5.27. Parameters summary

Name Type Direction Summary

label AffinityLabel In/Out

5.10.2. list GET

Lists all labels present in the system.

Table 5.28. Parameters summary

Name Type Direction Summary

labels AffinityLabel[ Out

]

max Integer In Sets the maximum number of labels to return.

5.10.2.1. max

Sets the maximum number of labels to return. If not specified all the labels are returned.

5.11. ASSIGNEDAFFINITYLABEL
This service represents one label to entity assignment when accessed using the entities/affinitylabels
subcollection.

Table 5.29. Methods summary

74
 CHAPTER 5. SERVICES

Name Summary

get Retrieves details about the attached label.

remove Removes the label from an entity.

5.11.1. get GET

Retrieves details about the attached label.

Table 5.30. Parameters summary

Name Type Direction Summary

label AffinityLabel Out

5.11.2. remove DELETE

Removes the label from an entity. Does not touch the label itself.

5.12. ASSIGNEDAFFINITYLABELS

This service is used to list and manipulate affinity labels that are assigned to supported entities
when accessed using entities/affinitylabels.

Table 5.31. Methods summary

Name Summary

add Attaches a label to an entity.

list Lists all labels that are attached to an entity.

5.12.1. add POST

Attaches a label to an entity.

Table 5.32. Parameters summary

75
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

label AffinityLabel In/Out

5.12.2. list GET

Lists all labels that are attached to an entity.

Table 5.33. Parameters summary

Name Type Direction Summary

label AffinityLabel[ Out

]

5.13. ASSIGNEDCPUPROFILE

Table 5.34. Methods summary

Name Summary

get

remove

5.13.1. get GET

Table 5.35. Parameters summary

Name Type Direction Summary

profile CpuProfile Out

5.13.2. remove DELETE

Table 5.36. Parameters summary

76
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.14. ASSIGNEDCPUPROFILES

Table 5.37. Methods summary

Name Summary

add

list

5.14.1. add POST

Table 5.38. Parameters summary

Name Type Direction Summary

profile CpuProfile In/Out

5.14.2. list GET

Table 5.39. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of profiles to return.

profiles CpuProfile[] Out

5.14.2.1. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

77
Red Hat Virtualization 4.0 REST API Guide

5.15. ASSIGNEDDISKPROFILE

Table 5.40. Methods summary

Name Summary

get

remove

5.15.1. get GET

Table 5.41. Parameters summary

Name Type Direction Summary

disk_pro DiskProfile Out

file

5.15.2. remove DELETE

Table 5.42. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.16. ASSIGNEDDISKPROFILES

Table 5.43. Methods summary

Name Summary

add

78
 CHAPTER 5. SERVICES

Name Summary

list

5.16.1. add POST

Table 5.44. Parameters summary

Name Type Direction Summary

profile DiskProfile In/Out

5.16.2. list GET

Table 5.45. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of profiles to return.

profiles DiskProfile[] Out

5.16.2.1. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

5.17. ASSIGNEDNETWORK

Table 5.46. Methods summary

Name Summary

get

remove

79
Red Hat Virtualization 4.0 REST API Guide

Name Summary

update

5.17.1. get GET

Table 5.47. Parameters summary

Name Type Direction Summary

network Network Out

5.17.2. remove DELETE

Table 5.48. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.17.3. update PUT

Table 5.49. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

network Network In/Out

5.18. ASSIGNEDNETWORKS

Table 5.50. Methods summary

80
 CHAPTER 5. SERVICES

Name Summary

add

list

5.18.1. add POST

Table 5.51. Parameters summary

Name Type Direction Summary

network Network In/Out

5.18.2. list GET

Table 5.52. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of networks to return.

networks Network[] Out

5.18.2.1. max

Sets the maximum number of networks to return. If not specified all the networks are returned.

5.19. ASSIGNEDPERMISSIONS
Represents a permission sub-collection, scoped by user, group or some entity type.

Table 5.53. Methods summary

81
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add Assign a new permission to a user or group for specific entity.

list List all the permissions of the specific entity.

5.19.1. add POST

Assign a new permission to a user or group for specific entity.

For example, to assign the UserVmManager role to the virtual machine with id 123 to the user with
id 456 send a request like this:

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

With a request body like this:

<permission>
<role>
<name>UserVmManager</name>
</role>
<user id="456"/>
</permission>

To assign the SuperUser role to the system to the user with id 456 send a request like this:

POST /ovirt-engine/api/permissions

With a request body like this:

<permission>
<role>
<name>SuperUser</name>
</role>
<user id="456"/>
</permission>

If you want to assign permission to the group instead of the user please replace the user element
with the group element with proper id of the group. For example to assign the UserRole role to
the cluster with id 123 to the group with id 789 send a request like this:

POST /ovirt-engine/api/clusters/123/permissions

With a request body like this:

<permission>
<role>
<name>UserRole</name>
</role>
<group id="789"/>

82
 CHAPTER 5. SERVICES

</permission>

Table 5.54. Parameters summary

Name Type Direction Summary

permissi Permission In/Out The permission.

on

5.19.2. list GET

List all the permissions of the specific entity.

For example to list all the permissions of the cluster with id 123 send a request like this:

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

<permissions>
<permission id="456">
<cluster id="123"/>
<role id="789"/>
<user id="451"/>
</permission>
<permission id="654">
<cluster id="123"/>
<role id="789"/>
<group id="127"/>
</permission>
</permissions>

Table 5.55. Parameters summary

Name Type Direction Summary

permissi Permission[] Out The list of permissions.

ons

5.20. ASSIGNEDROLES
Represents a roles sub-collection, for example scoped by user.

Table 5.56. Methods summary

83
Red Hat Virtualization 4.0 REST API Guide

Name Summary

list

5.20.1. list GET

Table 5.57. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of roles to return.

roles Role[] Out

5.20.1.1. max

Sets the maximum number of roles to return. If not specified all the roles are returned.

5.21. ASSIGNEDTAG

A service to manage assignment of specific tag to specific entities in system.

Table 5.58. Methods summary

Name Summary

get Gets the information about the assigned tag.

remove Unassign tag from specific entity in the system.

5.21.1. get GET

Gets the information about the assigned tag.

For example to retrieve the information about the tag with the id 456 which is assigned to virtual
machine with id 123 send a request like this:

GET /ovirt-engine/api/vms/123/tags/456

84
 CHAPTER 5. SERVICES

<tag href="/ovirt-engine/api/tags/456" id="456">

<name>root</name>
<description>root</description>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</tag>

Table 5.59. Parameters summary

Name Type Direction Summary

tag Tag Out The assigned tag.

5.21.2. remove DELETE

Unassign tag from specific entity in the system.

For example to unassign the tag with id 456 from virtual machine with id 123 send a request like
this:

DELETE /ovirt-engine/api/vms/123/tags/456

Table 5.60. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.22. ASSIGNEDTAGS
A service to manage collection of assignment of tags to specific entities in system.

Table 5.61. Methods summary

Name Summary

add Assign tag to specific entity in the system.

list List all tags assigned to the specific entity.

85
Red Hat Virtualization 4.0 REST API Guide

5.22.1. add POST

Assign tag to specific entity in the system.

For example to assign tag mytag to virtual machine with the id 123 send a request like this:

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

With a request body like this:

<tag>
<name>mytag</name>
</tag>

Table 5.62. Parameters summary

Name Type Direction Summary

tag Tag In/Out The assigned tag.

5.22.2. list GET

List all tags assigned to the specific entity.

For example to list all the tags of the virtual machine with id 123 send a request like this:

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

<tags>
<tag href="/ovirt-engine/api/tags/222" id="222">
<name>mytag</name>
<description>mytag</description>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</tag>
</tags>

Table 5.63. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of tags to return.

tags Tag[] Out The list of assigned tags.

86
 CHAPTER 5. SERVICES

5.22.2.1. max

Sets the maximum number of tags to return. If not specified all the tags are returned.

5.23. ASSIGNEDVNICPROFILE

Table 5.64. Methods summary

Name Summary

get

remove

5.23.1. get GET

Table 5.65. Parameters summary

Name Type Direction Summary

profile VnicProfile Out

5.23.2. remove DELETE

Table 5.66. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.24. ASSIGNEDVNICPROFILES

Table 5.67. Methods summary

87
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add

list

5.24.1. add POST

Table 5.68. Parameters summary

Name Type Direction Summary

profile VnicProfile In/Out

5.24.2. list GET

Table 5.69. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of profiles to return.

profiles VnicProfile[] Out

5.24.2.1. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

5.25. ATTACHEDSTORAGEDOMAIN

Table 5.70. Methods summary

Name Summary

activate This operation activates an attached storage domain.

88
 CHAPTER 5. SERVICES

Name Summary

deactivate This operation deactivates an attached storage domain.

get

remove

5.25.1. activate POST

This operation activates an attached storage domain. Once the storage domain is activated it is
ready for use with the data center.

POST /ovirt-engine/api/datacenters/123/storagedomains/456/activate

The activate action does not take any action specific parameters, so the request body should
contain an empty action:

<action/>

Table 5.71. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the activation should be performed

asynchronously.

5.25.2. deactivate POST

This operation deactivates an attached storage domain. Once the storage domain is deactivated it
will not be used with the data center.

POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate

The deactivate action does not take any action specific parameters, so the request body should
contain an empty action:

<action/>

Table 5.72. Parameters summary

89
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the deactivation should be performed

asynchronously.

5.25.3. get GET

Table 5.73. Parameters summary

Name Type Direction Summary

storage_ StorageDom Out

domain ain

5.25.4. remove DELETE

Table 5.74. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.26. ATTACHEDSTORAGEDOMAINS

Table 5.75. Methods summary

Name Summary

add

list

5.26.1. add POST

Table 5.76. Parameters summary

90
 CHAPTER 5. SERVICES

Name Type Direction Summary

storage_ StorageDom In/Out

domain ain

5.26.2. list GET

Table 5.77. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of storage domains to

return.

storage_ StorageDom Out

domains ain[]

5.26.2.1. max

Sets the maximum number of storage domains to return. If not specified all the storage domains are
returned.

5.27. BALANCE

Table 5.78. Methods summary

Name Summary

get

remove

5.27.1. get GET

Table 5.79. Parameters summary

91
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

balance Balance Out

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.27.2. remove DELETE

Table 5.80. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.28. BALANCES

Table 5.81. Methods summary

Name Summary

add

list

5.28.1. add POST

Table 5.82. Parameters summary

Name Type Direction Summary

balance Balance In/Out

5.28.2. list GET

92
 CHAPTER 5. SERVICES

Table 5.83. Parameters summary

Name Type Direction Summary

balances Balance[] Out

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of balances to return.

5.28.2.1. max

Sets the maximum number of balances to return. If not specified all the balances are returned.

5.29. BOOKMARK
A service to manage a bookmark.

Table 5.84. Methods summary

Name Summary

get Get a bookmark.

remove Remove a bookmark.

update Update a bookmark.

5.29.1. get GET

Get a bookmark.

An example for getting a bookmark:

GET /ovirt-engine/api/bookmarks/123

93
Red Hat Virtualization 4.0 REST API Guide

<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">

<name>example_vm</name>
<value>vm: name=example*</value>
</bookmark>

Table 5.85. Parameters summary

Name Type Direction Summary

bookmark Bookmark Out The requested bookmark.

5.29.2. remove DELETE

Remove a bookmark.

An example for removing a bookmark:

DELETE /ovirt-engine/api/bookmarks/123

Table 5.86. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.29.3. update PUT

Update a bookmark.

An example for updating a bookmark:

PUT /ovirt-engine/api/bookmarks/123

With the request body:

<bookmark>
<name>new_example_vm</name>
<value>vm: name=new_example*</value>
</bookmark>

Table 5.87. Parameters summary

94
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

bookmark Bookmark In/Out The updated bookmark.

5.30. BOOKMARKS

A service to manage bookmarks.

Table 5.88. Methods summary

Name Summary

add Adding a new bookmark.

list Listing all the available bookmarks.

5.30.1. add POST

Adding a new bookmark.

Example of adding a bookmark:

POST /ovirt-engine/api/bookmarks

<bookmark>
<name>new_example_vm</name>
<value>vm: name=new_example*</value>
</bookmark>

Table 5.89. Parameters summary

Name Type Direction Summary

bookmark Bookmark In/Out The added bookmark.

5.30.2. list GET

95
Red Hat Virtualization 4.0 REST API Guide

Listing all the available bookmarks.

Example of listing bookmarks:

GET /ovirt-engine/api/bookmarks

<bookmarks>
<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
<name>database</name>
<value>vm: name=database*</value>
</bookmark>
<bookmark href="/ovirt-engine/api/bookmarks/456" id="456">
<name>example</name>
<value>vm: name=example*</value>
</bookmark>
</bookmarks>

Table 5.90. Parameters summary

Name Type Direction Summary

bookmark Bookmark[] Out The list of available bookmarks.

s

max Integer In Sets the maximum number of bookmarks to return.

5.30.2.1. max

Sets the maximum number of bookmarks to return. If not specified all the bookmarks are returned.

5.31. CLUSTER
A service to manage specific cluster.

Table 5.91. Methods summary

Name Summary

get Get information about the cluster.

remove Removes cluster from the system.

96
 CHAPTER 5. SERVICES

Name Summary

resetemulate
dmachine

update Updates information about the cluster.

5.31.1. get GET

Get information about the cluster.

An example of getting a cluster:

GET /ovirt-engine/api/clusters/123

<cluster href="/ovirt-engine/api/clusters/123" id="123">

<actions>
<link href="/ovirt-engine/api/clusters/123/resetemulatedmachine"
rel="resetemulatedmachine"/>
</actions>
<name>Default</name>
<description>The default server cluster</description>
<link href="/ovirt-engine/api/clusters/123/networks" rel="networks"/>
<link href="/ovirt-engine/api/clusters/123/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/clusters/123/glustervolumes"
rel="glustervolumes"/>
<link href="/ovirt-engine/api/clusters/123/glusterhooks"
rel="glusterhooks"/>
<link href="/ovirt-engine/api/clusters/123/affinitygroups"
rel="affinitygroups"/>
<link href="/ovirt-engine/api/clusters/123/cpuprofiles"
rel="cpuprofiles"/>
<ballooning_enabled>false</ballooning_enabled>
<cpu>
<architecture>x86_64</architecture>
<type>Intel Penryn Family</type>
</cpu>
<error_handling>
<on_error>migrate</on_error>
</error_handling>
<fencing_policy>
<enabled>true</enabled>
<skip_if_connectivity_broken>
<enabled>false</enabled>
<threshold>50</threshold>
</skip_if_connectivity_broken>
<skip_if_sd_active>
<enabled>false</enabled>
</skip_if_sd_active>
</fencing_policy>

97
Red Hat Virtualization 4.0 REST API Guide

<gluster_service>false</gluster_service>
<ha_reservation>false</ha_reservation>
<ksm>
<enabled>true</enabled>
<merge_across_nodes>true</merge_across_nodes>
</ksm>
<maintenance_reason_required>false</maintenance_reason_required>
<memory_policy>
<over_commit>
<percent>100</percent>
</over_commit>
<transparent_hugepages>
<enabled>true</enabled>
</transparent_hugepages>
</memory_policy>
<migration>
<auto_converge>inherit</auto_converge>
<bandwidth>
<assignment_method>auto</assignment_method>
</bandwidth>
<compressed>inherit</compressed>
</migration>
<optional_reason>false</optional_reason>
<required_rng_sources>
<required_rng_source>random</required_rng_source>
</required_rng_sources>
<scheduling_policy href="/ovirt-engine/api/schedulingpolicies/456"
id="456"/>
<threads_as_cores>false</threads_as_cores>
<trusted_service>false</trusted_service>
<tunnel_migration>false</tunnel_migration>
<version>
<major>4</major>
<minor>0</minor>
</version>
<virt_service>true</virt_service>
<data_center href="/ovirt-engine/api/datacenters/111" id="111"/>
</cluster>

Table 5.92. Parameters summary

Name Type Direction Summary

cluster Cluster Out

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.31.2. remove DELETE

98
 CHAPTER 5. SERVICES

Removes cluster from the system.

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000

Table 5.93. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.31.3. resetemulatedmachine POST

Table 5.94. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the reset should be performed

asynchronously.

5.31.4. update PUT

Updates information about the cluster.

Only specified fields are updated, others remain unchanged.

E.g. update cluster’s CPU:

PUT /ovirt-engine/api/clusters/123

With request body like:

<cluster>
<cpu>
<type>Intel Haswell-noTSX Family</type>
</cpu>
</cluster>

Table 5.95. Parameters summary

99
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

cluster Cluster In/Out

5.32. CLUSTERLEVEL
Provides information about a specific cluster level. See the ClusterLevels service for more
information.

Table 5.96. Methods summary

Name Summary

get Provides the information about the capabilities of the specific cluster level managed
by this service.

5.32.1. get GET

Provides the information about the capabilities of the specific cluster level managed by this service.

For example, to find what CPU types are supported by level 3.6 you can send a request like this:

GET /ovirt-engine/api/clusterlevels/3.6

That will return a ClusterLevel object containing the supported CPU types, and other information
which describes the cluster level:

<cluster_level id="3.6">
<cpu_types>
<cpu_type>
<name>Intel Conroe Family</name>
<level>3</level>
<architecture>x86_64</architecture>
</cpu_type>
...
</cpu_types>
<permits>
<permit id="1">
<name>create_vm</name>
<administrative>false</administrative>

100
 CHAPTER 5. SERVICES

</permit>
...
</permits>
</cluster_level>

Table 5.97. Parameters summary

Name Type Direction Summary

level ClusterLevel Out Retreived cluster level.

5.33. CLUSTERLEVELS

Provides information about the capabilities of different cluster levels supported by the engine.
Version 4.0 of the engine supports levels 4.0 and 3.6. Each of these levels support different sets of
CPU types, for example. This service provides that information.

Table 5.98. Methods summary

Name Summary

list Lists the cluster levels supported by the system.

5.33.1. list GET

Lists the cluster levels supported by the system.

GET /ovirt-engine/api/clusterlevels

This will return a list of available cluster levels.

<cluster_levels>
<cluster_level id="4.0">
...
</cluster_level>
...
</cluster_levels>

Table 5.99. Parameters summary

101
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

levels ClusterLevel Out Retrieved cluster levels.

[]

5.34. CLUSTERS

A service to manage clusters.

Table 5.100. Methods summary

Name Summary

add Creates a new cluster.

list

5.34.1. add POST

Creates a new cluster.

This requires the name, cpu.type and data_center attributes. Identify the data center with either
the id or name attributes.

POST /ovirt-engine/api/clusters

With a request body like this:

<cluster>
<name>mycluster</name>
<cpu>
<type>Intel Penryn Family</type>
</cpu>
<data_center id="123"/>
</cluster>

Table 5.101. Parameters summary

Name Type Direction Summary

cluster Cluster In/Out

102
 CHAPTER 5. SERVICES

5.34.2. list GET

Table 5.102. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

clusters Cluster[] Out

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of clusters to return.

search String In A query string used to restrict the returned clusters.

5.34.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.34.2.2. max

Sets the maximum number of clusters to return. If not specified all the clusters are returned.

5.35. COPYABLE

Table 5.103. Methods summary

Name Summary

copy

5.35.1. copy POST

103
Red Hat Virtualization 4.0 REST API Guide

Table 5.104. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the copy should be performed

asynchronously.

5.36. CPUPROFILE

Table 5.105. Methods summary

Name Summary

get

remove

update

5.36.1. get GET

Table 5.106. Parameters summary

Name Type Direction Summary

profile CpuProfile Out

5.36.2. remove DELETE

Table 5.107. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

104
 CHAPTER 5. SERVICES

5.36.3. update PUT

Table 5.108. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

profile CpuProfile In/Out

5.37. CPUPROFILES

Table 5.109. Methods summary

Name Summary

add

list

5.37.1. add POST

Table 5.110. Parameters summary

Name Type Direction Summary

profile CpuProfile In/Out

5.37.2. list GET

Table 5.111. Parameters summary

105
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

max Integer In Sets the maximum number of profiles to return.

profile CpuProfile[] Out

5.37.2.1. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

5.38. DATACENTER

A service to manage a data center.

Table 5.112. Methods summary

Name Summary

get Get a data center.

remove Removes the data center.

update Updates the data center.

5.38.1. get GET

Get a data center.

An example of getting a data center:

GET /ovirt-engine/api/datacenters/123

<data_center href="/ovirt-engine/api/datacenters/123" id="123">

<name>Default</name>
<description>The default Data Center</description>
<link href="/ovirt-engine/api/datacenters/123/clusters"
rel="clusters"/>
<link href="/ovirt-engine/api/datacenters/123/storagedomains"
rel="storagedomains"/>
<link href="/ovirt-engine/api/datacenters/123/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/datacenters/123/networks"
rel="networks"/>

106
 CHAPTER 5. SERVICES

<link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>

<link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
<link href="/ovirt-engine/api/datacenters/123/iscsibonds"
rel="iscsibonds"/>
<local>false</local>
<quota_mode>disabled</quota_mode>
<status>up</status>
<storage_format>v3</storage_format>
<supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
<mac_pool href="/ovirt-engine/api/macpools/456" id="456"/>
</data_center>

Table 5.113. Parameters summary

Name Type Direction Summary

data_cen DataCenter Out

ter

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.38.2. remove DELETE

Removes the data center.

DELETE /ovirt-engine/api/datacenters/123

Without any special parameters, the storage domains attached to the data center are detached and
then removed from the storage. If something fails when performing this operation, for example if
there is no host available to remove the storage domains from the storage, the complete operation
will fail.

If the force parameter is true then the operation will always succeed, even if something fails while
removing one storage domain, for example. The failure is just ignored and the data center is
removed from the database anyway.

Table 5.114. Parameters summary

107
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

force Boolean In Indicates if the operation should succeed, and the

storage domain removed from the database, even
if something fails during the operation.

5.38.2.1. force

Indicates if the operation should succeed, and the storage domain removed from the database, even
if something fails during the operation.

This parameter is optional, and the default value is false.

5.38.3. update PUT

Updates the data center.

The name, description, storage_type, version, storage_format and mac_pool elements

are updatable post-creation. For example, to change the name and description of data center 123
send a request like this:

PUT /ovirt-engine/api/datacenters/123

With a request body like this:

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

Table 5.115. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

data_cen DataCenter In/Out The data center that is being updated.

ter

5.39. DATACENTERS

108
 CHAPTER 5. SERVICES

A service to manage data centers.

Table 5.116. Methods summary

Name Summary

add Creates a new data center.

list Lists the data centers.

5.39.1. add POST

Creates a new data center.

Creation of a new data center requires the name and local elements. For example, to create a
data center named mydc that uses shared storage (NFS, iSCSI or fibre channel) send a request like
this:

POST /ovirt-engine/api/datacenters

With a request body like this:

<data_center>
<name>mydc</name>
<local>false</local>
</data_center>

Table 5.117. Parameters summary

Name Type Direction Summary

data_cen DataCenter In/Out The data center that is being added.

ter

5.39.2. list GET

Lists the data centers.

The following request retrieves a representation of the data centers:

GET /ovirt-engine/api/datacenters

The above request performed with curl:

curl \

109
Red Hat Virtualization 4.0 REST API Guide

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

This is what an example response could look like:

<data_center href="/ovirt-engine/api/datacenters/123" id="123">

<name>Default</name>
<description>The default Data Center</description>
<link href="/ovirt-engine/api/datacenters/123/networks"
rel="networks"/>
<link href="/ovirt-engine/api/datacenters/123/storagedomains"
rel="storagedomains"/>
<link href="/ovirt-engine/api/datacenters/123/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/datacenters/123/clusters"
rel="clusters"/>
<link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
<link href="/ovirt-engine/api/datacenters/123/iscsibonds"
rel="iscsibonds"/>
<link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>
<local>false</local>
<quota_mode>disabled</quota_mode>
<status>up</status>
<supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</data_center>

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

The data center also contains a link to the storage domains collection. The data center uses this
collection to attach storage domains from the storage domains main collection.

Table 5.118. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

110
 CHAPTER 5. SERVICES

Name Type Direction Summary

data_cen DataCenter[] Out

ters

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of data centers to

return.

search String In A query string used to restrict the returned data

centers.

5.39.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.39.2.2. max

Sets the maximum number of data centers to return. If not specified all the data centers are returned.

5.40. DISK

Manages a single disk.

Table 5.119. Methods summary

Name Summary

copy This operation copies a disk to the specified storage domain.

export

get

111
Red Hat Virtualization 4.0 REST API Guide

Name Summary

move Moves a disk to another storage domain.

remove

5.40.1. copy POST

This operation copies a disk to the specified storage domain.

For example, copy of a disk can be facilitated using the following request:

POST /ovirt-engine/api/disks/123/copy

With a request body like this:

<action>
<storage_domain id="456"/>
<disk>
<name>mydisk</name>
</disk>
</action>

Table 5.120. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the copy should be performed

asynchronously.

disk Disk In

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

storage_ StorageDom In
domain ain

5.40.2. export POST

Table 5.121. Parameters summary

112
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the export should be performed

asynchronously.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

storage_ StorageDom In
domain ain

5.40.3. get GET

Table 5.122. Parameters summary

Name Type Direction Summary

disk Disk Out

5.40.4. move POST

Moves a disk to another storage domain.

For example, to move the disk with identifier 123 to a storage domain with identifier 456 send the
following request:

POST /ovirt-engine/api/disks/123/move

With the following request body:

<action>
<storage_domain id="456"/>
</action>

Table 5.123. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the move should be performed

asynchronously.

113
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

storage_ StorageDom In
domain ain

5.40.5. remove DELETE

Table 5.124. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.41. DISKATTACHMENT

This service manages the attachment of a disk to a virtual machine.

Table 5.125. Methods summary

Name Summary

get Returns the details of the attachment, including the bootable flag and link to the
disk.

remove Removes the disk attachment.

update Update the disk attachment and the disk properties within it.

5.41.1. get GET

Returns the details of the attachment, including the bootable flag and link to the disk.

An example of getting a disk attachment:

GET /ovirt-engine/api/vms/123/diskattachments/456

114
 CHAPTER 5. SERVICES

<disk_attachment href="/ovirt-engine/api/vms/123/diskattachments/456"
id="456">
<active>true</active>
<bootable>true</bootable>
<interface>virtio</interface>
<disk href="/ovirt-engine/api/disks/456" id="456"/>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</disk_attachment>

Table 5.126. Parameters summary

Name Type Direction Summary

attachme DiskAttachm Out

nt ent

5.41.2. remove DELETE

Removes the disk attachment.

This will only detach the disk from the virtual machine, but won’t remove it from the system, unless
the detach_only parameter is false.

An example of removing a disk attachment:

DELETE /ovirt-engine/api/vms/123/diskattachments/456?detach_only=true

Table 5.127. Parameters summary

Name Type Direction Summary

detach_o Boolean In Indicates if the disk should only be detached from

nly the virtual machine, but not removed from the
system.

5.41.2.1. detach_only

Indicates if the disk should only be detached from the virtual machine, but not removed from the
system. The default value is true, which won’t remove the disk from the system.

5.41.3. update PUT

Update the disk attachment and the disk properties within it.

115
Red Hat Virtualization 4.0 REST API Guide

PUT /vms/{vm:id}/disksattachments/{attachment:id}
<disk_attachment>
<bootable>true</bootable>
<interface>ide</interface>
<active>true</active>
<disk>
<name>mydisk</name>
<provisioned_size>1024</provisioned_size>
...
</disk>
</disk_attachment>

Table 5.128. Parameters summary

Name Type Direction Summary

disk_att DiskAttachm In/Out

achment ent

5.42. DISKATTACHMENTS

This service manages the set of disks attached to a virtual machine. Each attached disk is
represented by a DiskAttachment, containing the bootable flag, the disk interface and the reference
to the disk.

Table 5.129. Methods summary

Name Summary

add Adds a new disk attachment to the virtual machine.

list List the disk that are attached to the virtual machine.

5.42.1. add POST

Adds a new disk attachment to the virtual machine. The attachment parameter can contain just a
reference, if the disk already exists:

<disk_attachment>
<bootable>true</bootable>
<interface>ide</interface>
<active>true</active>
<disk id="123"/>
</disk_attachment>

116
 CHAPTER 5. SERVICES

Or it can contain the complete representation of the disk, if the disk doesn’t exist yet:

<disk_attachment>
<bootable>true</bootable>
<interface>ide</interface>
<active>true</active>
<disk>
<name>mydisk</name>
<provisioned_size>1024</provisioned_size>
...
</disk>
</disk_attachment>

In this case the disk will be created and then attached to the virtual machine.

In both cases, use the following URL for a virtual machine with an id 345:

POST /ovirt-engine/api/vms/345/diskattachments

Important

The server accepts requests that don’t contain the active attribute, but the effect is
undefined. In some cases the disk will be automatically activated and in other cases it
won’t. To avoid issues it is strongly recommended to always include the active attribute
with the desired value.

Table 5.130. Parameters summary

Name Type Direction Summary

attachme DiskAttachm In/Out

nt ent

5.42.2. list GET

List the disk that are attached to the virtual machine.

Table 5.131. Parameters summary

Name Type Direction Summary

attachme DiskAttachm Out

nts ent[]

5.43. DISKPROFILE

117
Red Hat Virtualization 4.0 REST API Guide

Table 5.132. Methods summary

Name Summary

get

remove

update

5.43.1. get GET

Table 5.133. Parameters summary

Name Type Direction Summary

profile DiskProfile Out

5.43.2. remove DELETE

Table 5.134. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.43.3. update PUT

Table 5.135. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

118
 CHAPTER 5. SERVICES

Name Type Direction Summary

profile DiskProfile In/Out

5.44. DISKPROFILES

Table 5.136. Methods summary

Name Summary

add

list

5.44.1. add POST

Table 5.137. Parameters summary

Name Type Direction Summary

profile DiskProfile In/Out

5.44.2. list GET

Table 5.138. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of profiles to return.

profile DiskProfile[] Out

5.44.2.1. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

119
Red Hat Virtualization 4.0 REST API Guide

5.45. DISKSNAPSHOT

Table 5.139. Methods summary

Name Summary

get

remove

5.45.1. get GET

Table 5.140. Parameters summary

Name Type Direction Summary

snapshot DiskSnapsh Out

ot

5.45.2. remove DELETE

Table 5.141. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.46. DISKSNAPSHOTS

Table 5.142. Methods summary

Name Summary

list

120
 CHAPTER 5. SERVICES

5.46.1. list GET

Table 5.143. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of snapshots to return.

snapshot DiskSnapsh Out

s ot[]

5.46.1.1. max

Sets the maximum number of snapshots to return. If not specified all the snapshots are returned.

5.47. DISKS

Manages the collection of disks available in the system.

Table 5.144. Methods summary

Name Summary

add Adds a new floating disk.

list Get list of disks.

5.47.1. add POST

Adds a new floating disk.

When creating a new floating Disk, the API requires the storage_domain, provisioned_size
and format attributes.

To create a new floating disk with specified provisioned_size, format and name on a storage
domain with an id e9fedf39-5edc-4e0a-8628-253f1b9c5693, send a request as follows:

POST /ovirt-engine/api/disks

With a request body as follows:

<disk>
<storage_domains>

121
Red Hat Virtualization 4.0 REST API Guide

<storage_domain id="e9fedf39-5edc-4e0a-8628-253f1b9c5693"/>
</storage_domains>
<name>disk1</name>
<provisioned_size>1048576</provisioned_size>
<format>cow</format>
</disk>

Table 5.145. Parameters summary

Name Type Direction Summary

disk Disk In/Out The disk.

5.47.2. list GET

Get list of disks.

GET /ovirt-engine/api/disks

You will get a XML response which will look like this one:

<disks>
<disk id="123">
<actions>...</actions>
<name>MyDisk</name>
<description>MyDisk description</description>
<link href="/ovirt-engine/api/disks/123/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/disks/123/statistics"
rel="statistics"/>
<actual_size>5345845248</actual_size>
<alias>MyDisk alias</alias>
...
<status>ok</status>
<storage_type>image</storage_type>
<wipe_after_delete>false</wipe_after_delete>
<disk_profile id="123"/>
<quota id="123"/>
<storage_domains>...</storage_domains>
</disk>
...
</disks>

Table 5.146. Parameters summary

122
 CHAPTER 5. SERVICES

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

disks Disk[] Out List of retrieved disks.

max Integer In Sets the maximum number of disks to return.

search String In A query string used to restrict the returned disks.

5.47.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.47.2.2. max

Sets the maximum number of disks to return. If not specified all the disks are returned.

5.48. DOMAIN

A service to view details of an authentication domain in the system.

Table 5.147. Methods summary

Name Summary

get Gets the authentication domain information.

5.48.1. get GET

Gets the authentication domain information.

Usage:

GET /ovirt-engine/api/domains/5678

123
Red Hat Virtualization 4.0 REST API Guide

Will return the domain information:

<domain href="/ovirt-engine/api/domains/5678" id="5678">

<name>internal-authz</name>
<link href="/ovirt-engine/api/domains/5678/users" rel="users"/>
<link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/>
<link href="/ovirt-engine/api/domains/5678/users?search={query}"
rel="users/search"/>
<link href="/ovirt-engine/api/domains/5678/groups?search={query}"
rel="groups/search"/>
</domain>

Table 5.148. Parameters summary

Name Type Direction Summary

domain Domain Out The authentication domain.

5.49. DOMAINGROUP

Table 5.149. Methods summary

Name Summary

get

5.49.1. get GET

Table 5.150. Parameters summary

Name Type Direction Summary

get Group Out

5.50. DOMAINGROUPS

Table 5.151. Methods summary

124
 CHAPTER 5. SERVICES

Name Summary

list

5.50.1. list GET

Table 5.152. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

groups Group[] Out

max Integer In Sets the maximum number of groups to return.

search String In A query string used to restrict the returned groups.

5.50.1.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.50.1.2. max

Sets the maximum number of groups to return. If not specified all the groups are returned.

5.51. DOMAINUSER

A service to view a domain user in the system.

Table 5.153. Methods summary

Name Summary

get Gets the domain user information.

125
Red Hat Virtualization 4.0 REST API Guide

5.51.1. get GET

Gets the domain user information.

Usage:

GET /ovirt-engine/api/domains/5678/users/1234

Will return the domain user information:

<user href="/ovirt-engine/api/users/1234" id="1234">

<name>admin</name>
<namespace>*</namespace>
<principal>admin</principal>
<user_name>admin@internal-authz</user_name>
<domain href="/ovirt-engine/api/domains/5678" id="5678">
<name>internal-authz</name>
</domain>
<groups/>
</user>

Table 5.154. Parameters summary

Name Type Direction Summary

user User Out The domain user.

5.52. DOMAINUSERS
A service to list all domain users in the system.

Table 5.155. Methods summary

Name Summary

list List all the users in the domain.

5.52.1. list GET

List all the users in the domain.

Usage:

GET /ovirt-engine/api/domains/5678/users

Will return the list of users in the domain:

126
 CHAPTER 5. SERVICES

<users>
<user href="/ovirt-engine/api/domains/5678/users/1234" id="1234">
<name>admin</name>
<namespace>*</namespace>
<principal>admin</principal>
<user_name>admin@internal-authz</user_name>
<domain href="/ovirt-engine/api/domains/5678" id="5678">
<name>internal-authz</name>
</domain>
<groups/>
</user>
</users>

Table 5.156. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

max Integer In Sets the maximum number of users to return.

search String In A query string used to restrict the returned users.

users User[] Out The list of users in the domain.

5.52.1.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.52.1.2. max

Sets the maximum number of users to return. If not specified all the users are returned.

5.53. DOMAINS

A service to list all authentication domains in the system.

Table 5.157. Methods summary

127
Red Hat Virtualization 4.0 REST API Guide

Name Summary

list List all the authentication domains in the system.

5.53.1. list GET

List all the authentication domains in the system.

Usage:

GET /ovirt-engine/api/domains

Will return the list of domains:

<domains>
<domain href="/ovirt-engine/api/domains/5678" id="5678">
<name>internal-authz</name>
<link href="/ovirt-engine/api/domains/5678/users" rel="users"/>
<link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/>
<link href="/ovirt-engine/api/domains/5678/users?search={query}"
rel="users/search"/>
<link href="/ovirt-engine/api/domains/5678/groups?search={query}"
rel="groups/search"/>
</domain>
</domains>

Table 5.158. Parameters summary

Name Type Direction Summary

domains Domain[] Out The list of domains.

max Integer In Sets the maximum number of domains to return.

5.53.1.1. max

Sets the maximum number of domains to return. If not specified all the domains are returned.

5.54. ENGINEKATELLOERRATA

A service to manage Katello errata assigned to the engine. The information is retrieved from Katello.

Table 5.159. Methods summary

128
 CHAPTER 5. SERVICES

Name Summary

list Retrieves the representation of the Katello errata.

5.54.1. list GET

Retrieves the representation of the Katello errata.

GET /ovirt-engine/api/katelloerrata

You will receive response in XML like this one:

<katello_errata>
<katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for
XYZ</summary>
<packages>
<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...
</packages>
</katello_erratum>
...
</katello_errata>

Table 5.160. Parameters summary

Name Type Direction Summary

errata KatelloErrat Out A representation of Katello errata.

um[]

max Integer In Sets the maximum number of errata to return.

5.54.1.1. max

Sets the maximum number of errata to return. If not specified all the errata are returned.

5.55. EVENT

129
Red Hat Virtualization 4.0 REST API Guide

5.55. EVENT

A service to manage an event in the system.

Table 5.161. Methods summary

Name Summary

get Get an event.

remove Removes an event from internal audit log.

5.55.1. get GET

Get an event.

An example of getting an event:

GET /ovirt-engine/api/events/123

<event href="/ovirt-engine/api/events/123" id="123">

<description>Host example.com was added by admin@internal-
authz.</description>
<code>42</code>
<correlation_id>135</correlation_id>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-12-11T11:13:44.654+02:00</time>
<cluster href="/ovirt-engine/api/clusters/456" id="456"/>
<host href="/ovirt-engine/api/hosts/789" id="789"/>
<user href="/ovirt-engine/api/users/987" id="987"/>
</event>

Note that the number of fields changes according to the information that resides on the event. For
example, for storage domain related events you will get the storage domain reference, as well as
the reference for the data center this storage domain resides in.

Table 5.162. Parameters summary

Name Type Direction Summary

event Event Out

5.55.2. remove DELETE

130
 CHAPTER 5. SERVICES

Removes an event from internal audit log.

An event can be removed by sending following request

DELETE /ovirt-engine/api/events/123

Table 5.163. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.56. EVENTS

A service to manage events in the system.

Table 5.164. Methods summary

Name Summary

add Adds an external event to the internal audit log.

list Get list of events.

undelete

5.56.1. add POST

Adds an external event to the internal audit log.

This is intended for integration with external systems that detect or produce events relevant for the
administrator of the system. For example, an external monitoring tool may be able to detect that a
file system is full inside the guest operating system of a virtual machine. This event can be added to
the internal audit log sending a request like this:

POST /ovirt-engine/api/events
<event>
<description>File system /home is full</description>
<severity>alert</severity>
<origin>mymonitor</origin>
<custom_id>1467879754</custom_id>
</event>

131
Red Hat Virtualization 4.0 REST API Guide

Events can also be linked to specific objects. For example, the above event could be linked to the
specific virtual machine where it happened, using the vm link:

POST /ovirt-engine/api/events
<event>
<description>File system /home is full</description>
<severity>alert</severity>
<origin>mymonitor</origin>
<custom_id>1467879754</custom_id>
<vm id="aae98225-5b73-490d-a252-899209af17e9"/>
</event>

Note

When using links, like the vm in the previous example, only the id attribute is accepted.
The name attribute, if provided, is simply ignored.

Table 5.165. Parameters summary

Name Type Direction Summary

event Event In/Out

5.56.2. list GET

Get list of events.

GET /ovirt-engine/api/events

To the above request we get following response:

<events>
<event href="/ovirt-engine/api/events/2" id="2">
<description>User admin@internal-authz logged out.</description>
<code>31</code>
<correlation_id>1e892ea9</correlation_id>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-09-14T12:14:34.541+02:00</time>
<user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-
000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
</event>
<event href="/ovirt-engine/api/events/1" id="1">
<description>User admin logged in.</description>
<code>30</code>
<correlation_id>1fbd81f4</correlation_id>
<custom_id>-1</custom_id>

132
 CHAPTER 5. SERVICES

<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-09-14T11:54:35.229+02:00</time>
<user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-
000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
</event>
</events>

The following events occur:

id="1" - The API logs in the admin user account.

id="2" - The API logs out of the admin user account.

Table 5.166. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

events Event[] Out

from Integer In Indicates the identifier of the the first event that
should be returned.

max Integer In Sets the maximum number of events to return.

search String In The events service provides search queries similar

to other resource services.

5.56.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.56.2.2. from

Indicates the identifier of the the first event that should be returned. The identifiers of events are
strictly increasing, so when this parameter is used only the events with that identifiers equal or
greater than the given value will be returned. For example, the following request will return only the
events with identifiers greater or equal than 123:

133
Red Hat Virtualization 4.0 REST API Guide

GET /ovirt-engine/api/events?from=123

This parameter is optional, and if not specified then the first event returned will be most recently
generated.

5.56.2.3. max

Sets the maximum number of events to return. If not specified all the events are returned.

5.56.2.4. search

The events service provides search queries similar to other resource services.

We can search by providing specific severity.

GET /ovirt-engine/api/events?search=severity%3Dnormal

To the above request we get a list of events which severity is equal to normal:

<events>
<event href="/ovirt-engine/api/events/2" id="2">
<description>User admin@internal-authz logged out.</description>
<code>31</code>
<correlation_id>1fbd81f4</correlation_id>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-09-14T11:54:35.229+02:00</time>
<user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-
000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
</event>
<event href="/ovirt-engine/api/events/1" id="1">
<description>Affinity Rules Enforcement Manager
started.</description>
<code>10780</code>
<custom_id>-1</custom_id>
<flood_rate>30</flood_rate>
<origin>oVirt</origin>
<severity>normal</severity>
<time>2016-09-14T11:52:18.861+02:00</time>
</event>
</events>

A virtualization environment generates a large amount of events after a period of time. However, the
API only displays a default number of events for one search query. To display more than the default,
the API separates results into pages with the page command in a search query. The following
search query tells the API to paginate results using a page value in combination with the sortby
clause:

sortby time asc page 1

Below example paginates event resources. The URL-encoded request is:

134
 CHAPTER 5. SERVICES

GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201

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

GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202

5.56.3. undelete POST

Table 5.167. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the un-delete should be performed

asynchronously.

5.57. EXTERNALCOMPUTERESOURCE

Table 5.168. Methods summary

Name Summary

get

5.57.1. get GET

Table 5.169. Parameters summary

Name Type Direction Summary

resource ExternalCo Out

mputeResou
rce

5.58. EXTERNALCOMPUTERESOURCES

Table 5.170. Methods summary

135
Red Hat Virtualization 4.0 REST API Guide

Name Summary

list

5.58.1. list GET

Table 5.171. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of resources to return.

resource ExternalCo Out

s mputeResou
rce[]

5.58.1.1. max

Sets the maximum number of resources to return. If not specified all the resources are returned.

5.59. EXTERNALDISCOVEREDHOST

Table 5.172. Methods summary

Name Summary

get

5.59.1. get GET

Table 5.173. Parameters summary

Name Type Direction Summary

host ExternalDisc Out

overedHost

136
 CHAPTER 5. SERVICES

5.60. EXTERNALDISCOVEREDHOSTS

Table 5.174. Methods summary

Name Summary

list

5.60.1. list GET

Table 5.175. Parameters summary

Name Type Direction Summary

hosts ExternalDisc Out

overedHost[]

max Integer In Sets the maximum number of hosts to return.

5.60.1.1. max

Sets the maximum number of hosts to return. If not specified all the hosts are returned.

5.61. EXTERNALHOST

Table 5.176. Methods summary

Name Summary

get

5.61.1. get GET

Table 5.177. Parameters summary

137
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

host ExternalHost Out

5.62. EXTERNALHOSTGROUP

Table 5.178. Methods summary

Name Summary

get

5.62.1. get GET

Table 5.179. Parameters summary

Name Type Direction Summary

group ExternalHost Out

Group

5.63. EXTERNALHOSTGROUPS

Table 5.180. Methods summary

Name Summary

list

5.63.1. list GET

Table 5.181. Parameters summary

138
 CHAPTER 5. SERVICES

Name Type Direction Summary

groups ExternalHost Out

Group[]

max Integer In Sets the maximum number of groups to return.

5.63.1.1. max

Sets the maximum number of groups to return. If not specified all the groups are returned.

5.64. EXTERNALHOSTPROVIDER

Table 5.182. Methods summary

Name Summary

get

importcertif
icates

remove

testconnecti
vity

update

5.64.1. get GET

Table 5.183. Parameters summary

Name Type Direction Summary

139
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

provider ExternalHost Out

Provider

5.64.2. importcertificates POST

Table 5.184. Parameters summary

Name Type Direction Summary

certific Certificate[] In
ates

5.64.3. remove DELETE

Table 5.185. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.64.4. testconnectivity POST

Table 5.186. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the test should be performed

asynchronously.

5.64.5. update PUT

Table 5.187. Parameters summary

140
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

provider ExternalHost In/Out

Provider

5.65. EXTERNALHOSTPROVIDERS

Table 5.188. Methods summary

Name Summary

add

list

5.65.1. add POST

Table 5.189. Parameters summary

Name Type Direction Summary

provider ExternalHost In/Out

Provider

5.65.2. list GET

Table 5.190. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of providers to return.

141
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

provider ExternalHost Out

s Provider[]

5.65.2.1. max

Sets the maximum number of providers to return. If not specified all the providers are returned.

5.66. EXTERNALHOSTS

Table 5.191. Methods summary

Name Summary

list

5.66.1. list GET

Table 5.192. Parameters summary

Name Type Direction Summary

hosts ExternalHost Out

[]

max Integer In Sets the maximum number of hosts to return.

5.66.1.1. max

Sets the maximum number of hosts to return. If not specified all the hosts are returned.

5.67. EXTERNALPROVIDER

Table 5.193. Methods summary

142
 CHAPTER 5. SERVICES

Name Summary

importcertif
icates

testconnecti
vity

5.67.1. importcertificates POST

Table 5.194. Parameters summary

Name Type Direction Summary

certific Certificate[] In
ates

5.67.2. testconnectivity POST

Table 5.195. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the test should be performed

asynchronously.

5.68. EXTERNALPROVIDERCERTIFICATE

Table 5.196. Methods summary

Name Summary

get

5.68.1. get GET

143
Red Hat Virtualization 4.0 REST API Guide

Table 5.197. Parameters summary

Name Type Direction Summary

certific Certificate Out

ate

5.69. EXTERNALPROVIDERCERTIFICATES

Table 5.198. Methods summary

Name Summary

list

5.69.1. list GET

Table 5.199. Parameters summary

Name Type Direction Summary

certific Certificate[] Out

ates

max Integer In Sets the maximum number of certificates to return.

5.69.1.1. max

Sets the maximum number of certificates to return. If not specified all the certificates are returned.

5.70. EXTERNALVMIMPORTS

Provides capability to import external virtual machines.

Table 5.200. Methods summary

144
 CHAPTER 5. SERVICES

Name Summary

add This operation is used to import a virtual machine from external hypervisor, such as
KVM, XEN or VMware.

5.70.1. add POST

This operation is used to import a virtual machine from external hypervisor, such as KVM, XEN or
VMware.

For example import of a virtual machine from VMware can be facilitated using the following request:

POST /externalvmimports

With request body of type ExternalVmImport, for example:

<external_vm_import>
<vm>
<name>my_vm</name>
</vm>
<cluster id="360014051136c20574f743bdbd28177fd" />
<storage_domain id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
<name>vm_name_as_is_in_vmware</name>
<sparse>true</sparse>
<username>vmware_user</username>
<password>123456</password>
<provider>VMWARE</provider>
<url>vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?
no_verify=1</url>
<drivers_iso id="virtio-win-1.6.7.iso" />
</external_vm_import>

Table 5.201. Parameters summary

Name Type Direction Summary

import ExternalVmI In/Out

mport

5.71. FENCEAGENT

Table 5.202. Methods summary

145
Red Hat Virtualization 4.0 REST API Guide

Name Summary

get

remove

update

5.71.1. get GET

Table 5.203. Parameters summary

Name Type Direction Summary

agent Agent Out

5.71.2. remove DELETE

Table 5.204. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.71.3. update PUT

Table 5.205. Parameters summary

Name Type Direction Summary

agent Agent In/Out

async Boolean In Indicates if the update should be performed

asynchronously.

146
 CHAPTER 5. SERVICES

Name Type Direction Summary

5.72. FENCEAGENTS

Table 5.206. Methods summary

Name Summary

add

list

5.72.1. add POST

Table 5.207. Parameters summary

Name Type Direction Summary

agent Agent In/Out

5.72.2. list GET

Table 5.208. Parameters summary

Name Type Direction Summary

agents Agent[] Out

max Integer In Sets the maximum number of agents to return.

5.72.2.1. max

Sets the maximum number of agents to return. If not specified all the agents are returned.

147
Red Hat Virtualization 4.0 REST API Guide

5.73. FILE

Table 5.209. Methods summary

Name Summary

get

5.73.1. get GET

Table 5.210. Parameters summary

Name Type Direction Summary

file File Out

5.74. FILES

Provides a way for clients to list available files.

This services is specifically targeted to ISO storage domains, which contain ISO images and virtual
floppy disks (VFDs) that an administrator uploads.

The addition of a CDROM device to a virtual machine requires an ISO image from the files of an
ISO storage domain.

Table 5.211. Methods summary

Name Summary

list

5.74.1. list GET

Table 5.212. Parameters summary

148
 CHAPTER 5. SERVICES

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

file File[] Out

max Integer In Sets the maximum number of files to return.

search String In A query string used to restrict the returned files.

5.74.1.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.74.1.2. max

Sets the maximum number of files to return. If not specified all the files are returned.

5.75. FILTER

Table 5.213. Methods summary

Name Summary

get

remove

5.75.1. get GET

Table 5.214. Parameters summary

149
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

result Filter Out

5.75.2. remove DELETE

Table 5.215. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.76. FILTERS

Table 5.216. Methods summary

Name Summary

add

list

5.76.1. add POST

Table 5.217. Parameters summary

Name Type Direction Summary

filter Filter In/Out

5.76.2. list GET

150
 CHAPTER 5. SERVICES

Table 5.218. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

filters Filter[] Out

max Integer In Sets the maximum number of filters to return.

5.76.2.1. max

Sets the maximum number of filters to return. If not specified all the filters are returned.

5.77. GLUSTERBRICK
This service manages a single gluster brick.

Table 5.219. Methods summary

Name Summary

get Get details of a brick.

remove Removes a brick.

replace Replaces this brick with a new one.

5.77.1. get GET

Get details of a brick.

Retrieves status details of brick from underlying gluster volume with header All-Content set to
true. This is the equivalent of running gluster volume status <volumename>
<brickname> detail.

For example, to get the details of brick 234 of gluster volume 123, send a request like this:

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234

151
Red Hat Virtualization 4.0 REST API Guide

Which will return a response body like this:

<brick id="234">
<name>host1:/rhgs/data/brick1</name>
<brick_dir>/rhgs/data/brick1</brick_dir>
<server_id>111</server_id>
<status>up</status>
<device>/dev/mapper/RHGS_vg1-lv_vmaddldisks</device>
<fs_name>xfs</fs_name>
<gluster_clients>
<gluster_client>
<bytes_read>2818417648</bytes_read>
<bytes_written>1384694844</bytes_written>
<client_port>1011</client_port>
<host_name>client2</host_name>
</gluster_client>
</gluster_clients>
<memory_pools>
<memory_pool>
<name>data-server:fd_t</name>
<alloc_count>1626348</alloc_count>
<cold_count>1020</cold_count>
<hot_count>4</hot_count>
<max_alloc>23</max_alloc>
<max_stdalloc>0</max_stdalloc>
<padded_size>140</padded_size>
<pool_misses>0</pool_misses>
</memory_pool>
</memory_pools>

<mnt_options>rw,seclabel,noatime,nodiratime,attr2,inode64,sunit=512,swidt
h=2048,noquota</mnt_options>
<pid>25589</pid>
<port>49155</port>
</brick>

Table 5.220. Parameters summary

Name Type Direction Summary

brick GlusterBrick Out

5.77.2. remove DELETE

Removes a brick.

Removes a brick from the underlying gluster volume and deletes entries from database. This can be
used only when removing a single brick without data migration. To remove multiple bricks and with
data migration, use migrate instead.

For example, to delete brick 234 from gluster volume 123, send a request like this:

152
 CHAPTER 5. SERVICES

DELETE /ovirt-
engine/api/clusters/567/glustervolumes/123/glusterbricks/234

Table 5.221. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.77.3. replace POST

Replaces this brick with a new one.

Important

This operation has been deprecated since version 3.5 of the engine and will be removed
in the future. Use add brick(s) and migrate brick(s) instead.

Table 5.222. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the replacement should be performed

asynchronously.

force Boolean In

5.78. GLUSTERBRICKS
This service manages the gluster bricks in a gluster volume

Table 5.223. Methods summary

Name Summary

activate Activate the bricks post data migration of remove brick operation.

153
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add Adds a list of bricks to gluster volume.

list Lists the bricks of a gluster volume.

migrate Start migration of data prior to removing bricks.

remove Removes bricks from gluster volume.

stopmigrate Stops migration of data from bricks for a remove brick operation.

5.78.1. activate POST

Activate the bricks post data migration of remove brick operation.

Used to activate brick(s) once the data migration from bricks is complete but user no longer wishes
to remove bricks. The bricks that were previously marked for removal will now be used as normal
bricks.

For example, to retain the bricks that on glustervolume 123 from which data was migrated, send a
request like this:

POST /ovirt-
engine/api/clusters/567/glustervolumes/123/glusterbricks/activate

With a request body like this:

<action>
<bricks>
<brick>
<name>host1:/rhgs/brick1</name>
</brick>
</bricks>
</action>

Table 5.224. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the activation should be performed

asynchronously.

154
 CHAPTER 5. SERVICES

Name Type Direction Summary

bricks GlusterBrick[ In The list of bricks that need to be re-activated.

]

5.78.2. add POST

Adds a list of bricks to gluster volume.

Used to expand a gluster volume by adding bricks. For replicated volume types, the parameter
replica_count needs to be passed. In case the replica count is being increased, then the number
of bricks needs to be equivalent to the number of replica sets.

For example, to add bricks to gluster volume 123, send a request like this:

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

With a request body like this:

<bricks>
<brick>
<server_id>111</server_id>
<brick_dir>/export/data/brick3</brick_dir>
</brick>
</bricks>

Table 5.225. Parameters summary

Name Type Direction Summary

bricks GlusterBrick[ In/Out The list of bricks to be added to the volume

]

replica_ Integer In Replica count of volume post add operation.

count

stripe_c Integer In Stripe count of volume post add operation.

ount

5.78.3. list GET

Lists the bricks of a gluster volume.

For example, to list bricks of gluster volume 123, send a request like this:

155
Red Hat Virtualization 4.0 REST API Guide

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

Provides an output as below:

<bricks>
<brick id="234">
<name>host1:/rhgs/data/brick1</name>
<brick_dir>/rhgs/data/brick1</brick_dir>
<server_id>111</server_id>
<status>up</status>
</brick>
<brick id="233">
<name>host2:/rhgs/data/brick1</name>
<brick_dir>/rhgs/data/brick1</brick_dir>
<server_id>222</server_id>
<status>up</status>
</brick>
</bricks>

Table 5.226. Parameters summary

Name Type Direction Summary

bricks GlusterBrick[ Out

]

max Integer In Sets the maximum number of bricks to return.

5.78.3.1. max

Sets the maximum number of bricks to return. If not specified all the bricks are returned.

5.78.4. migrate POST

Start migration of data prior to removing bricks.

Removing bricks is a two-step process, where the data on bricks to be removed, is first migrated to
remaining bricks. Once migration is completed the removal of bricks is confirmed via the API
remove. If at any point, the action needs to be cancelled stopmigrate has to be called.

For instance, to delete a brick from a gluster volume with id 123, send a request:

POST /ovirt-
engine/api/clusters/567/glustervolumes/123/glusterbricks/migrate

With a request body like this:

<action>
<bricks>

156
 CHAPTER 5. SERVICES

<brick>
<name>host1:/rhgs/brick1</name>
</brick>
</bricks>
</action>

The migration process can be tracked from the job id returned from the API using job and steps in
job using step

Table 5.227. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the migration should be performed

asynchronously.

bricks GlusterBrick[ In List of bricks for which data migration needs to be

] started.

5.78.5. remove DELETE

Removes bricks from gluster volume.

The recommended way to remove bricks without data loss is to first migrate the data using
stopmigrate and then removing them. If migrate was not called on bricks prior to remove, the bricks
are removed without data migration which may lead to data loss.

For example, to delete the bricks from gluster volume 123, send a request like this:

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

With a request body like this:

<bricks>
<brick>
<name>host:brick_directory</name>
</brick>
</bricks>

Table 5.228. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

157
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

bricks GlusterBrick[ In The list of bricks to be removed

]

replica_ Integer In Replica count of volume post add operation.

count

5.78.6. stopmigrate POST

Stops migration of data from bricks for a remove brick operation.

To cancel data migration that was started as part of the 2-step remove brick process in case the
user wishes to continue using the bricks. The bricks that were marked for removal will function as
normal bricks post this operation.

For example, to stop migration of data from the bricks of gluster volume 123, send a request like
this:

POST /ovirt-
engine/api/clusters/567/glustervolumes/123/glusterbricks/stopmigrate

With a request body like this:

<bricks>
<brick>
<name>host:brick_directory</name>
</brick>
</bricks>

Table 5.229. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

bricks GlusterBrick[ In List of bricks for which data migration needs to be

] stopped.

5.78.6.1. bricks

List of bricks for which data migration needs to be stopped. This list should match the arguments
passed to migrate.

158
 CHAPTER 5. SERVICES

5.79. GLUSTERHOOK

Table 5.230. Methods summary

Name Summary

disable Resolves status conflict of hook among servers in cluster by disabling Gluster hook
in all servers of the cluster.

enable Resolves status conflict of hook among servers in cluster by disabling Gluster hook
in all servers of the cluster.

get

remove Removes the this Gluster hook from all servers in cluster and deletes it from the
database.

resolve Resolves missing hook conflict depending on the resolution type.

5.79.1. disable POST

Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of
the cluster. This updates the hook status to DISABLED in database.

Table 5.231. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.79.2. enable POST

Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of
the cluster. This updates the hook status to DISABLED in database.

Table 5.232. Parameters summary

159
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.79.3. get GET

Table 5.233. Parameters summary

Name Type Direction Summary

hook GlusterHook Out

5.79.4. remove DELETE

Removes the this Gluster hook from all servers in cluster and deletes it from the database.

Table 5.234. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.79.5. resolve POST

Resolves missing hook conflict depending on the resolution type.

For ADD resolves by copying hook stored in engine database to all servers where the hook is
missing. The engine maintains a list of all servers where hook is missing.

For COPY resolves conflict in hook content by copying hook stored in engine database to all servers
where the hook is missing. The engine maintains a list of all servers where the content is conflicting.
If a host id is passed as parameter, the hook content from the server is used as the master to copy
to other servers in cluster.

Table 5.235. Parameters summary

160
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

host Host In

resoluti String In
on_type

5.80. GLUSTERHOOKS

Table 5.236. Methods summary

Name Summary

list

5.80.1. list GET

Table 5.237. Parameters summary

Name Type Direction Summary

hooks GlusterHook Out

[]

max Integer In Sets the maximum number of hooks to return.

5.80.1.1. max

Sets the maximum number of hooks to return. If not specified all the hooks are returned.

5.81. GLUSTERVOLUME

This service manages a single gluster volume.

161
Red Hat Virtualization 4.0 REST API Guide

Table 5.238. Methods summary

Name Summary

get Get the gluster volume details.

getprofilest Get gluster volume profile statistics.

atistics

rebalance Rebalance the gluster volume.

remove Removes the gluster volume.

resetallopti Resets all the options set in the gluster volume.

ons

resetoption Resets a particular option in the gluster volume.

setoption Sets a particular option in the gluster volume.

start Starts the gluster volume.

startprofile Start profiling the gluster volume.

stop Stops the gluster volume.

stopprofile Stop profiling the gluster volume.

stoprebalanc Stop rebalancing the gluster volume.

e

5.81.1. get GET

Get the gluster volume details.

162
 CHAPTER 5. SERVICES

For example, to get details of a gluster volume with identifier 123 in cluster 456, send a request like
this:

GET /ovirt-engine/api/clusters/456/glustervolumes/123

This GET request will return the following output:

<gluster_volume id="123">
<name>data</name>
<link href="/ovirt-
engine/api/clusters/456/glustervolumes/123/glusterbricks"
rel="glusterbricks"/>
<disperse_count>0</disperse_count>
<options>
<option>
<name>storage.owner-gid</name>
<value>36</value>
</option>
<option>
<name>performance.io-cache</name>
<value>off</value>
</option>
<option>
<name>cluster.data-self-heal-algorithm</name>
<value>full</value>
</option>
</options>
<redundancy_count>0</redundancy_count>
<replica_count>3</replica_count>
<status>up</status>
<stripe_count>0</stripe_count>
<transport_types>
<transport_type>tcp</transport_type>
</transport_types>
<volume_type>replicate</volume_type>
</gluster_volume>

Table 5.239. Parameters summary

Name Type Direction Summary

volume GlusterVolu Out Representation of the gluster volume.

me

5.81.2. getprofilestatistics POST

Get gluster volume profile statistics.

For example, to get profile statistics for a gluster volume with identifier 123 in cluster 456, send a
request like this:

163
Red Hat Virtualization 4.0 REST API Guide

POST /ovirt-
engine/api/clusters/456/glustervolumes/123/getprofilestatistics

Table 5.240. Parameters summary

Name Type Direction Summary

details GlusterVolu Out Gluster volume profiling information returned from

meProfileDe the action.
tails

5.81.3. rebalance POST

Rebalance the gluster volume.

Rebalancing a gluster volume helps to distribute the data evenly across all the bricks. After
expanding or shrinking a gluster volume (without migrating data), we need to rebalance the data
among the bricks. In a non-replicated volume, all bricks should be online to perform the rebalance
operation. In a replicated volume, at least one of the bricks in the replica should be online.

For example, to rebalance a gluster volume with identifier 123 in cluster 456, send a request like
this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/rebalance

Table 5.241. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the rebalance should be performed

asynchronously.

fix_layo Boolean In If set to true, rebalance will only fix the layout so
ut that new data added to the volume is distributed
across all the hosts.

force Boolean In Indicates if the rebalance should be force started.

5.81.3.1. fix_layout

If set to true, rebalance will only fix the layout so that new data added to the volume is distributed
across all the hosts. But it will not migrate/rebalance the existing data. Default is false.

164
 CHAPTER 5. SERVICES

5.81.3.2. force

Indicates if the rebalance should be force started. The rebalance command can be executed with
the force option even when the older clients are connected to the cluster. However, this could lead to
a data loss situation. Default is false.

5.81.4. remove DELETE

Removes the gluster volume.

For example, to remove a volume with identifier 123 in cluster 456, send a request like this:

DELETE /ovirt-engine/api/clusters/456/glustervolumes/123

Table 5.242. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.81.5. resetalloptions POST

Resets all the options set in the gluster volume.

For example, to reset all options in a gluster volume with identifier 123 in cluster 456, send a
request like this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetalloptions

Table 5.243. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the reset should be performed

asynchronously.

5.81.6. resetoption POST

Resets a particular option in the gluster volume.

For example, to reset a particular option option1 in a gluster volume with identifier 123 in cluster
456, send a request like this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetoption

165
Red Hat Virtualization 4.0 REST API Guide

With the following request body:

<action>
<option name="option1"/>
</action>

Table 5.244. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the reset should be performed

asynchronously.

force Boolean In

option Option In Option to reset.

5.81.7. setoption POST

Sets a particular option in the gluster volume.

For example, to set option1 with value value1 in a gluster volume with identifier 123 in cluster
456, send a request like this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/setoption

With the following request body:

<action>
<option name="option1" value="value1"/>
</action>

Table 5.245. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

option Option In Option to set.

166
 CHAPTER 5. SERVICES

5.81.8. start POST

Starts the gluster volume.

A Gluster Volume should be started to read/write data. For example, to start a gluster volume with
identifier 123 in cluster 456, send a request like this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/start

Table 5.246. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

force Boolean In Indicates if the volume should be force started.

5.81.8.1. force

Indicates if the volume should be force started. If a gluster volume is started already but few/all
bricks are down then force start can be used to bring all the bricks up. Default is false.

5.81.9. startprofile POST

Start profiling the gluster volume.

For example, to start profiling a gluster volume with identifier 123 in cluster 456, send a request like
this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/startprofile

Table 5.247. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.81.10. stop POST

Stops the gluster volume.

Stopping a volume will make its data inaccessible.

167
Red Hat Virtualization 4.0 REST API Guide

For example, to stop a gluster volume with identifier 123 in cluster 456, send a request like this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stop

Table 5.248. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

force Boolean In

5.81.11. stopprofile POST

Stop profiling the gluster volume.

For example, to stop profiling a gluster volume with identifier 123 in cluster 456, send a request like
this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stopprofile

Table 5.249. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.81.12. stoprebalance POST

Stop rebalancing the gluster volume.

For example, to stop rebalancing a gluster volume with identifier 123 in cluster 456, send a request
like this:

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stoprebalance

Table 5.250. Parameters summary

168
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.82. GLUSTERVOLUMES

This service manages a collection of gluster volumes available in a cluster.

Table 5.251. Methods summary

Name Summary

add Creates a new gluster volume.

list Lists all gluster volumes in the cluster.

5.82.1. add POST

Creates a new gluster volume.

The volume is created based on properties of the volume parameter. The properties name,
volume_type and bricks are required.

For example, to add a volume with name myvolume to the cluster 123, send the following request:

POST /ovirt-engine/api/clusters/123/glustervolumes

With the following request body:

<gluster_volume>
<name>myvolume</name>
<volume_type>replicate</volume_type>
<replica_count>3</replica_count>
<bricks>
<brick>
<server_id>server1</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
<brick>
<server_id>server2</server_id>
<brick_dir>/exp1</brick_dir>
</brick>
<brick>
<server_id>server3</server_id>

169
Red Hat Virtualization 4.0 REST API Guide

<brick_dir>/exp1</brick_dir>
</brick>
<bricks>
</gluster_volume>

Table 5.252. Parameters summary

Name Type Direction Summary

volume GlusterVolu In/Out The gluster volume definition from which to create
me the volume is passed as input and the newly
created volume is returned.

5.82.2. list GET

Lists all gluster volumes in the cluster.

For example, to list all Gluster Volumes in cluster 456, send a request like this:

GET /ovirt-engine/api/clusters/456/glustervolumes

Table 5.253. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

max Integer In Sets the maximum number of volumes to return.

search String In A query string used to restrict the returned

volumes.

volumes GlusterVolu Out

me[]

5.82.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

170
 CHAPTER 5. SERVICES

5.82.2.2. max

Sets the maximum number of volumes to return. If not specified all the volumes are returned.

5.83. GRAPHICSCONSOLE

Table 5.254. Methods summary

Name Summary

get Gets the configuration of the graphics console.

remove

5.83.1. get GET

Gets the configuration of the graphics console.

Table 5.255. Parameters summary

Name Type Direction Summary

console GraphicsCo Out

nsole

current Boolean In Use the following query to obtain the current run-
time configuration of the graphics console.

5.83.1.1. current

Use the following query to obtain the current run-time configuration of the graphics console.

GET /ovit-engine/api/vms/{vm:id}/graphicsconsoles/{console:id}?
current=true

The default value is false.

5.83.2. remove DELETE

Table 5.256. Parameters summary

171
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.84. GRAPHICSCONSOLES

Table 5.257. Methods summary

Name Summary

add

list Lists all the configured graphics consoles of the virtual machine.

5.84.1. add POST

Table 5.258. Parameters summary

Name Type Direction Summary

console GraphicsCo In/Out

nsole

5.84.2. list GET

Lists all the configured graphics consoles of the virtual machine.

Table 5.259. Parameters summary

Name Type Direction Summary

consoles GraphicsCo Out

nsole[]

172
 CHAPTER 5. SERVICES

Name Type Direction Summary

current Boolean In Use the following query to obtain the current run-
time configuration of the graphics consoles.

max Integer In Sets the maximum number of consoles to return.

5.84.2.1. current

Use the following query to obtain the current run-time configuration of the graphics consoles.

GET /ovirt-engine/api/vms/123/graphicsconsoles?current=true

The default value is false.

5.84.2.2. max

Sets the maximum number of consoles to return. If not specified all the consoles are returned.

5.85. GROUP

Table 5.260. Methods summary

Name Summary

get

remove

5.85.1. get GET

Table 5.261. Parameters summary

Name Type Direction Summary

get Group Out

5.85.2. remove DELETE

173
Red Hat Virtualization 4.0 REST API Guide

Table 5.262. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.86. GROUPS

Table 5.263. Methods summary

Name Summary

add Add group from a directory service.

list

5.86.1. add POST

Add group from a directory service. Please note that domain name is name of the authorization
provider.

For example, to add the Developers group from the internal-authz authorization provider
send a request like this:

POST /ovirt-engine/api/groups

With a request body like this:

<group>
<name>Developers</name>
<domain>
<name>internal-authz</name>
</domain>
</group>

Table 5.264. Parameters summary

Name Type Direction Summary

group Group In/Out

174
 CHAPTER 5. SERVICES

5.86.2. list GET

Table 5.265. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

groups Group[] Out

max Integer In Sets the maximum number of groups to return.

search String In A query string used to restrict the returned groups.

5.86.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.86.2.2. max

Sets the maximum number of groups to return. If not specified all the groups are returned.

5.87. HOST

A service to manage a host.

Table 5.266. Methods summary

Name Summary

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

approve Approve a pre-installed Hypervisor host for usage in the virtualization environment.

175
Red Hat Virtualization 4.0 REST API Guide

Name Summary

commitnetcon Marks the network configuration as good and persists it inside the host.
fig

deactivate Deactivate the host to perform maintenance tasks.

enrollcertif Enroll certificate of the host.

icate

fence Controls host’s power management device.

forceselects Manually set a host as the storage pool manager (SPM).

pm

get Get the host details.

install Install VDSM and related software on the host.

iscsidiscove Discover iSCSI targets on the host, using the initiator details.
r

iscsilogin Login to iSCSI targets on the host, using the target details.

refresh Refresh the host devices and capabilities.

remove Remove the host from the system.

setupnetwork This method is used to change the configuration of the network interfaces of a host.
s

unregistered
storagedomai
nsdiscover

176
 CHAPTER 5. SERVICES

Name Summary

update Update the host properties.

upgrade Upgrade VDSM and selected software on the host.

5.87.1. activate POST

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

Table 5.267. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the activation should be performed

asynchronously.

5.87.2. approve POST

Approve a pre-installed Hypervisor host for usage in the virtualization environment.

This action also accepts an optional cluster element to define the target cluster for this host.

Table 5.268. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the approval should be performed

asynchronously.

cluster Cluster In

5.87.3. commitnetconfig POST

Marks the network configuration as good and persists it inside the host.

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

177
Red Hat Virtualization 4.0 REST API Guide

Important

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

For example, to commit the network configuration of host with id 123 send a request like this:

POST /ovirt-engine/api/hosts/123/commitnetconfig

With a request body like this:

<action/>

Table 5.269. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.87.4. deactivate POST

Deactivate the host to perform maintenance tasks.

Table 5.270. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the deactivation should be performed

asynchronously.

reason String In

stop_glu Boolean In Indicates if the gluster service should be stopped

ster_ser as part of deactivating the host.
vice

5.87.4.1. stop_gluster_service

178
 CHAPTER 5. SERVICES

Indicates if the gluster service should be stopped as part of deactivating the host. It can be used
while performing maintenance operations on the gluster host. Default value for this variable is
false.

5.87.5. enrollcertificate POST

Enroll certificate of the host. Useful in case you get a warning that it is about to, or already expired.

Table 5.271. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the enrollment should be performed

asynchronously.

5.87.6. fence POST

Controls host’s power management device.

For example, let’s assume you want to start the host. This can be done via:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
<fence_type>start</fence_type>
</action>
' \
"${url}/hosts/123/fence"

Table 5.272. Parameters summary

Name Type Direction Summary

179
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the fencing should be performed

asynchronously.

fence_ty String In
pe

power_ma PowerMana Out

nagement gement

5.87.7. forceselectspm POST

Manually set a host as the storage pool manager (SPM).

POST /ovirt-engine/api/hosts/123/forceselectspm

With a request body like this:

<action/>

Table 5.273. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.87.8. get GET

Get the host details.

Table 5.274. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

180
 CHAPTER 5. SERVICES

Name Type Direction Summary

host Host Out

5.87.9. install POST

Install VDSM and related software on the host. The host type defines additional parameters for the
action.

Example of installing a host, using curl and JSON, plain:

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--request PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Version: 4" \
--user "admin@internal:..." \
--data '
{
"root_password": "myrootpassword"
}
' \
"https://engine.example.com/ovirt-engine/api/hosts/123"

Example of installing a host, using curl and JSON, with hosted engine components:

curl \
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--request PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Version: 4" \
--user "admin@internal:..." \
--data '
{
"root_password": "myrootpassword"
}
' \
"https://engine.example.com/ovirt-engine/api/hosts/123?
deploy_hosted_engine=true"

Table 5.275. Parameters summary

181
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the installation should be performed

asynchronously.

deploy_h Boolean In When set to true it means this host should deploy
osted_en also hosted engine components.
gine

host Host In This override_iptables property is used to

indicate if the firewall configuration should be
replaced by the default one.

image String In When installing an oVirt node a image ISO file is

needed.

root_pas String In The password of of the root user, used to

sword connect to the host via SSH.

ssh Ssh In The SSH details used to connect to the host.

undeploy Boolean In When set to true it means this host should un-
_hosted_ deploy hosted engine components and this host
engine will not function as part of the High Availability
cluster.

5.87.9.1. deploy_hosted_engine

When set to true it means this host should deploy also hosted engine components. Missing value
is treated as true i.e deploy. Omitting this parameter means false and will perform no operation in
hosted engine area.

5.87.9.2. undeploy_hosted_engine

When set to true it means this host should un-deploy hosted engine components and this host will
not function as part of the High Availability cluster. Missing value is treated as true i.e un-deploy
Omitting this parameter means false and will perform no operation in hosted engine area.

5.87.10. iscsidiscover POST

Discover iSCSI targets on the host, using the initiator details.

182
 CHAPTER 5. SERVICES

Table 5.276. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the discovery should be performed

asynchronously.

iscsi IscsiDetails In The target iSCSI device.

iscsi_ta String[] Out The iSCSI targets.

rgets

5.87.11. iscsilogin POST

Login to iSCSI targets on the host, using the target details.

Table 5.277. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the login should be performed

asynchronously.

iscsi IscsiDetails In The target iSCSI device.

5.87.12. refresh POST

Refresh the host devices and capabilities.

Table 5.278. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the refresh should be performed

asynchronously.

5.87.13. remove DELETE

Remove the host from the system.

183
Red Hat Virtualization 4.0 REST API Guide

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request DELETE \
--header "Version: 4" \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc"

Table 5.279. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.87.14. setupnetworks POST

This method is used to change the configuration of the network interfaces of a host.

For example, lets assume that you have a host with three network interfaces eth0, eth1 and eth2
and that you want to configure a new bond using eth0 and eth1, and put a VLAN on top of it. Using
a simple shell script and the curl command line HTTP client that can be done as follows:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
<modified_bonds>
<host_nic>
<name>bond0</name>
<bonding>
<options>
<option>

184
 CHAPTER 5. SERVICES

<name>mode</name>
<value>4</value>
</option>
<option>
<name>miimon</name>
<value>100</value>
</option>
</options>
<slaves>
<host_nic>
<name>eth1</name>
</host_nic>
<host_nic>
<name>eth2</name>
</host_nic>
</slaves>
</bonding>
</host_nic>
</modified_bonds>
<modified_network_attachments>
<network_attachment>
<network>
<name>myvlan</name>
</network>
<host_nic>
<name>bond0</name>
</host_nic>
<ip_address_assignments>
<assignment_method>static</assignment_method>
<ip_address_assignment>
<ip>
<address>192.168.122.10</address>
<netmask>255.255.255.0</netmask>
</ip>
</ip_address_assignment>
</ip_address_assignments>
</network_attachment>
</modified_network_attachments>
</action>
' \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc/setupnetworks"

Note that this is valid for version 4 of the API. In previous versions some elements were represented
as XML attributes instead of XML elements. In particular the options and ip elements were
represented as follows:

<options name="mode" value="4"/>

<options name="miimon" value="100"/>
<ip address="192.168.122.10" netmask="255.255.255.0"/>

Using the Python SDK the same can be done with the following code:

host.setupnetworks(
params.Action(
modified_bonds=params.HostNics(
host_nic=[

185
Red Hat Virtualization 4.0 REST API Guide

params.HostNIC(
name="bond0",
bonding=params.Bonding(
options=params.Options(
option=[
params.Option(name="mode", value="4"),
params.Option(name="miimon", value="100"),
],
),
slaves=params.Slaves(
host_nic=[
params.HostNIC(name="eth1"),
params.HostNIC(name="eth2"),
],
),
),
),
],
),
modified_network_attachments=params.NetworkAttachments(
network_attachment=[
params.NetworkAttachment(
network=params.Network(name="myvlan"),
host_nic=params.HostNIC(name="bond0"),
ip_address_assignments=params.IpAddressAssignments(
ip_address_assignment=[
params.IpAddressAssignment(
assignment_method="static",
ip=params.IP(
address="192.168.122.10",
netmask="255.255.255.0",
),
),
],
),
),
],
),
),
)

Important

To make sure that the network configuration has been saved in the host, and that it will be
applied when the host is rebooted, remember to call commitnetconfig.

Table 5.280. Parameters summary

Name Type Direction Summary

186
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

check_co Boolean In
nnectivi
ty

connecti Integer In
vity_tim
eout

modified HostNic[] In
_bonds

modified NetworkLab In
_labels el[]

modified NetworkAtta In
_network chment[]
_attachm
ents

removed_ HostNic[] In
bonds

removed_ NetworkLab In
labels el[]

removed_ NetworkAtta In
network_ chment[]
attachme
nts

synchron NetworkAtta In
ized_net chment[]
work_att
achments

187
Red Hat Virtualization 4.0 REST API Guide

5.87.15. unregisteredstoragedomainsdiscover POST

Table 5.281. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the discovery should be performed

asynchronously.

iscsi IscsiDetails In

storage_ StorageDom Out

domains ain[]

5.87.16. update PUT

Update the host properties.

For example, to update a the kernel command line of a host send a request like this:

PUT /ovirt-engine/api/hosts/123

With request body like this:

<host>
<os>

<custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom
_kernel_cmdline>
</os>
</host>

Table 5.282. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

host Host In/Out

5.87.17. upgrade POST

188
 CHAPTER 5. SERVICES

Upgrade VDSM and selected software on the host.

Table 5.283. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the upgrade should be performed

asynchronously.

5.88. HOSTDEVICE
A service to access a particular device of a host.

Table 5.284. Methods summary

Name Summary

get Retrieve information about a particular host’s device.

5.88.1. get GET

Retrieve information about a particular host’s device.

An example of getting a host device:

GET /ovirt-engine/api/hosts/123/devices/456

<host_device href="/ovirt-engine/api/hosts/123/devices/456" id="456">

<name>usb_1_9_1_1_0</name>
<capability>usb</capability>
<host href="/ovirt-engine/api/hosts/123" id="123"/>
<parent_device href="/ovirt-engine/api/hosts/123/devices/789" id="789">
<name>usb_1_9_1</name>
</parent_device>
</host_device>

Table 5.285. Parameters summary

Name Type Direction Summary

device HostDevice Out

189
Red Hat Virtualization 4.0 REST API Guide

5.89. HOSTDEVICES
A service to access host devices.

Table 5.286. Methods summary

Name Summary

list List the devices of a host.

5.89.1. list GET

List the devices of a host.

Table 5.287. Parameters summary

Name Type Direction Summary

devices HostDevice[] Out

max Integer In Sets the maximum number of devices to return.

5.89.1.1. max

Sets the maximum number of devices to return. If not specified all the devices are returned.

5.90. HOSTHOOK

Table 5.288. Methods summary

Name Summary

get

5.90.1. get GET

Table 5.289. Parameters summary

190
 CHAPTER 5. SERVICES

Name Type Direction Summary

hook Hook Out

5.91. HOSTHOOKS

Table 5.290. Methods summary

Name Summary

list

5.91.1. list GET

Table 5.291. Parameters summary

Name Type Direction Summary

hooks Hook[] Out

max Integer In Sets the maximum number of hooks to return.

5.91.1.1. max

Sets the maximum number of hooks to return. If not specified all the hooks are returned.

5.92. HOSTNIC
A service to manage a network interface of a host.

Table 5.292. Methods summary

Name Summary

get

191
Red Hat Virtualization 4.0 REST API Guide

Name Summary

updatevirtua The action updates virtual function configuration in case the current resource
lfunctionsco represents an SR-IOV enabled NIC.
nfiguration

5.92.1. get GET

Table 5.293. Parameters summary

Name Type Direction Summary

nic HostNic Out

5.92.2. updatevirtualfunctionsconfiguration POST

The action updates virtual function configuration in case the current resource represents an SR-IOV
enabled NIC. The input should be consisted of at least one of the following properties:

allNetworksAllowed

numberOfVirtualFunctions

Please see the HostNicVirtualFunctionsConfiguration type for the meaning of the

properties.

Table 5.294. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

virtual_ HostNicVirtu In
function alFunctions
s_config Configuratio
uration n

5.93. HOSTNICS

A service to manage the network interfaces of a host.

192
 CHAPTER 5. SERVICES

Table 5.295. Methods summary

Name Summary

list

5.93.1. list GET

Table 5.296. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of NICs to return.

nics HostNic[] Out

5.93.1.1. max

Sets the maximum number of NICs to return. If not specified all the NICs are returned.

5.94. HOSTNUMANODE

Table 5.297. Methods summary

Name Summary

get

5.94.1. get GET

Table 5.298. Parameters summary

Name Type Direction Summary

node NumaNode Out

193
Red Hat Virtualization 4.0 REST API Guide

5.95. HOSTNUMANODES

Table 5.299. Methods summary

Name Summary

list

5.95.1. list GET

Table 5.300. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of nodes to return.

nodes NumaNode[] Out

5.95.1.1. max

Sets the maximum number of nodes to return. If not specified all the nodes are returned.

5.96. HOSTSTORAGE
A service to manage host storages.

Table 5.301. Methods summary

Name Summary

list Get list of storages.

5.96.1. list GET

Get list of storages.

GET /ovirt-engine/api/hosts/123/storage

The XML response you get will be like this one:

194
 CHAPTER 5. SERVICES

<host_storages>
<host_storage id="123">
...
</host_storage>
...
</host_storages>

Table 5.302. Parameters summary

Name Type Direction Summary

report_s Boolean In Indicates if the status of the LUNs in the storage

tatus should be checked.

storages HostStorage Out Retrieved list of storages.

[]

5.96.1.1. report_status

Indicates if the status of the LUNs in the storage should be checked. Checking the status of the LUN
is an heavy weight operation and this data is not always needed by the user. This parameter will
give the option to not perform the status check of the LUNs.

The default is true for backward compatibility.

Here an example with the LUN status :

<host_storage id="123">
<logical_units>
<logical_unit id="123">
<lun_mapping>0</lun_mapping>
<paths>1</paths>
<product_id>lun0</product_id>
<serial>123</serial>
<size>10737418240</size>
<status>used</status>
<vendor_id>LIO-ORG</vendor_id>
<volume_group_id>123</volume_group_id>
</logical_unit>
</logical_units>
<type>iscsi</type>
<host id="123"/>
</host_storage>

Here an example without the LUN status :

<host_storage id="123">
<logical_units>
<logical_unit id="123">
<lun_mapping>0</lun_mapping>

195
Red Hat Virtualization 4.0 REST API Guide

<paths>1</paths>
<product_id>lun0</product_id>
<serial>123</serial>
<size>10737418240</size>
<vendor_id>LIO-ORG</vendor_id>
<volume_group_id>123</volume_group_id>
</logical_unit>
</logical_units>
<type>iscsi</type>
<host id="123"/>
</host_storage>

5.97. HOSTS

A service that manages hosts.

Table 5.303. Methods summary

Name Summary

add Creates a new host.

list Get a list of all available hosts.

5.97.1. add POST

Creates a new host.

The host is created based on the attributes of the host parameter. The name, address and
root_password properties are required.

For example, to add a host send the following request:

POST /ovirt-engine/api/hosts

With the following request body:

<host>
<name>myhost</name>
<address>myhost.example.com</address>
<root_password>myrootpassword</root_password>
</host>

Note

The root_password element is only included in the client-provided initial representation

and is not exposed in the representations returned from subsequent requests.

196
 CHAPTER 5. SERVICES

To add a hosted engine host, use the optional deploy_hosted_engine parameter:

POST /ovirt-engine/api/hosts?deploy_hosted_engine=true

Table 5.304. Parameters summary

Name Type Direction Summary

deploy_h Boolean In When set to true it means this host should deploy
osted_en also hosted engine components.
gine

host Host In/Out The host definition from which to create the new
host is passed as parameter, and the newly
created host is returned.

undeploy Boolean In When set to true it means this host should un-
_hosted_ deploy hosted engine components and this host
engine will not function as part of the High Availability
cluster.

5.97.1.1. deploy_hosted_engine

When set to true it means this host should deploy also hosted engine components. Missing value
is treated as true i.e deploy. Omitting this parameter means false and will perform no operation in
hosted engine area.

5.97.1.2. undeploy_hosted_engine

When set to true it means this host should un-deploy hosted engine components and this host will
not function as part of the High Availability cluster. Missing value is treated as true i.e un-deploy.
Omitting this parameter means false and will perform no operation in hosted engine area.

5.97.2. list GET

Get a list of all available hosts.

For example, to list the hosts send the following request:

GET /ovirt-engine/api/hosts

The response body will be something like this:

<hosts>
<host href="/ovirt-engine/api/hosts/123" id="123">
...
</host>

197
Red Hat Virtualization 4.0 REST API Guide

<host href="/ovirt-engine/api/hosts/456" id="456">

...
</host>
...
</host>

Table 5.305. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

hosts Host[] Out

max Integer In Sets the maximum number of hosts to return.

search String In A query string used to restrict the returned hosts.

5.97.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.97.2.2. max

Sets the maximum number of hosts to return. If not specified all the hosts are returned.

5.98. ICON

A service to manage an icon (read-only).

Table 5.306. Methods summary

198
 CHAPTER 5. SERVICES

Name Summary

get Get an icon.

5.98.1. get GET

Get an icon.

GET /ovirt-engine/api/icons/123

You will get a XML response like this one:

<icon id="123">
<data>Some binary data here</data>
<media_type>image/png</media_type>
</icon>

Table 5.307. Parameters summary

Name Type Direction Summary

icon Icon Out Retrieved icon.

5.99. ICONS

A service to manage icons.

Table 5.308. Methods summary

Name Summary

list Get a list of icons.

5.99.1. list GET

Get a list of icons.

GET /ovirt-engine/api/icons

You will get a XML response which is similar to this one:

<icons>

199
Red Hat Virtualization 4.0 REST API Guide

<icon id="123">
<data>...</data>
<media_type>image/png</media_type>
</icon>
...
</icons>

Table 5.309. Parameters summary

Name Type Direction Summary

icons Icon[] Out Retrieved list of icons.

max Integer In Sets the maximum number of icons to return.

5.99.1.1. max

Sets the maximum number of icons to return. If not specified all the icons are returned.

5.100. IMAGE

Table 5.310. Methods summary

Name Summary

get

import

5.100.1. get GET

Table 5.311. Parameters summary

Name Type Direction Summary

image Image Out

5.100.2. import POST

200
 CHAPTER 5. SERVICES

Table 5.312. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the import should be performed

asynchronously.

cluster Cluster In Cluster where the image should be imported.

disk Disk In The disk which should be imported.

import_a Boolean In Specify if template should be created from the

s_templa imported disk.
te

storage_ StorageDom In Storage domain where disk should be imported.

domain ain

template Template In Name of the template, which should be created.

5.100.2.1. cluster

Cluster where the image should be imported. Has effect only in case import_as_template
parameter is set to true.

5.100.2.2. template

Name of the template, which should be created. Has effect only in case import_as_template
parameter is set to true.

5.101. IMAGETRANSFER
This service provides a mechanism to control an image transfer. The client will have to create a
transfer by using add of the Section 5.102, “ImageTransfers” service, stating the image to transfer
data to/from.

After doing that, the transfer is managed by this service.

E.g., for uploading to the disk image with id 52cb593f-837c-4633-a444-35a0a0383706, the

client can use oVirt’s Python’s SDK as follows:

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(

201
Red Hat Virtualization 4.0 REST API Guide

types.ImageTransfer(
image=types.Image(
id='52cb593f-837c-4633-a444-35a0a0383706'
)
)
)

Transfers have phases, which govern the flow of the upload/download. A client implementing such a
flow should poll/check the transfer’s phase and act accordingly. All the possible phases can be
found in ImageTransferPhase.

After adding a new transfer, its phase will be initializing. The client will have to poll on the transfer’s
phase until it changes. When the phase becomes transferring, the session is ready to start the
transfer.

For example:

transfer_service = transfers_service.image_transfer_service(transfer.id)
while transfer.phase == types.ImageTransferPhase.INITIALIZING:
time.sleep(3)
transfer = transfer_service.get()

At that stage, if the transfer’s phase is paused_system, then the session was not successfully
established. One possible reason for that is that the ovirt-imageio-daemon is not running in the host
that was selected for transfer. The transfer can be resumed by calling resume of the service that
manages it.

If the session was successfully established - the returned transfer entity will contain the proxy_url
and signed_ticket attributes, which the client needs to use in order to transfer the required data. The
client can choose whatever technique and tool for sending the HTTPS request with the image’s
data.

proxy_url is the address of a proxy server to the image, to do I/O to.

signed_ticket is the content that needs to be added to the Authentication header in the
HTTPS request, in order to perform a trusted communication.

For example, Python’s HTTPSConnection can be used in order to perform an upload, so an

upload_headers dict is set for the upcoming upload:

upload_headers = {
'Authorization' : transfer.signed_ticket,
}

Using Python’s HTTPSConnection, a new connection is established:

# Extract the URI, port, and path from the transfer's proxy_url.
url = urlparse(transfer.proxy_url)

# Create a new instance of the connection.

proxy_connection = HTTPSConnection(
url.hostname,
url.port,
context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)
)

202
 CHAPTER 5. SERVICES

The specific content range being sent must be noted in the Content-Range HTTPS header. This
can be used in order to split the transfer into several requests for a more flexible process.

For doing that, the client will have to repeatedly extend the transfer session to keep the channel
open. Otherwise, the session will terminate and the transfer will get into paused_system phase,
and HTTPS requests to the server will be rejected.

E.g., the client can iterate on chunks of the file, and send them to the proxy server while asking the
service to extend the session:

path = "/path/to/image"
MB_per_request = 32
with open(path, "rb") as disk:
size = os.path.getsize(path)
chunk_size = 1024*1024*MB_per_request
pos = 0
while (pos < size):
transfer_service.extend()
upload_headers['Content-Range'] = "bytes %d-%d/%d" % (pos, min(pos
+ chunk_size, size)-1, size)
proxy_connection.request(
'PUT',
url.path,
disk.read(chunk_size),
headers=upload_headers
)
r = proxy_connection.getresponse()
print r.status, r.reason, "Completed", "{:.0%}".format(pos/
float(size))
pos += chunk_size

When finishing the transfer, the user should call finalize. This will make the final adjustments and
verifications for finishing the transfer process.

For example:

transfer_service.finalize()

In case of an error, the transfer’s phase will be changed to finished_failure, and the disk’s status will
be changed to Illegal. Otherwise it will be changed to finished_success, and the disk will be
ready to be used. In both cases, the transfer entity will be removed shortly after.

Table 5.313. Methods summary

Name Summary

extend Extend the image transfer session.

finalize After finishing to transfer the data, finalize the transfer.

203
Red Hat Virtualization 4.0 REST API Guide

Name Summary

get Get the image transfer entity.

pause Pause the image transfer session.

resume Resume the image transfer session.

5.101.1. extend POST

Extend the image transfer session.

5.101.2. finalize POST

After finishing to transfer the data, finalize the transfer.

This will make sure that the data being transferred is valid and fits the image entity that was targeted
in the transfer. Specifically, will verify that if the image entity is a QCOW disk, the data uploaded is
indeed a QCOW file, and that the image doesn’t have a backing file.

5.101.3. get GET

Get the image transfer entity.

Table 5.314. Parameters summary

Name Type Direction Summary

image_tr ImageTransf Out

ansfer er

5.101.4. pause POST

Pause the image transfer session.

5.101.5. resume POST

Resume the image transfer session. The client will need to poll the transfer’s phase until it is
different than resuming. For example:

transfer_service = transfers_service.image_transfer_service(transfer.id)
transfer_service.resume()
transfer = transfer_service.get()

204
 CHAPTER 5. SERVICES

while transfer.phase == types.ImageTransferPhase.RESUMING:

time.sleep(1)
transfer = transfer_service.get()

5.102. IMAGETRANSFERS
This service manages image transfers, for performing Image I/O API in oVirt. Please refer to image
transfer for further documentation.

Table 5.315. Methods summary

Name Summary

add Add a new image transfer.

list Retrieves the list of image transfers that are currently being performed.

5.102.1. add POST

Add a new image transfer. An image needs to be specified in order to make a new transfer.

Table 5.316. Parameters summary

Name Type Direction Summary

image_tr ImageTransf In/Out

ansfer er

5.102.2. list GET

Retrieves the list of image transfers that are currently being performed.

Table 5.317. Parameters summary

Name Type Direction Summary

image_tr ImageTransf Out

ansfer er[]

205
Red Hat Virtualization 4.0 REST API Guide

5.103. IMAGES

Table 5.318. Methods summary

Name Summary

list

5.103.1. list GET

Table 5.319. Parameters summary

Name Type Direction Summary

images Image[] Out

max Integer In Sets the maximum number of images to return.

5.103.1.1. max

Sets the maximum number of images to return. If not specified all the images are returned.

5.104. INSTANCETYPE

Table 5.320. Methods summary

Name Summary

get Get a specific instance type and it’s attributes.

remove Removes a specific instance type from the system.

update Update a specific instance type and it’s attributes.

5.104.1. get GET

Get a specific instance type and it’s attributes.

206
 CHAPTER 5. SERVICES

GET /ovirt-engine/api/instancetypes/123

Table 5.321. Parameters summary

Name Type Direction Summary

instance InstanceTyp Out

_type e

5.104.2. remove DELETE

Removes a specific instance type from the system.

If a virtual machine was created using an instance type X after removal of the instance type the
virtual machine’s instance type will be set to custom.

DELETE /ovirt-engine/api/instancetypes/123

Table 5.322. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.104.3. update PUT

Update a specific instance type and it’s attributes.

All the attributes are editable after creation. If a virtual machine was created using an instance type
X and some configuration in instance type X was updated, the virtual machine’s configuration will be
updated automatically by the engine.

PUT /ovirt-engine/api/instancetypes/123

For example, to update the memory of instance type 123 to 1 GiB and set the cpu topology to 2
sockets and 1 core, send a request like this:

<instance_type>
<memory>1073741824</memory>
<cpu>
<topology>
<cores>1</cores>
<sockets>2</sockets>

207
Red Hat Virtualization 4.0 REST API Guide

<threads>1</threads>
</topology>
</cpu>
</instance_type>

Table 5.323. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

instance InstanceTyp In/Out

_type e

5.105. INSTANCETYPENIC

Table 5.324. Methods summary

Name Summary

get Gets network interface configuration of the instance type.

remove Remove the network interface from the instance type.

update Updates the network interface configuration of the instance type.

5.105.1. get GET

Gets network interface configuration of the instance type.

Table 5.325. Parameters summary

Name Type Direction Summary

nic Nic Out

208
 CHAPTER 5. SERVICES

5.105.2. remove DELETE

Remove the network interface from the instance type.

Table 5.326. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.105.3. update PUT

Updates the network interface configuration of the instance type.

Table 5.327. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

nic Nic In/Out

5.106. INSTANCETYPENICS

Table 5.328. Methods summary

Name Summary

add Add new network interface to the instance type.

list Lists all the configured network interface of the instance type.

5.106.1. add POST

Add new network interface to the instance type.

Table 5.329. Parameters summary

209
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

nic Nic In/Out

5.106.2. list GET

Lists all the configured network interface of the instance type.

Table 5.330. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of NICs to return.

nics Nic[] Out

search String In A query string used to restrict the returned

templates.

5.106.2.1. max

Sets the maximum number of NICs to return. If not specified all the NICs are returned.

5.107. INSTANCETYPEWATCHDOG

Table 5.331. Methods summary

Name Summary

get Gets watchdog configuration of the instance type.

remove Remove a watchdog from the instance type.

update Updates the watchdog configuration of the instance type.

5.107.1. get GET

210
 CHAPTER 5. SERVICES

Gets watchdog configuration of the instance type.

Table 5.332. Parameters summary

Name Type Direction Summary

watchdog Watchdog Out

5.107.2. remove DELETE

Remove a watchdog from the instance type.

Table 5.333. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.107.3. update PUT

Updates the watchdog configuration of the instance type.

Table 5.334. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

watchdog Watchdog In/Out

5.108. INSTANCETYPEWATCHDOGS

Table 5.335. Methods summary

211
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add Add new watchdog to the instance type.

list Lists all the configured watchdogs of the instance type.

5.108.1. add POST

Add new watchdog to the instance type.

Table 5.336. Parameters summary

Name Type Direction Summary

watchdog Watchdog In/Out

5.108.2. list GET

Lists all the configured watchdogs of the instance type.

Table 5.337. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of watchdogs to return.

search String In A query string used to restrict the returned

templates.

watchdog Watchdog[] Out

s

5.108.2.1. max

Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.

5.109. INSTANCETYPES

212
 CHAPTER 5. SERVICES

Table 5.338. Methods summary

Name Summary

add Creates a new instance type.

list Lists all existing instance types in the system.

5.109.1. add POST

Creates a new instance type.

This requires only a name attribute and can include all hardware configurations of the virtual
machine.

POST /ovirt-engine/api/instancetypes

With a request body like this:

<instance_type>
<name>myinstancetype</name>
</template>

Creating an instance type with all hardware configurations with a request body like this:

<instance_type>
<name>myinstancetype</name>
<console>
<enabled>true</enabled>
</console>
<cpu>
<topology>
<cores>2</cores>
<sockets>2</sockets>
<threads>1</threads>
</topology>
</cpu>
<custom_cpu_model>AMD Opteron_G2</custom_cpu_model>
<custom_emulated_machine>q35</custom_emulated_machine>
<display>
<monitors>1</monitors>
<single_qxl_pci>true</single_qxl_pci>
<smartcard_enabled>true</smartcard_enabled>
<type>spice</type>
</display>
<high_availability>
<enabled>true</enabled>
<priority>1</priority>
</high_availability>
<io>

213
Red Hat Virtualization 4.0 REST API Guide

<threads>2</threads>
</io>
<memory>4294967296</memory>
<memory_policy>
<ballooning>true</ballooning>
<guaranteed>268435456</guaranteed>
</memory_policy>
<migration>
<auto_converge>inherit</auto_converge>
<compressed>inherit</compressed>
<policy id="00000000-0000-0000-0000-000000000000"/>
</migration>
<migration_downtime>2</migration_downtime>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
</os>
<rng_device>
<rate>
<bytes>200</bytes>
<period>2</period>
</rate>
<source>urandom</source>
</rng_device>
<soundcard_enabled>true</soundcard_enabled>
<usb>
<enabled>true</enabled>
<type>native</type>
</usb>
<virtio_scsi>
<enabled>true</enabled>
</virtio_scsi>
</instance_type>

Table 5.339. Parameters summary

Name Type Direction Summary

instance InstanceTyp In/Out

_type e

5.109.2. list GET

Lists all existing instance types in the system.

Table 5.340. Parameters summary

214
 CHAPTER 5. SERVICES

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

instance InstanceTyp Out

_type e[]

max Integer In Sets the maximum number of instance types to

return.

search String In A query string used to restrict the returned

templates.

5.109.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.109.2.2. max

Sets the maximum number of instance types to return. If not specified all the instance types are
returned.

5.110. ISCSIBOND

Table 5.341. Methods summary

Name Summary

get

remove Removes of an existing iSCSI bond.

update Updates an iSCSI bond.

5.110.1. get GET

215
Red Hat Virtualization 4.0 REST API Guide

Table 5.342. Parameters summary

Name Type Direction Summary

bond IscsiBond Out

5.110.2. remove DELETE

Removes of an existing iSCSI bond.

For example, to remove the iSCSI bond 456 send a request like this:

DELETE /ovirt-engine/api/datacenters/123/iscsibonds/456

Table 5.343. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.110.3. update PUT

Updates an iSCSI bond.

Updating of an iSCSI bond can be done on the name and the description attributes only. For
example, to update the iSCSI bond 456 of data center 123, send a request like this:

PUT /ovirt-engine/api/datacenters/123/iscsibonds/1234

The request body should look like this:

<iscsi_bond>
<name>mybond</name>
<description>My iSCSI bond</description>
</iscsi_bond>

Table 5.344. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

216
 CHAPTER 5. SERVICES

Name Type Direction Summary

bond IscsiBond In/Out

5.111. ISCSIBONDS

Table 5.345. Methods summary

Name Summary

add Create a new iSCSI bond on a data center.

list

5.111.1. add POST

Create a new iSCSI bond on a data center.

For example, to create a new iSCSI bond on data center 123 using storage connections 456 and
789, send a request like this:

POST /ovirt-engine/api/datacenters/123/iscsibonds

The request body should look like this:

<iscsi_bond>
<name>mybond</name>
<storage_connections>
<storage_connection id="456"/>
<storage_connection id="789"/>
</storage_connections>
<networks>
<network id="abc"/>
</networks>
</iscsi_bond>

Table 5.346. Parameters summary

Name Type Direction Summary

bond IscsiBond In/Out

217
Red Hat Virtualization 4.0 REST API Guide

5.111.2. list GET

Table 5.347. Parameters summary

Name Type Direction Summary

bonds IscsiBond[] Out

max Integer In Sets the maximum number of bonds to return.

5.111.2.1. max

Sets the maximum number of bonds to return. If not specified all the bonds are returned.

5.112. JOB
A service to manage a job.

Table 5.348. Methods summary

Name Summary

clear Set an external job execution to be cleared by the system.

end Marks an external job execution as ended.

get Retrieves a job.

5.112.1. clear POST

Set an external job execution to be cleared by the system.

For example, to set a job with identifier 123 send the following request:

POST /ovirt-engine/api/jobs/clear

With the following request body:

<action/>

218
 CHAPTER 5. SERVICES

Table 5.349. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.112.2. end POST

Marks an external job execution as ended.

For example, to terminate a job with identifier 123 send the following request:

POST /ovirt-engine/api/jobs/end

With the following request body:

<action>
<force>true</force>
<status>finished</status>
</action>

Table 5.350. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

force Boolean In Indicates if the job should be forcibly terminated.

5.112.3. get GET

Retrieves a job.

GET /ovirt-engine/api/jobs/123

You will receive response in XML like this one:

<job href="/ovirt-engine/api/jobs/123" id="123">

<actions>
<link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
<link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
</actions>
<description>Adding Disk</description>

219
Red Hat Virtualization 4.0 REST API Guide

<link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>

<auto_cleared>true</auto_cleared>
<end_time>2016-12-12T23:07:29.758+02:00</end_time>
<external>false</external>
<last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
<start_time>2016-12-12T23:07:26.593+02:00</start_time>
<status>failed</status>
<owner href="/ovirt-engine/api/users/456" id="456"/>
</job>

Table 5.351. Parameters summary

Name Type Direction Summary

job Job Out Retrieves the representation of the job.

5.113. JOBS

A service to manage jobs.

Table 5.352. Methods summary

Name Summary

add Add an external job.

list Retrieves the representation of the jobs.

5.113.1. add POST

Add an external job.

For example, to add a job with the following request:

POST /ovirt-engine/api/jobs

With the following request body:

<job>
<description>Doing some work</description>
<auto_cleared>true</auto_cleared>
</job>

The response should look like:

220
 CHAPTER 5. SERVICES

<job href="/ovirt-engine/api/jobs/123" id="123">

<actions>
<link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
<link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
</actions>
<description>Doing some work</description>
<link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
<auto_cleared>true</auto_cleared>
<external>true</external>
<last_updated>2016-12-13T02:15:42.130+02:00</last_updated>
<start_time>2016-12-13T02:15:42.130+02:00</start_time>
<status>started</status>
<owner href="/ovirt-engine/api/users/456" id="456"/>
</job>

Table 5.353. Parameters summary

Name Type Direction Summary

job Job In/Out Job that will be added.

5.113.2. list GET

Retrieves the representation of the jobs.

GET /ovirt-engine/api/jobs

You will receive response in XML like this one:

<jobs>
<job href="/ovirt-engine/api/jobs/123" id="123">
<actions>
<link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
<link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
</actions>
<description>Adding Disk</description>
<link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
<auto_cleared>true</auto_cleared>
<end_time>2016-12-12T23:07:29.758+02:00</end_time>
<external>false</external>
<last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
<start_time>2016-12-12T23:07:26.593+02:00</start_time>
<status>failed</status>
<owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
...
</jobs>

Table 5.354. Parameters summary

221
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

jobs Job[] Out A representation of jobs.

max Integer In Sets the maximum number of jobs to return.

5.113.2.1. max

Sets the maximum number of jobs to return. If not specified all the jobs are returned.

5.114. KATELLOERRATA
A service to manage Katello errata. The information is retrieved from Katello.

Table 5.355. Methods summary

Name Summary

list Retrieves the representation of the Katello errata.

5.114.1. list GET

Retrieves the representation of the Katello errata.

GET /ovirt-engine/api/katelloerrata

You will receive response in XML like this one:

<katello_errata>
<katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for
XYZ</summary>
<packages>
<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...
</packages>
</katello_erratum>
...

222
 CHAPTER 5. SERVICES

</katello_errata>

Table 5.356. Parameters summary

Name Type Direction Summary

errata KatelloErrat Out A representation of Katello errata.

um[]

max Integer In Sets the maximum number of errata to return.

5.114.1.1. max

Sets the maximum number of errata to return. If not specified all the errata are returned.

5.115. KATELLOERRATUM
A service to manage a Katello erratum.

Table 5.357. Methods summary

Name Summary

get Retrieves a Katello erratum.

5.115.1. get GET

Retrieves a Katello erratum.

GET /ovirt-engine/api/katelloerrata/123

You will receive response in XML like this one:

<katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">

<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for
XYZ</summary>
<packages>
<package>

223
Red Hat Virtualization 4.0 REST API Guide

<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...
</packages>
</katello_erratum>

Table 5.358. Parameters summary

Name Type Direction Summary

erratum KatelloErrat Out Retrieves the representation of the Katello erratum.

um

5.116. MACPOOL

Table 5.359. Methods summary

Name Summary

get

remove Removes a MAC address pool.

update Updates a MAC address pool.

5.116.1. get GET

Table 5.360. Parameters summary

Name Type Direction Summary

pool MacPool Out

5.116.2. remove DELETE

Removes a MAC address pool.

For example, to remove the MAC address pool having id 123 send a request like this:

224
 CHAPTER 5. SERVICES

DELETE /ovirt-engine/api/macpools/123

Table 5.361. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.116.3. update PUT

Updates a MAC address pool.

The name, description, allow_duplicates, and ranges attributes can be updated.

For example, to update the MAC address pool of id 123 send a request like this:

PUT /ovirt-engine/api/macpools/123

With a request body like this:

<mac_pool>
<name>UpdatedMACPool</name>
<description>An updated MAC address pool</description>
<allow_duplicates>false</allow_duplicates>
<ranges>
<range>
<from>00:1A:4A:16:01:51</from>
<to>00:1A:4A:16:01:e6</to>
</range>
<range>
<from>02:1A:4A:01:00:00</from>
<to>02:1A:4A:FF:FF:FF</to>
</range>
</ranges>
</mac_pool>

Table 5.362. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

pool MacPool In/Out

225
Red Hat Virtualization 4.0 REST API Guide

5.117. MACPOOLS

Table 5.363. Methods summary

Name Summary

add Creates a new MAC address pool.

list

5.117.1. add POST

Creates a new MAC address pool.

Creation of a MAC address pool requires values for the name and ranges attributes.

For example, to create MAC address pool send a request like this:

POST /ovirt-engine/api/macpools

With a request body like this:

<mac_pool>
<name>MACPool</name>
<description>A MAC address pool</description>
<allow_duplicates>true</allow_duplicates>
<default_pool>false</default_pool>
<ranges>
<range>
<from>00:1A:4A:16:01:51</from>
<to>00:1A:4A:16:01:e6</to>
</range>
</ranges>
</mac_pool>

Table 5.364. Parameters summary

Name Type Direction Summary

pool MacPool In/Out

5.117.2. list GET

Table 5.365. Parameters summary

226
 CHAPTER 5. SERVICES

Name Type Direction Summary

max Integer In Sets the maximum number of pools to return.

pools MacPool[] Out

5.117.2.1. max

Sets the maximum number of pools to return. If not specified all the pools are returned.

5.118. MEASURABLE

5.119. MOVEABLE

Table 5.366. Methods summary

Name Summary

move

5.119.1. move POST

Table 5.367. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the move should be performed

asynchronously.

5.120. NETWORK
A service managing a network

Table 5.368. Methods summary

227
Red Hat Virtualization 4.0 REST API Guide

Name Summary

get Gets a logical network.

remove Removes a logical network, or the association of a logical network to a data center.

update Updates a logical network.

5.120.1. get GET

Gets a logical network.

For example:

GET /ovirt-engine/api/networks/123

Will respond:

<network href="/ovirt-engine/api/networks/123" id="123">

<name>ovirtmgmt</name>
<description>Default Management Network</description>
<link href="/ovirt-engine/api/networks/123/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/networks/123/vnicprofiles"
rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/123/networklabels"
rel="networklabels"/>
<mtu>0</mtu>
<stp>false</stp>
<usages>
<usage>vm</usage>
</usages>
<data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
</network>

Table 5.369. Parameters summary

Name Type Direction Summary

network Network Out

5.120.2. remove DELETE

Removes a logical network, or the association of a logical network to a data center.

228
 CHAPTER 5. SERVICES

For example, to remove the logical network 123 send a request like this:

DELETE /ovirt-engine/api/networks/123

Each network is bound exactly to one data center. So if we disassociate network with data center it
has the same result as if we would just remove that network. However it might be more specific to
say we’re removing network 456 of data center 123.

For example, to remove the association of network 456 to data center 123 send a request like this:

DELETE /ovirt-engine/api/datacenters/123/networks/456

Table 5.370. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.120.3. update PUT

Updates a logical network.

The name, description, ip, vlan, stp and display attributes can be updated.

For example, to update the description of the logical network 123 send a request like this:

PUT /ovirt-engine/api/networks/123

With a request body like this:

<network>
<description>My updated description</description>
</network>

The maximum transmission unit of a network is set using a PUT request to specify the integer value
of the mtu attribute.

For example, to set the maximum transmission unit send a request like this:

PUT /ovirt-engine/api/datacenters/123/networks/456

With a request body like this:

<network>
<mtu>1500</mtu>
</network>

Table 5.371. Parameters summary

229
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

network Network In/Out

5.121. NETWORKATTACHMENT

Table 5.372. Methods summary

Name Summary

get

remove

update

5.121.1. get GET

Table 5.373. Parameters summary

Name Type Direction Summary

attachme NetworkAtta Out

nt chment

5.121.2. remove DELETE

Table 5.374. Parameters summary

Name Type Direction Summary

230
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.121.3. update PUT

Table 5.375. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

attachme NetworkAtta In/Out

nt chment

5.122. NETWORKATTACHMENTS

Table 5.376. Methods summary

Name Summary

add

list

5.122.1. add POST

Table 5.377. Parameters summary

Name Type Direction Summary

attachme NetworkAtta In/Out

nt chment

231
Red Hat Virtualization 4.0 REST API Guide

5.122.2. list GET

Table 5.378. Parameters summary

Name Type Direction Summary

attachme NetworkAtta Out

nts chment[]

max Integer In Sets the maximum number of attachments to

return.

5.122.2.1. max

Sets the maximum number of attachments to return. If not specified all the attachments are returned.

5.123. NETWORKFILTER

Manages a network filter.

<network_filter id="00000019-0019-0019-0019-00000000026b">
<name>example-network-filter-b</name>
<version>
<major>4</major>
<minor>0</minor>
<build>-1</build>
<revision>-1</revision>
</version>
</network_filter>

Please note that version is referring to the minimal support version for the specific filter.

Table 5.379. Methods summary

Name Summary

get Retrieves a representation of the network filter.

5.123.1. get GET

Retrieves a representation of the network filter.

Table 5.380. Parameters summary

232
 CHAPTER 5. SERVICES

Name Type Direction Summary

network_ NetworkFilte Out

filter r

5.124. NETWORKFILTERS
Represents a readonly network filters sub-collection.

The network filter enables to filter packets send to/from the VM’s nic according to defined rules. For
more information please refer to NetworkFilter service documentation

Network filters are supported in different versions, starting from version 3.0.

A network filter is defined for each vnic profile.

A vnic profile is defined for a specific network.

A network can be assigned to several different clusters. In the future, each network will be defined in
cluster level.

Currently, each network is being defined at data center level. Potential network filters for each
network are determined by the network’s data center compatibility version V. V must be >= the
network filter version in order to configure this network filter for a specific network. Please note, that
if a network is assigned to cluster with a version supporting a network filter, the filter may not be
available due to the data center version being smaller then the network filter’s version.

Example of listing all of the supported network filters for a specific cluster:

GET http://localhost:8080/ovirt-
engine/api/clusters/{cluster:id}/networkfilters

Output:

<network_filters>
<network_filter id="00000019-0019-0019-0019-00000000026c">
<name>example-network-filter-a</name>
<version>
<major>4</major>
<minor>0</minor>
<build>-1</build>
<revision>-1</revision>
</version>
</network_filter>
<network_filter id="00000019-0019-0019-0019-00000000026b">
<name>example-network-filter-b</name>
<version>
<major>4</major>
<minor>0</minor>
<build>-1</build>
<revision>-1</revision>
</version>
</network_filter>
<network_filter id="00000019-0019-0019-0019-00000000026a">

233
Red Hat Virtualization 4.0 REST API Guide

<name>example-network-filter-a</name>
<version>
<major>3</major>
<minor>0</minor>
<build>-1</build>
<revision>-1</revision>
</version>
</network_filter>
</network_filters>

Table 5.381. Methods summary

Name Summary

list Retrieves the representations of the network filters.

5.124.1. list GET

Retrieves the representations of the network filters.

Table 5.382. Parameters summary

Name Type Direction Summary

filters NetworkFilte Out

r[]

5.125. NETWORKLABEL

Table 5.383. Methods summary

Name Summary

get

remove Removes a label from a logical network.

5.125.1. get GET

Table 5.384. Parameters summary

234
 CHAPTER 5. SERVICES

Name Type Direction Summary

label NetworkLab Out

el

5.125.2. remove DELETE

Removes a label from a logical network.

For example, to remove the label exemplary from a logical network having id 123 send the
following request:

DELETE /ovirt-engine/api/networks/123/labels/exemplary

Table 5.385. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.126. NETWORKLABELS

Table 5.386. Methods summary

Name Summary

add Attaches label to logical network.

list

5.126.1. add POST

Attaches label to logical network.

You can attach labels to a logical network to automate the association of that logical network with
physical host network interfaces to which the same label has been attached.

For example, to attach the label mylabel to a logical network having id 123 send a request like
this:

POST /ovirt-engine/api/networks/123/labels

235
Red Hat Virtualization 4.0 REST API Guide

With a request body like this:

<label id="mylabel"/>

Table 5.387. Parameters summary

Name Type Direction Summary

label NetworkLab In/Out

el

5.126.2. list GET

Table 5.388. Parameters summary

Name Type Direction Summary

labels NetworkLab Out

el[]

max Integer In Sets the maximum number of labels to return.

5.126.2.1. max

Sets the maximum number of labels to return. If not specified all the labels are returned.

5.127. NETWORKS

Manages logical networks.

The engine creates a default ovirtmgmt network on installation. This network acts as the
management network for access to hypervisor hosts. This network is associated with the Default
cluster and is a member of the Default data center.

Table 5.389. Methods summary

Name Summary

add Creates a new logical network, or associates an existing network with a data center.

236
 CHAPTER 5. SERVICES

Name Summary

list List logical networks.

5.127.1. add POST

Creates a new logical network, or associates an existing network with a data center.

Creation of a new network requires the name and data_center elements.

For example, to create a network named mynetwork for data center 123 send a request like this:

POST /ovirt-engine/api/networks

With a request body like this:

<network>
<name>mynetwork</name>
<data_center id="123"/>
</network>

To associate the existing network 456 with the data center 123 send a request like this:

POST /ovirt-engine/api/datacenters/123/networks

With a request body like this:

<network>
<name>ovirtmgmt</name>
</network>

Table 5.390. Parameters summary

Name Type Direction Summary

network Network In/Out

5.127.2. list GET

List logical networks.

For example:

GET /ovirt-engine/api/networks

Will respond:

237
Red Hat Virtualization 4.0 REST API Guide

<networks>
<network href="/ovirt-engine/api/networks/123" id="123">
<name>ovirtmgmt</name>
<description>Default Management Network</description>
<link href="/ovirt-engine/api/networks/123/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/networks/123/vnicprofiles"
rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/123/networklabels"
rel="networklabels"/>
<mtu>0</mtu>
<stp>false</stp>
<usages>
<usage>vm</usage>
</usages>
<data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
</network>
...
</networks>

Table 5.391. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

max Integer In Sets the maximum number of networks to return.

networks Network[] Out

search String In A query string used to restrict the returned

networks.

5.127.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.127.2.2. max

Sets the maximum number of networks to return. If not specified all the networks are returned.

5.128. OPENSTACKIMAGE

238
 CHAPTER 5. SERVICES

5.128. OPENSTACKIMAGE

Table 5.392. Methods summary

Name Summary

get

import Imports a virtual machine from a Glance image storage domain.

5.128.1. get GET

Table 5.393. Parameters summary

Name Type Direction Summary

image OpenStackI Out

mage

5.128.2. import POST

Imports a virtual machine from a Glance image storage domain.

For example, to import the image with identifier 456 from the storage domain with identifier 123
send a request like this:

POST /ovirt-engine/api/openstackimageproviders/123/images/456/import

With a request body like this:

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

Table 5.394. Parameters summary

239
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the import should be performed

asynchronously.

cluster Cluster In This parameter is mandatory in case of using

import_as_template and indicates which
cluster should be used for import glance image as
template.

disk Disk In

import_a Boolean In Indicates whether the image should be imported as

s_templa a template.
te

storage_ StorageDom In
domain ain

template Template In

5.129. OPENSTACKIMAGEPROVIDER

Table 5.395. Methods summary

Name Summary

get

importcertif
icates

remove

testconnecti
vity

240
 CHAPTER 5. SERVICES

Name Summary

update

5.129.1. get GET

Table 5.396. Parameters summary

Name Type Direction Summary

provider OpenStackI Out

mageProvid
er

5.129.2. importcertificates POST

Table 5.397. Parameters summary

Name Type Direction Summary

certific Certificate[] In
ates

5.129.3. remove DELETE

Table 5.398. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.129.4. testconnectivity POST

Table 5.399. Parameters summary

241
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the test should be performed

asynchronously.

5.129.5. update PUT

Table 5.400. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

provider OpenStackI In/Out

mageProvid
er

5.130. OPENSTACKIMAGEPROVIDERS

Table 5.401. Methods summary

Name Summary

add

list

5.130.1. add POST

Table 5.402. Parameters summary

Name Type Direction Summary

242
 CHAPTER 5. SERVICES

Name Type Direction Summary

provider OpenStackI In/Out

mageProvid
er

5.130.2. list GET

Table 5.403. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of providers to return.

provider OpenStackI Out

s mageProvid
er[]

5.130.2.1. max

Sets the maximum number of providers to return. If not specified all the providers are returned.

5.131. OPENSTACKIMAGES

Table 5.404. Methods summary

Name Summary

list Lists the images of a Glance image storage domain.

5.131.1. list GET

Lists the images of a Glance image storage domain.

Table 5.405. Parameters summary

243
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

images OpenStackI Out

mage[]

max Integer In Sets the maximum number of images to return.

5.131.1.1. max

Sets the maximum number of images to return. If not specified all the images are returned.

5.132. OPENSTACKNETWORK

Table 5.406. Methods summary

Name Summary

get

import This operation imports an external network into oVirt.

5.132.1. get GET

Table 5.407. Parameters summary

Name Type Direction Summary

network OpenStackN Out

etwork

5.132.2. import POST

This operation imports an external network into oVirt. The network will be added to the data center
specified.

Table 5.408. Parameters summary

244
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the import should be performed

asynchronously.

data_cen DataCenter In The data center into which the network is to be

ter imported.

5.132.2.1. data_center

The data center into which the network is to be imported. Data center is mandatory, and can be
specified using the id or name attributes, the rest of the attributes will be ignored.

5.133. OPENSTACKNETWORKPROVIDER

This service manages OpenStack network provider.

Table 5.409. Methods summary

Name Summary

get Returns the representation of the object managed by this service.

importcertif
icates

remove Removes the provider.

testconnecti
vity

update Updates the provider.

5.133.1. get GET

Returns the representation of the object managed by this service.

For example, to get the OpenStack network provider with identifier 1234, send a request like this:

GET /ovirt-engine/api/openstacknetworkproviders/1234

245
Red Hat Virtualization 4.0 REST API Guide

Table 5.410. Parameters summary

Name Type Direction Summary

provider OpenStackN Out

etworkProvi
der

5.133.2. importcertificates POST

Table 5.411. Parameters summary

Name Type Direction Summary

certific Certificate[] In
ates

5.133.3. remove DELETE

Removes the provider.

For example, to remove the OpenStack network provider with identifier 1234, send a request like
this:

DELETE /ovirt-engine/api/openstacknetworkproviders/1234

Table 5.412. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.133.4. testconnectivity POST

Table 5.413. Parameters summary

246
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the test should be performed

asynchronously.

5.133.5. update PUT

Updates the provider.

For example, to update provider_name, requires_authentication, url, tenant_name and

type properties, for the OpenStack network provider with identifier 1234, send a request like this:

PUT /ovirt-engine/api/openstacknetworkproviders/1234

With a request body like this:

<openstack_network_provider>
<name>ovn-network-provider</name>
<requires_authentication>false</requires_authentication>
<url>http://some_server_url.domain.com:9696</url>
<tenant_name>oVirt</tenant_name>
<type>external</type>
</openstack_network_provider>

Table 5.414. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

provider OpenStackN In/Out The provider to update.

etworkProvi
der

5.134. OPENSTACKNETWORKPROVIDERS
This service manages OpenStack network providers.

Table 5.415. Methods summary

247
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add The operation adds a new network provider to the system.

list

5.134.1. add POST

The operation adds a new network provider to the system. If the type property is not present, a
default value of NEUTRON will be used.

Table 5.416. Parameters summary

Name Type Direction Summary

provider OpenStackN In/Out

etworkProvi
der

5.134.2. list GET

Table 5.417. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of providers to return.

provider OpenStackN Out

s etworkProvi
der[]

5.134.2.1. max

Sets the maximum number of providers to return. If not specified all the providers are returned.

5.135. OPENSTACKNETWORKS

Table 5.418. Methods summary

248
 CHAPTER 5. SERVICES

Name Summary

list

5.135.1. list GET

Table 5.419. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of networks to return.

networks OpenStackN Out

etwork[]

5.135.1.1. max

Sets the maximum number of networks to return. If not specified all the networks are returned.

5.136. OPENSTACKSUBNET

Table 5.420. Methods summary

Name Summary

get

remove

5.136.1. get GET

Table 5.421. Parameters summary

Name Type Direction Summary

249
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

subnet OpenStackS Out

ubnet

5.136.2. remove DELETE

Table 5.422. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.137. OPENSTACKSUBNETS

Table 5.423. Methods summary

Name Summary

add

list

5.137.1. add POST

Table 5.424. Parameters summary

Name Type Direction Summary

subnet OpenStackS In/Out

ubnet

5.137.2. list GET

Table 5.425. Parameters summary

250
 CHAPTER 5. SERVICES

Name Type Direction Summary

max Integer In Sets the maximum number of sub-networks to

return.

subnets OpenStackS Out

ubnet[]

5.137.2.1. max

Sets the maximum number of sub-networks to return. If not specified all the sub-networks are
returned.

5.138. OPENSTACKVOLUMEAUTHENTICATIONKEY

Table 5.426. Methods summary

Name Summary

get

remove

update

5.138.1. get GET

Table 5.427. Parameters summary

Name Type Direction Summary

key OpenstackV Out

olumeAuthe
nticationKey

5.138.2. remove DELETE

Table 5.428. Parameters summary

251
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.138.3. update PUT

Table 5.429. Parameters summary

Name Type Direction Summary

key OpenstackV In/Out

olumeAuthe
nticationKey

5.139. OPENSTACKVOLUMEAUTHENTICATIONKEYS

Table 5.430. Methods summary

Name Summary

add

list

5.139.1. add POST

Table 5.431. Parameters summary

Name Type Direction Summary

key OpenstackV In/Out

olumeAuthe
nticationKey

5.139.2. list GET

252
 CHAPTER 5. SERVICES

Table 5.432. Parameters summary

Name Type Direction Summary

keys OpenstackV Out

olumeAuthe
nticationKey[
]

max Integer In Sets the maximum number of keys to return.

5.139.2.1. max

Sets the maximum number of keys to return. If not specified all the keys are returned.

5.140. OPENSTACKVOLUMEPROVIDER

Table 5.433. Methods summary

Name Summary

get

importcertif
icates

remove

testconnecti
vity

update

5.140.1. get GET

Table 5.434. Parameters summary

253
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

provider OpenStackV Out

olumeProvid
er

5.140.2. importcertificates POST

Table 5.435. Parameters summary

Name Type Direction Summary

certific Certificate[] In
ates

5.140.3. remove DELETE

Table 5.436. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.140.4. testconnectivity POST

Table 5.437. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the test should be performed

asynchronously.

5.140.5. update PUT

Table 5.438. Parameters summary

254
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

provider OpenStackV In/Out

olumeProvid
er

5.141. OPENSTACKVOLUMEPROVIDERS

Table 5.439. Methods summary

Name Summary

add Adds a new volume provider.

list Retrieves the list of volume providers.

5.141.1. add POST

Adds a new volume provider.

For example:

POST /ovirt-engine/api/openstackvolumeproviders

With a request body like this:

<openstack_volume_provider>
<name>mycinder</name>
<url>https://mycinder.example.com:8776</url>
<data_center>
<name>mydc</name>
</data_center>
<requires_authentication>true</requires_authentication>
<username>admin</username>
<password>mypassword</password>
<tenant_name>mytenant</tenant_name>
</openstack_volume_provider>

Table 5.440. Parameters summary

255
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

provider OpenStackV In/Out

olumeProvid
er

5.141.2. list GET

Retrieves the list of volume providers.

Table 5.441. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of providers to return.

provider OpenStackV Out

s olumeProvid
er[]

5.141.2.1. max

Sets the maximum number of providers to return. If not specified all the providers are returned.

5.142. OPENSTACKVOLUMETYPE

Table 5.442. Methods summary

Name Summary

get

5.142.1. get GET

Table 5.443. Parameters summary

256
 CHAPTER 5. SERVICES

Name Type Direction Summary

type OpenStackV Out

olumeType

5.143. OPENSTACKVOLUMETYPES

Table 5.444. Methods summary

Name Summary

list

5.143.1. list GET

Table 5.445. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of volume types to

return.

types OpenStackV Out

olumeType[]

5.143.1.1. max

Sets the maximum number of volume types to return. If not specified all the volume types are
returned.

5.144. OPERATINGSYSTEM

Table 5.446. Methods summary

Name Summary

get

257
Red Hat Virtualization 4.0 REST API Guide

5.144.1. get GET

Table 5.447. Parameters summary

Name Type Direction Summary

operatin OperatingSy Out

g_system stemInfo

5.145. OPERATINGSYSTEMS

Table 5.448. Methods summary

Name Summary

list

5.145.1. list GET

Table 5.449. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of networks to return.

operatin OperatingSy Out

g_system stemInfo[]

5.145.1.1. max

Sets the maximum number of networks to return. If not specified all the networks are returned.

5.146. PERMISSION

Table 5.450. Methods summary

258
 CHAPTER 5. SERVICES

Name Summary

get

remove

5.146.1. get GET

Table 5.451. Parameters summary

Name Type Direction Summary

permissi Permission Out

on

5.146.2. remove DELETE

Table 5.452. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.147. PERMIT

A service to manage a specific permit of the role.

Table 5.453. Methods summary

Name Summary

get Gets the information about the permit of the role.

remove Removes the permit from the role.

259
Red Hat Virtualization 4.0 REST API Guide

5.147.1. get GET

Gets the information about the permit of the role.

For example to retrieve the information about the permit with the id 456 of the role with the id 123
send a request like this:

GET /ovirt-engine/api/roles/123/permits/456

<permit href="/ovirt-engine/api/roles/123/permits/456" id="456">

<name>change_vm_cd</name>
<administrative>false</administrative>
<role href="/ovirt-engine/api/roles/123" id="123"/>
</permit>

Table 5.454. Parameters summary

Name Type Direction Summary

permit Permit Out The permit of the role.

5.147.2. remove DELETE

Removes the permit from the role.

For example to remove the permit with id 456 from the role with id 123 send a request like this:

DELETE /ovirt-engine/api/roles/123/permits/456

Table 5.455. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.148. PERMITS
Represents a permits sub-collection of the specific role.

Table 5.456. Methods summary

260
 CHAPTER 5. SERVICES

Name Summary

add Adds a permit to the role.

list List the permits of the role.

5.148.1. add POST

Adds a permit to the role. The permit name can be retrieved from the Section 5.33, “ClusterLevels”
service.

For example to assign a permit create_vm to the role with id 123 send a request like this:

POST /ovirt-engine/api/roles/123/permits

With a request body like this:

<permit>
<name>create_vm</name>
</permit>

Table 5.457. Parameters summary

Name Type Direction Summary

permit Permit In/Out The permit to add.

5.148.2. list GET

List the permits of the role.

For example to list the permits of the role with the id 123 send a request like this:

GET /ovirt-engine/api/roles/123/permits

<permits>
<permit href="/ovirt-engine/api/roles/123/permits/5" id="5">
<name>change_vm_cd</name>
<administrative>false</administrative>
<role href="/ovirt-engine/api/roles/123" id="123"/>
</permit>
<permit href="/ovirt-engine/api/roles/123/permits/7" id="7">
<name>connect_to_vm</name>

261
Red Hat Virtualization 4.0 REST API Guide

<administrative>false</administrative>
<role href="/ovirt-engine/api/roles/123" id="123"/>
</permit>
</permits>

Table 5.458. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of permits to return.

permits Permit[] Out List of permits.

5.148.2.1. max

Sets the maximum number of permits to return. If not specified all the permits are returned.

5.149. QOS

Table 5.459. Methods summary

Name Summary

get

remove

update

5.149.1. get GET

Table 5.460. Parameters summary

Name Type Direction Summary

qos Qos Out

262
 CHAPTER 5. SERVICES

5.149.2. remove DELETE

Table 5.461. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.149.3. update PUT

Table 5.462. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

qos Qos In/Out

5.150. QOSS

Table 5.463. Methods summary

Name Summary

add

list

5.150.1. add POST

Table 5.464. Parameters summary

263
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

qos Qos In/Out

5.150.2. list GET

Table 5.465. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of QoS descriptors to

return.

qoss Qos[] Out

5.150.2.1. max

Sets the maximum number of QoS descriptors to return. If not specified all the descriptors are
returned.

5.151. QUOTA

Table 5.466. Methods summary

Name Summary

get Retrieves a quota.

remove Delete a quota.

update Updates a quota.

5.151.1. get GET

Retrieves a quota.

An example of retrieving a quota:

264
 CHAPTER 5. SERVICES

GET /ovirt-engine/api/datacenters/123/quotas/456

<quota id="456">
<name>myquota</name>
<description>My new quota for virtual machines</description>
<cluster_hard_limit_pct>20</cluster_hard_limit_pct>
<cluster_soft_limit_pct>80</cluster_soft_limit_pct>
<storage_hard_limit_pct>20</storage_hard_limit_pct>
<storage_soft_limit_pct>80</storage_soft_limit_pct>
</quota>

Table 5.467. Parameters summary

Name Type Direction Summary

quota Quota Out

5.151.2. remove DELETE

Delete a quota.

An example of deleting a quota:

DELETE /ovirt-engine/api/datacenters/123-456/quotas/654-321
-0472718ab224 HTTP/1.1
Accept: application/xml
Content-type: application/xml

Table 5.468. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.151.3. update PUT

Updates a quota.

An example of updating a quota:

PUT /ovirt-engine/api/datacenters/123/quotas/456

<quota>
<cluster_hard_limit_pct>30</cluster_hard_limit_pct>

265
Red Hat Virtualization 4.0 REST API Guide

<cluster_soft_limit_pct>70</cluster_soft_limit_pct>
<storage_hard_limit_pct>20</storage_hard_limit_pct>
<storage_soft_limit_pct>80</storage_soft_limit_pct>
</quota>

Table 5.469. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

quota Quota In/Out

5.152. QUOTACLUSTERLIMIT

Table 5.470. Methods summary

Name Summary

get

remove

5.152.1. get GET

Table 5.471. Parameters summary

Name Type Direction Summary

limit QuotaCluste Out

rLimit

5.152.2. remove DELETE

Table 5.472. Parameters summary

266
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.153. QUOTACLUSTERLIMITS

Table 5.473. Methods summary

Name Summary

add

list

5.153.1. add POST

Table 5.474. Parameters summary

Name Type Direction Summary

limit QuotaCluste In/Out

rLimit

5.153.2. list GET

Table 5.475. Parameters summary

Name Type Direction Summary

limits QuotaCluste Out

rLimit[]

max Integer In Sets the maximum number of limits to return.

5.153.2.1. max

267
Red Hat Virtualization 4.0 REST API Guide

Sets the maximum number of limits to return. If not specified all the limits are returned.

5.154. QUOTASTORAGELIMIT

Table 5.476. Methods summary

Name Summary

get

remove

5.154.1. get GET

Table 5.477. Parameters summary

Name Type Direction Summary

limit QuotaStorag Out

eLimit

5.154.2. remove DELETE

Table 5.478. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

5.155. QUOTASTORAGELIMITS

Table 5.479. Methods summary

268
 CHAPTER 5. SERVICES

Name Summary

add

list

5.155.1. add POST

Table 5.480. Parameters summary

Name Type Direction Summary

limit QuotaStorag In/Out

eLimit

5.155.2. list GET

Table 5.481. Parameters summary

Name Type Direction Summary

limits QuotaStorag Out

eLimit[]

max Integer In Sets the maximum number of limits to return.

5.155.2.1. max

Sets the maximum number of limits to return. If not specified all the limits are returned.

5.156. QUOTAS

Table 5.482. Methods summary

269
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add Creates a new quota.

list Lists quotas of a data center

5.156.1. add POST

Creates a new quota.

An example of creating a new quota:

POST /ovirt-engine/api/datacenters/123/quotas

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

Table 5.483. Parameters summary

Name Type Direction Summary

quota Quota In/Out

5.156.2. list GET

Lists quotas of a data center

Table 5.484. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of quota descriptors to

return.

quotas Quota[] Out

5.156.2.1. max

270
 CHAPTER 5. SERVICES

Sets the maximum number of quota descriptors to return. If not specified all the descriptors are
returned.

5.157. ROLE

Table 5.485. Methods summary

Name Summary

get Get the role.

remove Removes the role.

update Updates a role.

5.157.1. get GET

Get the role.

GET /ovirt-engine/api/roles/123

You will receive XML response like this one:

<role id="123">
<name>MyRole</name>
<description>MyRole description</description>
<link href="/ovirt-engine/api/roles/123/permits" rel="permits"/>
<administrative>true</administrative>
<mutable>false</mutable>
</role>

Table 5.486. Parameters summary

Name Type Direction Summary

role Role Out Retrieved role.

5.157.2. remove DELETE

Removes the role.

To remove the role you need to know its id, then send request like this:

271
Red Hat Virtualization 4.0 REST API Guide

DELETE /ovirt-engine/api/roles/{role_id}

Table 5.487. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.157.3. update PUT

Updates a role. You are allowed to update name, description and administrative attributes
after role is created. Within this endpoint you can’t add or remove roles permits you need to use
service that manages permits of role.

For example to update role’s name, description and administrative attributes send a request
like this:

PUT /ovirt-engine/api/roles/123

With a request body like this:

<role>
<name>MyNewRoleName</name>
<description>My new description of the role</description>
<administrative>true</administrative>
</group>

Table 5.488. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

role Role In/Out Updated role.

5.158. ROLES
Provides read-only access to the global set of roles

Table 5.489. Methods summary

272
 CHAPTER 5. SERVICES

Name Summary

add Create a new role.

list List roles.

5.158.1. add POST

Create a new role. The role can be administrative or non-administrative and can have different
permits.

For example, to add the MyRole non-administrative role with permits to login and create virtual
machines send a request like this (note that you have to pass permit id):

POST /ovirt-engine/api/roles

With a request body like this:

<role>
<name>MyRole</name>
<description>My custom role to create virtual machines</description>
<administrative>false</administrative>
<permits>
<permit id="1"/>
<permit id="1300"/>
</permits>
</group>

Table 5.490. Parameters summary

Name Type Direction Summary

role Role In/Out Role that will be added.

5.158.2. list GET

List roles.

GET /ovirt-engine/api/roles

You will receive response in XML like this one:

<roles>
<role id="123">
<name>SuperUser</name>
<description>Roles management administrator</description>

273
Red Hat Virtualization 4.0 REST API Guide

<link href="/ovirt-engine/api/roles/123/permits" rel="permits"/>

<administrative>true</administrative>
<mutable>false</mutable>
</role>
...
</roles>

Table 5.491. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of roles to return.

roles Role[] Out Retrieved list of roles.

5.158.2.1. max

Sets the maximum number of roles to return. If not specified all the roles are returned.

5.159. SCHEDULINGPOLICIES

Table 5.492. Methods summary

Name Summary

add

list

5.159.1. add POST

Table 5.493. Parameters summary

Name Type Direction Summary

policy SchedulingP In/Out

olicy

274
 CHAPTER 5. SERVICES

5.159.2. list GET

Table 5.494. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of policies to return.

policies SchedulingP Out

olicy[]

5.159.2.1. max

Sets the maximum number of policies to return. If not specified all the policies are returned.

5.160. SCHEDULINGPOLICY

Table 5.495. Methods summary

Name Summary

get

remove

update

5.160.1. get GET

Table 5.496. Parameters summary

275
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

policy SchedulingP Out

olicy

5.160.2. remove DELETE

Table 5.497. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.160.3. update PUT

Table 5.498. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

policy SchedulingP In/Out

olicy

5.161. SCHEDULINGPOLICYUNIT

Table 5.499. Methods summary

Name Summary

get

276
 CHAPTER 5. SERVICES

Name Summary

remove

5.161.1. get GET

Table 5.500. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

unit SchedulingP Out

olicyUnit

5.161.2. remove DELETE

Table 5.501. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.162. SCHEDULINGPOLICYUNITS

Table 5.502. Methods summary

Name Summary

list

5.162.1. list GET

Table 5.503. Parameters summary

277
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of policy units to return.

units SchedulingP Out

olicyUnit[]

5.162.1.1. max

Sets the maximum number of policy units to return. If not specified all the policy units are returned.

5.163. SNAPSHOT

Table 5.504. Methods summary

Name Summary

get

remove

restore Restores a virtual machine snapshot.

5.163.1. get GET

Table 5.505. Parameters summary

Name Type Direction Summary

snapshot Snapshot Out

5.163.2. remove DELETE

278
 CHAPTER 5. SERVICES

Table 5.506. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.163.3. restore POST

Restores a virtual machine snapshot.

For example, to restore the snapshot with identifier 456 of virtual machine with identifier 123 send a
request like this:

POST /ovirt-engine/api/vms/123/snapshots/456/restore

With an empty action in the body:

<action/>

Table 5.507. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the restore should be performed

asynchronously.

disks Disk[] In

restore_ Boolean In
memory

5.164. SNAPSHOTCDROM

Table 5.508. Methods summary

Name Summary

get

279
Red Hat Virtualization 4.0 REST API Guide

5.164.1. get GET

Table 5.509. Parameters summary

Name Type Direction Summary

cdrom Cdrom Out

5.165. SNAPSHOTCDROMS

Table 5.510. Methods summary

Name Summary

list

5.165.1. list GET

Table 5.511. Parameters summary

Name Type Direction Summary

cdroms Cdrom[] Out

max Integer In Sets the maximum number of CDROMS to return.

5.165.1.1. max

Sets the maximum number of CDROMS to return. If not specified all the CDROMS are returned.

5.166. SNAPSHOTDISK

Table 5.512. Methods summary

280
 CHAPTER 5. SERVICES

Name Summary

get

5.166.1. get GET

Table 5.513. Parameters summary

Name Type Direction Summary

disk Disk Out

5.167. SNAPSHOTDISKS

Table 5.514. Methods summary

Name Summary

list

5.167.1. list GET

Table 5.515. Parameters summary

Name Type Direction Summary

disks Disk[] Out

max Integer In Sets the maximum number of disks to return.

5.167.1.1. max

Sets the maximum number of disks to return. If not specified all the disks are returned.

5.168. SNAPSHOTNIC

281
Red Hat Virtualization 4.0 REST API Guide

Table 5.516. Methods summary

Name Summary

get

5.168.1. get GET

Table 5.517. Parameters summary

Name Type Direction Summary

nic Nic Out

5.169. SNAPSHOTNICS

Table 5.518. Methods summary

Name Summary

list

5.169.1. list GET

Table 5.519. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of NICs to return.

nics Nic[] Out

5.169.1.1. max

Sets the maximum number of NICs to return. If not specified all the NICs are returned.

5.170. SNAPSHOTS
282
 CHAPTER 5. SERVICES

5.170. SNAPSHOTS

Table 5.520. Methods summary

Name Summary

add Creates a virtual machine snapshot.

list

5.170.1. add POST

Creates a virtual machine snapshot.

For example, to create a new snapshot for virtual machine 123 send a request like this:

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

With a request body like this:

<snapshot>
<description>My snapshot</description>
</snapshot>

Table 5.521. Parameters summary

Name Type Direction Summary

snapshot Snapshot In/Out

5.170.2. list GET

Table 5.522. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of snapshots to return.

snapshot Snapshot[] Out

s

283
Red Hat Virtualization 4.0 REST API Guide

5.170.2.1. max

Sets the maximum number of snapshots to return. If not specified all the snapshots are returned.

5.171. SSHPUBLICKEY

Table 5.523. Methods summary

Name Summary

get

remove

update

5.171.1. get GET

Table 5.524. Parameters summary

Name Type Direction Summary

key SshPublicKe Out

y

5.171.2. remove DELETE

Table 5.525. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.171.3. update PUT

Table 5.526. Parameters summary

284
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

key SshPublicKe In/Out

y

5.172. SSHPUBLICKEYS

Table 5.527. Methods summary

Name Summary

add

list

5.172.1. add POST

Table 5.528. Parameters summary

Name Type Direction Summary

key SshPublicKe In/Out

y

5.172.2. list GET

Table 5.529. Parameters summary

Name Type Direction Summary

keys SshPublicKe Out

y[]

285
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

max Integer In Sets the maximum number of keys to return.

5.172.2.1. max

Sets the maximum number of keys to return. If not specified all the keys are returned.

5.173. STATISTIC

Table 5.530. Methods summary

Name Summary

get

5.173.1. get GET

Table 5.531. Parameters summary

Name Type Direction Summary

statisti Statistic In/Out

c

5.174. STATISTICS

Table 5.532. Methods summary

Name Summary

list Retrieves a list of statistics.

5.174.1. list GET

Retrieves a list of statistics.

For example, to retrieve the statistics for virtual machine 123 send a request like this:

286
 CHAPTER 5. SERVICES

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

The result will be like this:

<statistics>
<statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456">
<name>memory.installed</name>
<description>Total memory configured</description>
<kind>gauge</kind>
<type>integer</type>
<unit>bytes</unit>
<values>
<value>
<datum>1073741824</datum>
</value>
</values>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</statistic>
...
</statistics>

Just a single part of the statistics can be retrieved by specifying its id at the end of the URI. That
means:

GET /ovirt-engine/api/vms/123/statistics/456

Outputs:

<statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456">

<name>memory.installed</name>
<description>Total memory configured</description>
<kind>gauge</kind>
<type>integer</type>
<unit>bytes</unit>
<values>
<value>
<datum>1073741824</datum>
</value>
</values>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</statistic>

Table 5.533. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of statistics to return.

287
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

statisti Statistic[] Out

cs

5.174.1.1. max

Sets the maximum number of statistics to return. If not specified all the statistics are returned.

5.175. STEP

A service to manage a step.

Table 5.534. Methods summary

Name Summary

end Marks an external step execution as ended.

get Retrieves a step.

5.175.1. end POST

Marks an external step execution as ended.

For example, to terminate a step with identifier 456 which belongs to a job with identifier 123 send
the following request:

POST /ovirt-engine/api/jobs/123/steps/456/end

With the following request body:

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

Table 5.535. Parameters summary

288
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

force Boolean In Indicates if the step should be forcibly terminated.

succeede Boolean In Indicates the resolution of the step execution.

d

5.175.2. get GET

Retrieves a step.

GET /ovirt-engine/api/jobs/123/steps/456

You will receive response in XML like this one:

<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">

<actions>
<link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
</actions>
<description>Validating</description>
<end_time>2016-12-12T23:07:26.627+02:00</end_time>
<external>false</external>
<number>0</number>
<start_time>2016-12-12T23:07:26.605+02:00</start_time>
<status>finished</status>
<type>validating</type>
<job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>

Table 5.536. Parameters summary

Name Type Direction Summary

step Step Out Retrieves the representation of the step.

5.176. STEPS

A service to manage steps.

Table 5.537. Methods summary

289
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add Add an external step to an existing job or to an existing step.

list Retrieves the representation of the steps.

5.176.1. add POST

Add an external step to an existing job or to an existing step.

For example, to add a step to job with identifier 123 send the following request:

POST /ovirt-engine/api/jobs/123/steps

With the following request body:

<step>
<description>Validating</description>
<start_time>2016-12-12T23:07:26.605+02:00</start_time>
<status>started</status>
<type>validating</type>
</step>

The response should look like:

<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">

<actions>
<link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
</actions>
<description>Validating</description>
<link href="/ovirt-engine/api/jobs/123/steps/456/statistics"
rel="statistics"/>
<external>true</external>
<number>2</number>
<start_time>2016-12-13T01:06:15.380+02:00</start_time>
<status>started</status>
<type>validating</type>
<job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>

Table 5.538. Parameters summary

Name Type Direction Summary

step Step In/Out Step that will be added.

290
 CHAPTER 5. SERVICES

5.176.2. list GET

Retrieves the representation of the steps.

GET /ovirt-engine/api/job/123/steps

You will receive response in XML like this one:

<steps>
<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
<actions>
<link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
</actions>
<description>Validating</description>
<link href="/ovirt-engine/api/jobs/123/steps/456/statistics"
rel="statistics"/>
<external>true</external>
<number>2</number>
<start_time>2016-12-13T01:06:15.380+02:00</start_time>
<status>started</status>
<type>validating</type>
<job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>
...
</steps>

Table 5.539. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of steps to return.

steps Step[] Out A representation of steps.

5.176.2.1. max

Sets the maximum number of steps to return. If not specified all the steps are returned.

5.177. STORAGE

Table 5.540. Methods summary

Name Summary

get

291
Red Hat Virtualization 4.0 REST API Guide

5.177.1. get GET

Table 5.541. Parameters summary

Name Type Direction Summary

report_s Boolean In Indicates if the status of the LUNs in the storage

tatus should be checked.

storage HostStorage Out

5.177.1.1. report_status

Indicates if the status of the LUNs in the storage should be checked. Checking the status of the LUN
is an heavy weight operation and this data is not always needed by the user. This parameter will
give the option to not perform the status check of the LUNs.

The default is true for backward compatibility.

Here an example with the LUN status :

<host_storage id="360014051136c20574f743bdbd28177fd">
<logical_units>
<logical_unit id="360014051136c20574f743bdbd28177fd">
<lun_mapping>0</lun_mapping>
<paths>1</paths>
<product_id>lun0</product_id>
<serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial>
<size>10737418240</size>
<status>used</status>
<vendor_id>LIO-ORG</vendor_id>
<volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-
MNzIBZ</volume_group_id>
</logical_unit>
</logical_units>
<type>iscsi</type>
<host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/>
</host_storage>

Here an example without the LUN status :

<host_storage id="360014051136c20574f743bdbd28177fd">
<logical_units>
<logical_unit id="360014051136c20574f743bdbd28177fd">
<lun_mapping>0</lun_mapping>
<paths>1</paths>
<product_id>lun0</product_id>
<serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial>
<size>10737418240</size>
<vendor_id>LIO-ORG</vendor_id>

292
 CHAPTER 5. SERVICES

<volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-
MNzIBZ</volume_group_id>
</logical_unit>
</logical_units>
<type>iscsi</type>
<host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/>
</host_storage>

5.178. STORAGEDOMAIN

Table 5.542. Methods summary

Name Summary

get

isattached

refreshluns This operation refreshes the LUN size.

remove Removes the storage domain.

update Updates a storage domain.

updateovfsto This operation forces the update of the OVF_STORE of this storage domain.
re

5.178.1. get GET

Table 5.543. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

storage_ StorageDom Out

domain ain

293
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

5.178.2. isattached POST

Table 5.544. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

host Host In

is_attac Boolean Out

hed

5.178.3. refreshluns POST

This operation refreshes the LUN size.

After increasing the size of the underlying LUN on the storage server, the user can refresh the LUN
size. This action forces a rescan of the provided LUNs and updates the database with the new size
if required.

For example, in order to refresh the size of two LUNs send a request like this:

POST /ovirt-engine/api/storagedomains/262b056b-aede-40f1-9666-
b883eff59d40/refreshluns

With a request body like this:

<action>
<logical_units>
<logical_unit id="1IET_00010001"/>
<logical_unit id="1IET_00010002"/>
</logical_units>
</action>

Table 5.545. Parameters summary

294
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the refresh should be performed

asynchronously.

logical_ LogicalUnit[] In The LUNs that need to be refreshed.

units

5.178.4. remove DELETE

Removes the storage domain.

Without any special parameters, the storage domain is detached from the system and removed from
the database. The storage domain can then be imported to the same or different setup, with all the
data on it. If the storage isn’t accessible the operation will fail.

If the destroy parameter is true then the operation will always succeed, even if the storage isn’t
accessible, the failure is just ignored and the storage domain is removed from the database anyway.

If the format parameter is true then the actual storage is formatted, and the metadata is removed
from the LUN or directory, so it can no longer be imported to the same or a different setup.

Table 5.546. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

destroy Boolean In Indicates if the operation should succeed, and the

storage domain removed from the database, even
if the storage isn’t accessible.

format Boolean In Indicates if the actual storage should be formatted,

removing all the metadata from the underlying LUN
or directory:

[source] ---- DELETE /ovirt-

engine/api/storagedomains/123?format=true ----

This parameter is optional, and the default value is

false.

295
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

host String In Indicates what host should be used to remove the

storage domain.

5.178.4.1. destroy

Indicates if the operation should succeed, and the storage domain removed from the database, even
if the storage isn’t accessible.

DELETE /ovirt-engine/api/storagedomains/123?destroy=true

This parameter is optional, and the default value is false.

5.178.4.2. host

Indicates what host should be used to remove the storage domain.

This parameter is mandatory, and it can contain the name or the identifier of the host. For example,
to use the host named myhost to remove the storage domain with identifier 123 send a request
like this:

DELETE /ovirt-engine/api/storagedomains/123?host=myhost

5.178.5. update PUT

Updates a storage domain.

Not all of the StorageDomain's attributes are updatable post-creation. Those that can be updated
are: name, description, comment, warning_low_space_indicator,
critical_space_action_blocker and wipe_after_delete (note that changing the
wipe_after_delete attribute will not change the wipe after delete property of disks that already
exist).

To update the name and wipe_after_delete attributes of a storage domain with an identifier
123, send a request as follows:

PUT /ovirt-engine/api/storagedomains/123

With a request body as follows:

<storage_domain>
<name>data2</name>
<wipe_after_delete>true</wipe_after_delete>
</storage_domain>

Table 5.547. Parameters summary

296
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

storage_ StorageDom In/Out

domain ain

5.178.6. updateovfstore POST

This operation forces the update of the OVF_STORE of this storage domain.

The OVF_STORE is a disk image that contains the meta-data of virtual machines and disks that
reside in the storage domain. This meta-data is used in case the domain is imported or exported to
or from a different data center or a different installation.

By default the OVF_STORE is updated periodically (set by default to 60 minutes) but users might
want to force an update after an important change, or when the they believe the OVF_STORE is
corrupt.

When initiated by the user, OVF_STORE update will be performed whether an update is needed or
not.

Table 5.548. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the OVF_STORE update should be

performed asynchronously.

5.179. STORAGEDOMAINCONTENTDISK

Table 5.549. Methods summary

Name Summary

get

5.179.1. get GET

Table 5.550. Parameters summary

297
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

disk Disk Out

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.180. STORAGEDOMAINCONTENTDISKS

Table 5.551. Methods summary

Name Summary

list

5.180.1. list GET

Table 5.552. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

disks Disk[] Out

max Integer In Sets the maximum number of disks to return.

search String In A query string used to restrict the returned disks.

5.180.1.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.180.1.2. max
298
 CHAPTER 5. SERVICES

5.180.1.2. max

Sets the maximum number of disks to return. If not specified all the disks are returned.

5.181. STORAGEDOMAINSERVERCONNECTION

Table 5.553. Methods summary

Name Summary

get

remove Detaches a storage connection from storage.

5.181.1. get GET

Table 5.554. Parameters summary

Name Type Direction Summary

connecti StorageCon Out

on nection

5.181.2. remove DELETE

Detaches a storage connection from storage.

Table 5.555. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.182. STORAGEDOMAINSERVERCONNECTIONS

Table 5.556. Methods summary

299
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add

list

5.182.1. add POST

Table 5.557. Parameters summary

Name Type Direction Summary

connecti StorageCon In/Out

on nection

5.182.2. list GET

Table 5.558. Parameters summary

Name Type Direction Summary

connecti StorageCon Out

ons nection[]

max Integer In Sets the maximum number of connections to

return.

5.182.2.1. max

Sets the maximum number of connections to return. If not specified all the connections are returned.

5.183. STORAGEDOMAINTEMPLATE

Table 5.559. Methods summary

300
 CHAPTER 5. SERVICES

Name Summary

get

import

register

remove

5.183.1. get GET

Table 5.560. Parameters summary

Name Type Direction Summary

template Template Out

5.183.2. import POST

Table 5.561. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the import should be performed

asynchronously.

clone Boolean In

cluster Cluster In

exclusiv Boolean In
e

301
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

storage_ StorageDom In
domain ain

template Template In

vm Vm In

5.183.3. register POST

Table 5.562. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the registration should be performed

asynchronously.

clone Boolean In

cluster Cluster In

exclusiv Boolean In
e

template Template In

5.183.4. remove DELETE

Table 5.563. Parameters summary

Name Type Direction Summary

302
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.184. STORAGEDOMAINTEMPLATES

Table 5.564. Methods summary

Name Summary

list

5.184.1. list GET

Table 5.565. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of templates to return.

template Template[] Out

s

5.184.1.1. max

Sets the maximum number of templates to return. If not specified all the templates are returned.

5.185. STORAGEDOMAINVM

Table 5.566. Methods summary

Name Summary

get

303
Red Hat Virtualization 4.0 REST API Guide

Name Summary

import Imports a virtual machine from an export storage domain.

register

remove Deletes a virtual machine from an export storage domain.

5.185.1. get GET

Table 5.567. Parameters summary

Name Type Direction Summary

vm Vm Out

5.185.2. import POST

Imports a virtual machine from an export storage domain.

For example, send a request like this:

POST /ovirt-engine/api/storagedomains/123/vms/456/import

With a request body like this:

<action>
<storage_domain>
<name>mydata</name>
</storage_domain>
<cluster>
<name>mycluster</name>
</cluster>
</action>

To import a virtual machine as a new entity add the clone parameter:

<action>
<storage_domain>
<name>mydata</name>
</storage_domain>
<cluster>
<name>mycluster</name>
</cluster>
<clone>true</clone>

304
 CHAPTER 5. SERVICES

<vm>
<name>myvm</name>
</vm>
</action>

Include an optional disks parameter to choose which disks to import. For example, to import the
disks of the template that have the identifiers 123 and 456 send the following request body:

<action>
<cluster>
<name>mycluster</name>
</cluster>
<vm>
<name>myvm</name>
</vm>
<disks>
<disk id="123"/>
<disk id="456"/>
</disks>
</action>

Table 5.568. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the import should be performed

asynchronously.

clone Boolean In Indicates if the identifiers of the imported virtual

machine should be regenerated.

cluster Cluster In

collapse Boolean In Indicates of the snapshots of the virtual machine

_snapsho that is imported should be collapsed, so that the
ts result will be a virtual machine without snapshots.

storage_ StorageDom In
domain ain

vm Vm In

5.185.2.1. clone

305
Red Hat Virtualization 4.0 REST API Guide

Indicates if the identifiers of the imported virtual machine should be regenerated.

By default when a virtual machine is imported the identifiers are preserved. This means that the
same virtual machine can’t be imported multiple times, as that identifiers needs to be unique. To
allow importing the same machine multiple times set this parameter to true, as the default is
false.

5.185.2.2. collapse_snapshots

Indicates of the snapshots of the virtual machine that is imported should be collapsed, so that the
result will be a virtual machine without snapshots.

This parameter is optional, and if it isn’t explicitly specified the default value is false.

5.185.3. register POST

Table 5.569. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the registration should be performed

asynchronously.

clone Boolean In

cluster Cluster In

vm Vm In

5.185.4. remove DELETE

Deletes a virtual machine from an export storage domain.

For example, to delete the virtual machine 456 from the storage domain 123, send a request like
this:

DELETE /ovirt-engine/api/storagedomains/123/vms/456

Table 5.570. Parameters summary

306
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.186. STORAGEDOMAINVMDISKATTACHMENT
Returns the details of the disks attached to a virtual machine in the export domain.

Table 5.571. Methods summary

Name Summary

get Returns the details of the attachment with all its properties and a link to the disk.

5.186.1. get GET

Returns the details of the attachment with all its properties and a link to the disk.

Table 5.572. Parameters summary

Name Type Direction Summary

attachme DiskAttachm Out The disk attachment.

nt ent

5.187. STORAGEDOMAINVMDISKATTACHMENTS

Returns the details of a disk attached to a virtual machine in the export domain.

Table 5.573. Methods summary

Name Summary

list List the disks that are attached to the virtual machine.

5.187.1. list GET

307
Red Hat Virtualization 4.0 REST API Guide

List the disks that are attached to the virtual machine.

Table 5.574. Parameters summary

Name Type Direction Summary

attachme DiskAttachm Out

nts ent[]

5.188. STORAGEDOMAINVMS

Lists the virtual machines of an export storage domain.

For example, to retrieve the virtual machines that are available in the storage domain with identifier
123 send the following request:

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

This will return the following response body:

<vms>
<vm id="456" href="/api/storagedomains/123/vms/456">
<name>vm1</name>
...
<storage_domain id="123" href="/api/storagedomains/123"/>
<actions>
<link rel="import" href="/api/storagedomains/123/vms/456/import"/>
</actions>
</vm>
</vms>

Virtual machines and templates in these collections have a similar representation to their
counterparts in the top-level Vm and Template collections, except they also contain a
StorageDomain reference and an import action.

Table 5.575. Methods summary

Name Summary

list

5.188.1. list GET

Table 5.576. Parameters summary

308
 CHAPTER 5. SERVICES

Name Type Direction Summary

max Integer In Sets the maximum number of virtual machines to

return.

vm Vm[] Out

5.188.1.1. max

Sets the maximum number of virtual machines to return. If not specified all the virtual machines are
returned.

5.189. STORAGEDOMAINS

Table 5.577. Methods summary

Name Summary

add Adds a new storage domain.

list

5.189.1. add POST

Adds a new storage domain.

Creation of a new StorageDomain requires the name, type, host and storage attributes. Identify
the host attribute with the id or name attributes. In oVirt 3.6 and later you can enable the wipe after
delete option by default on the storage domain. To configure this, specify wipe_after_delete in
the POST request. This option can be edited after the domain is created, but doing so will not
change the wipe after delete property of disks that already exist.

To add a new storage domain with specified name, type, storage.type, storage.address and
storage.path and by using a host with an id 123, send a request as follows:

POST /ovirt-engine/api/storagedomains

With a request body as follows:

<storage_domain>
<name>mydata</name>
<type>data</type>
<storage>
<type>nfs</type>

309
Red Hat Virtualization 4.0 REST API Guide

<address>mynfs.example.com</address>
<path>/exports/mydata</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>

To create a new NFS ISO storage domain send a request like this:

<storage_domain>
<name>myisos</name>
<type>iso</type>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/export/myisos</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>

To create a new iSCSI storage domain send a request like this:

<storage_domain>
<name>myiscsi</name>
<type>data</type>
<storage>
<type>iscsi</type>
<logical_units>
<logical_unit id="3600144f09dbd050000004eedbd340001"/>
<logical_unit id="3600144f09dbd050000004eedbd340002"/>
</logical_units>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>

Table 5.578. Parameters summary

Name Type Direction Summary

storage_ StorageDom In/Out

domain ain

5.189.2. list GET

Table 5.579. Parameters summary

310
 CHAPTER 5. SERVICES

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of storage domains to

return.

search String In A query string used to restrict the returned storage

domains.

storage_ StorageDom Out

domains ain[]

5.189.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.189.2.2. max

Sets the maximum number of storage domains to return. If not specified all the storage domains are
returned.

5.190. STORAGESERVERCONNECTION

Table 5.580. Methods summary

Name Summary

get

remove Removes a storage connection.

311
Red Hat Virtualization 4.0 REST API Guide

Name Summary

update Updates the storage connection.

5.190.1. get GET

Table 5.581. Parameters summary

Name Type Direction Summary

conectio StorageCon Out

n nection

5.190.2. remove DELETE

Removes a storage connection.

A storage connection can only be deleted if neither storage domain nor LUN disks reference it. The
host name or id is optional; providing it disconnects (unmounts) the connection from that host.

Table 5.582. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

host String In The name or identifier of the host from which the
connection would be unmounted (disconnected).

5.190.2.1. host

The name or identifier of the host from which the connection would be unmounted (disconnected). If
not provided, no host will be disconnected.

For example, to use the host with identifier 456 to delete the storage connection with identifier 123
send a request like this:

DELETE /ovirt-engine/api/storageconnections/123?host=456

5.190.3. update PUT

312
 CHAPTER 5. SERVICES

Updates the storage connection.

For example, to change the address of the storage server send a request like this:

PUT /ovirt-engine/api/storageconnections/123

With a request body like this:

<storage_connection>
<address>mynewnfs.example.com</address>
<host>
<name>myhost</name>
</host>
</storage_connection>

Table 5.583. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

connecti StorageCon In/Out

on nection

force Boolean In Indicates if the operation should succeed

regardless to the relevant storage domain’s status
(i.

5.190.3.1. force

Indicates if the operation should succeed regardless to the relevant storage domain’s status (i.e.
updating is also applicable when storage domain’s status is not maintenance).

This parameter is optional, and the default value is false.

5.191. STORAGESERVERCONNECTIONEXTENSION

Table 5.584. Methods summary

Name Summary

get

313
Red Hat Virtualization 4.0 REST API Guide

Name Summary

remove

update Update a storage server connection extension for the given host.

5.191.1. get GET

Table 5.585. Parameters summary

Name Type Direction Summary

extensio StorageCon Out

n nectionExte
nsion

5.191.2. remove DELETE

Table 5.586. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.191.3. update PUT

Update a storage server connection extension for the given host.

To update the storage connection 456 of host 123 send a request like this:

PUT /ovirt-engine/api/hosts/123/storageconnectionextensions/456

With a request body like this:

<storage_connection_extension>
<target>iqn.2016-01.com.example:mytarget</target>
<username>myuser</username>
<password>mypassword</password>
</storage_connection_extension>

314
 CHAPTER 5. SERVICES

Table 5.587. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

extensio StorageCon In/Out

n nectionExte
nsion

5.192. STORAGESERVERCONNECTIONEXTENSIONS

Table 5.588. Methods summary

Name Summary

add Creates a new storage server connection extension for the given host.

list

5.192.1. add POST

Creates a new storage server connection extension for the given host.

The extension lets the user define credentials for an iSCSI target for a specific host. For example to
use myuser and mypassword as the credentials when connecting to the iSCSI target from host
123 send a request like this:

POST /ovirt-engine/api/hosts/123/storageconnectionextensions

With a request body like this:

<storage_connection_extension>
<target>iqn.2016-01.com.example:mytarget</target>
<username>myuser</username>
<password>mypassword</password>
</storage_connection_extension>

Table 5.589. Parameters summary

315
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

extensio StorageCon In/Out

n nectionExte
nsion

5.192.2. list GET

Table 5.590. Parameters summary

Name Type Direction Summary

extensio StorageCon Out

ns nectionExte
nsion[]

max Integer In Sets the maximum number of extensions to return.

5.192.2.1. max

Sets the maximum number of extensions to return. If not specified all the extensions are returned.

5.193. STORAGESERVERCONNECTIONS

Table 5.591. Methods summary

Name Summary

add Creates a new storage connection.

list

5.193.1. add POST

Creates a new storage connection.

For example, to create a new storage connection for the NFS server mynfs.example.com and
NFS share /export/mydata send a request like this:

POST /ovirt-engine/api/storageconnections

316
 CHAPTER 5. SERVICES

With a request body like this:

<storage_connection>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/export/mydata</path>
<host>
<name>myhost</name>
</host>
</storage_connection>

Table 5.592. Parameters summary

Name Type Direction Summary

connecti StorageCon In/Out

on nection

5.193.2. list GET

Table 5.593. Parameters summary

Name Type Direction Summary

connecti StorageCon Out

ons nection[]

max Integer In Sets the maximum number of connections to

return.

5.193.2.1. max

Sets the maximum number of connections to return. If not specified all the connections are returned.

5.194. SYSTEM

Table 5.594. Methods summary

317
Red Hat Virtualization 4.0 REST API Guide

Name Summary

get Returns basic information describing the API, like the product name, the version
number and a summary of the number of relevant objects.

reloadconfig
urations

5.194.1. get GET

Returns basic information describing the API, like the product name, the version number and a
summary of the number of relevant objects.

GET /ovirt-engine/api

We get following response:

<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}"/>
<product_info>
<name>oVirt Engine</name>
<vendor>ovirt.org</vendor>
<version>
<build>4</build>
<full_version>4.0.4</full_version>
<major>4</major>
<minor>0</minor>
<revision>0</revision>

318
 CHAPTER 5. SERVICES

</version>
</product_info>
<special_objects>
<blank_template href="/ovirt-engine/api/templates/00000000-0000-0000-
0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
<root_tag href="/ovirt-engine/api/tags/00000000-0000-0000-0000-
000000000000" id="00000000-0000-0000-0000-000000000000"/>
</special_objects>
<summary>
<hosts>
<active>0</active>
<total>0</total>
</hosts>
<storage_domains>
<active>0</active>
<total>1</total>
</storage_domains>
<users>
<active>1</active>
<total>1</total>
</users>
<vms>
<active>0</active>
<total>0</total>
</vms>
</summary>
<time>2016-09-14T12:00:48.132+02:00</time>
</api>

The entry point provides a user with links to the collections in a virtualization environment. The rel
attribute of each collection link provides a reference point for each link.

The entry point also contains other data such as product_info, special_objects and
summary.

Table 5.595. Parameters summary

Name Type Direction Summary

api Api Out

5.194.2. reloadconfigurations POST

Table 5.596. Parameters summary

Name Type Direction Summary

319
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the reload should be performed

asynchronously.

5.195. SYSTEMPERMISSIONS
This service doesn’t add any new methods, it is just a placeholder for the annotation that specifies
the path of the resource that manages the permissions assigned to the system object.

Table 5.597. Methods summary

Name Summary

add Assign a new permission to a user or group for specific entity.

list List all the permissions of the specific entity.

5.195.1. add POST

Assign a new permission to a user or group for specific entity.

For example, to assign the UserVmManager role to the virtual machine with id 123 to the user with
id 456 send a request like this:

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

With a request body like this:

<permission>
<role>
<name>UserVmManager</name>
</role>
<user id="456"/>
</permission>

To assign the SuperUser role to the system to the user with id 456 send a request like this:

POST /ovirt-engine/api/permissions

With a request body like this:

<permission>
<role>
<name>SuperUser</name>

320
 CHAPTER 5. SERVICES

</role>
<user id="456"/>
</permission>

If you want to assign permission to the group instead of the user please replace the user element
with the group element with proper id of the group. For example to assign the UserRole role to
the cluster with id 123 to the group with id 789 send a request like this:

POST /ovirt-engine/api/clusters/123/permissions

With a request body like this:

<permission>
<role>
<name>UserRole</name>
</role>
<group id="789"/>
</permission>

Table 5.598. Parameters summary

Name Type Direction Summary

permissi Permission In/Out The permission.

on

5.195.2. list GET

List all the permissions of the specific entity.

For example to list all the permissions of the cluster with id 123 send a request like this:

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

<permissions>
<permission id="456">
<cluster id="123"/>
<role id="789"/>
<user id="451"/>
</permission>
<permission id="654">
<cluster id="123"/>
<role id="789"/>
<group id="127"/>
</permission>
</permissions>

Table 5.599. Parameters summary

321
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

permissi Permission[] Out The list of permissions.

ons

5.196. TAG
A service to manage a specific tag in the system.

Table 5.600. Methods summary

Name Summary

get Gets the information about the tag.

remove Removes the tag from the system.

update Updates the tag entity.

5.196.1. get GET

Gets the information about the tag.

For example to retrieve the information about the tag with the id 123 send a request like this:

GET /ovirt-engine/api/tags/123

<tag href="/ovirt-engine/api/tags/123" id="123">

<name>root</name>
<description>root</description>
</tag>

Table 5.601. Parameters summary

Name Type Direction Summary

tag Tag Out The tag.

5.196.2. remove DELETE

322
 CHAPTER 5. SERVICES

Removes the tag from the system.

For example to remove the tag with id 123 send a request like this:

DELETE /ovirt-engine/api/tags/123

Table 5.602. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.196.3. update PUT

Updates the tag entity.

For example to update parent tag to tag with id 456 of the tag with id 123 send a request like this:

PUT /ovirt-engine/api/tags/123

With request body like:

<tag>
<parent id="456"/>
</tag>

You may also specify a tag name instead of id. For example to update parent tag to tag with name
mytag of the tag with id 123 send a request like this:

<tag>
<parent>
<name>mytag</name>
</parent>
</tag>

Table 5.603. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

tag Tag In/Out The updated tag.

323
Red Hat Virtualization 4.0 REST API Guide

5.197. TAGS
Represents a service to manage collection of the tags in the system.

Table 5.604. Methods summary

Name Summary

add Add a new tag to the system.

list List the tags in the system.

5.197.1. add POST

Add a new tag to the system.

For example, to add new tag with name mytag to the system send a request like this:

POST /ovirt-engine/api/tags

With a request body like this:

<tag>
<name>mytag</name>
</tag>

Note

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

To create new tag with specific parent tag send a request body like this:

<tag>
<name>mytag</name>
<parent>
<name>myparenttag</name>
</parent>
</tag>

Table 5.605. Parameters summary

324
 CHAPTER 5. SERVICES

Name Type Direction Summary

tag Tag In/Out The added tag.

5.197.2. list GET

List the tags in the system.

For example to list the full hierarchy of the tags in the system send a request like this:

GET /ovirt-engine/api/tags

<tags>
<tag href="/ovirt-engine/api/tags/222" id="222">
<name>root2</name>
<description>root2</description>
<parent href="/ovirt-engine/api/tags/111" id="111"/>
</tag>
<tag href="/ovirt-engine/api/tags/333" id="333">
<name>root3</name>
<description>root3</description>
<parent href="/ovirt-engine/api/tags/222" id="222"/>
</tag>
<tag href="/ovirt-engine/api/tags/111" id="111">
<name>root</name>
<description>root</description>
</tag>
</tags>

In the previous XML output you can see the following hierarchy of the tags:

root: (id: 111)

- root2 (id: 222)
- root3 (id: 333)

Table 5.606. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of tags to return.

tags Tag[] Out List of all tags in the system.

5.197.2.1. max

Sets the maximum number of tags to return. If not specified all the tags are returned.

325
Red Hat Virtualization 4.0 REST API Guide

5.198. TEMPLATE

Manages the virtual machine template and template versions.

Table 5.607. Methods summary

Name Summary

export Exports a template to the data center export domain.

get Returns the information about this template or template version.

remove Removes a virtual machine template.

update Updates the template.

5.198.1. export POST

Exports a template to the data center export domain.

For example, the operation can be facilitated using the following request:

POST /ovirt-engine/api/templates/123/export

With a request body like this:

<action>
<storage_domain id="456"/>
<exclusive>true<exclusive/>
</action>

Table 5.608. Parameters summary

Name Type Direction Summary

exclusiv Boolean In Indicates if the existing templates with the same

e name should be overwritten.

storage_ StorageDom In Specifies the destination export storage domain.

domain ain

326
 CHAPTER 5. SERVICES

5.198.1.1. exclusive

Indicates if the existing templates with the same name should be overwritten.

The export action reports a failed action if a template of the same name exists in the destination
domain. Set this parameter to true to change this behavior and overwrite any existing template.

5.198.2. get GET

Returns the information about this template or template version.

Table 5.609. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

template Template Out The information about the template or template

version.

5.198.3. remove DELETE

Removes a virtual machine template.

DELETE /ovirt-engine/api/templates/123

Table 5.610. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.198.4. update PUT

Updates the template.

The name, description, type, memory, cpu, topology, os, high_availability, display,
stateless, usb and timezone elements can be updated after a template has been created.

For example, to update a template to so that it has 1 GiB of memory send a request like this:

PUT /ovirt-engine/api/templates/123

327
Red Hat Virtualization 4.0 REST API Guide

With the following request body:

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

The version_name name attribute is the only one that can be updated within the version
attribute used for template versions:

<template>
<version>
<version_name>mytemplate_2</version_name>
</version>
</template>

Table 5.611. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

template Template In/Out

5.199. TEMPLATECDROM
A service managing a CD-ROM device on templates.

Table 5.612. Methods summary

Name Summary

get Returns the information about this CD-ROM device.

5.199.1. get GET

Returns the information about this CD-ROM device.

For example, to get information about the CD-ROM device of template 123 send a request like:

GET /ovirt-engine/api/templates/123/cdroms/

Table 5.613. Parameters summary

328
 CHAPTER 5. SERVICES

Name Type Direction Summary

cdrom Cdrom Out The information about the CD-ROM device.

5.199.1.1. cdrom

The information about the CD-ROM device.

The information consists of cdrom attribute containing reference to the CD-ROM device, the
template, and optionally the inserted disk.

If there is a disk inserted then the file attribute will contain a reference to the ISO image:

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">

<template href="/ovirt-engine/api/templates/123" id="123"/>
<file id="mycd.iso"/>
</cdrom>

If there is no disk inserted then the file attribute won’t be reported:

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">

<template href="/ovirt-engine/api/templates/123" id="123"/>
</cdrom>

5.200. TEMPLATECDROMS
Lists the CD-ROM devices of a template.

Table 5.614. Methods summary

Name Summary

list

5.200.1. list GET

Table 5.615. Parameters summary

Name Type Direction Summary

cdroms Cdrom[] Out The list of CD-ROM devices of the template.

329
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

max Integer In Sets the maximum number of CD-ROMs to return.

5.200.1.1. max

Sets the maximum number of CD-ROMs to return. If not specified all the CD-ROMs are returned.

5.201. TEMPLATEDISK

Table 5.616. Methods summary

Name Summary

copy

export

get

remove

5.201.1. copy POST

Table 5.617. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the copy should be performed

asynchronously.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.201.2. export POST

330
 CHAPTER 5. SERVICES

Table 5.618. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the export should be performed

asynchronously.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.201.3. get GET

Table 5.619. Parameters summary

Name Type Direction Summary

disk Disk Out

5.201.4. remove DELETE

Table 5.620. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.202. TEMPLATEDISKATTACHMENT

This service manages the attachment of a disk to a template.

Table 5.621. Methods summary

Name Summary

get Returns the details of the attachment.

331
Red Hat Virtualization 4.0 REST API Guide

Name Summary

remove Removes the disk from the template.

5.202.1. get GET

Returns the details of the attachment.

Table 5.622. Parameters summary

Name Type Direction Summary

attachme DiskAttachm Out

nt ent

5.202.2. remove DELETE

Removes the disk from the template. The disk will only be removed if there are other existing copies
of the disk on other storage domains.

A storage domain has to be specified to determine which of the copies should be removed (template
disks can have copies on multiple storage domains).

DELETE /ovirt-
engine/api/templates/{template:id}/diskattachments/{attachment:id}?
storage_domain=072fbaa1-08f3-4a40-9f34-a5ca22dd1d74

Table 5.623. Parameters summary

Name Type Direction Summary

force Boolean In

storage_ String In Specifies the identifier of the storage domain the

domain image to be removed resides on.

5.203. TEMPLATEDISKATTACHMENTS

This service manages the set of disks attached to a template. Each attached disk is represented by
a DiskAttachment.

332
 CHAPTER 5. SERVICES

Table 5.624. Methods summary

Name Summary

list List the disks that are attached to the template.

5.203.1. list GET

List the disks that are attached to the template.

Table 5.625. Parameters summary

Name Type Direction Summary

attachme DiskAttachm Out

nts ent[]

5.204. TEMPLATEDISKS

Table 5.626. Methods summary

Name Summary

list

5.204.1. list GET

Table 5.627. Parameters summary

Name Type Direction Summary

disks Disk[] Out

max Integer In Sets the maximum number of disks to return.

5.204.1.1. max

333
Red Hat Virtualization 4.0 REST API Guide

Sets the maximum number of disks to return. If not specified all the disks are returned.

5.205. TEMPLATENIC

Table 5.628. Methods summary

Name Summary

get

remove

update

5.205.1. get GET

Table 5.629. Parameters summary

Name Type Direction Summary

nic Nic Out

5.205.2. remove DELETE

Table 5.630. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.205.3. update PUT

Table 5.631. Parameters summary

334
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

nic Nic In/Out

5.206. TEMPLATENICS

Table 5.632. Methods summary

Name Summary

add

list

5.206.1. add POST

Table 5.633. Parameters summary

Name Type Direction Summary

nic Nic In/Out

5.206.2. list GET

Table 5.634. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of NICs to return.

nics Nic[] Out

335
Red Hat Virtualization 4.0 REST API Guide

5.206.2.1. max

Sets the maximum number of NICs to return. If not specified all the NICs are returned.

5.207. TEMPLATEWATCHDOG

Table 5.635. Methods summary

Name Summary

get

remove

update

5.207.1. get GET

Table 5.636. Parameters summary

Name Type Direction Summary

watchdog Watchdog Out

5.207.2. remove DELETE

Table 5.637. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.207.3. update PUT

Table 5.638. Parameters summary

336
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

watchdog Watchdog In/Out

5.208. TEMPLATEWATCHDOGS

Table 5.639. Methods summary

Name Summary

add

list

5.208.1. add POST

Table 5.640. Parameters summary

Name Type Direction Summary

watchdog Watchdog In/Out

5.208.2. list GET

Table 5.641. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of watchdogs to return.

watchdog Watchdog[] Out

s

337
Red Hat Virtualization 4.0 REST API Guide

5.208.2.1. max

Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.

5.209. TEMPLATES
This service manages the virtual machine templates available in the system.

Table 5.642. Methods summary

Name Summary

add Creates a new template.

list Returns the list of virtual machine templates.

5.209.1. add POST

Creates a new template.

This requires the name and vm elements. Identify the virtual machine with the id name attributes.

POST /ovirt-engine/api/templates

With a request body like this:

<template>
<name>mytemplate</name>
<vm id="123"/>
</template>

The template can be created as a sub version of an existing template.This requires the name and vm
attributes for the new template, and the base_template and version_name attributes for the new
template version. The base_template and version_name attributes must be specified within a
version section enclosed in the template section. Identify the virtual machine with the id or
name attributes.

<template>
<name>mytemplate</name>
<vm id="123"/>
<version>
<base_template id="456"/>
<version_name>mytemplate_001</version_name>
</version>
</template>

Table 5.643. Parameters summary

338
 CHAPTER 5. SERVICES

Name Type Direction Summary

clone_pe Boolean In Specifies if the permissions of the virtual machine

rmission should be copied to the template.
s

template Template In/Out The information about the template or template

version.

5.209.1.1. clone_permissions

Specifies if the permissions of the virtual machine should be copied to the template.

If this optional parameter is provided, and its values is true then the permissions of the virtual
machine (only the direct ones, not the inherited ones) will be copied to the created template. For
example, to create a template from the myvm virtual machine copying its permissions, send a
request like this:

POST /ovirt-engine/api/templates?clone_permissions=true

With a request body like this:

<template>
<name>mytemplate<name>
<vm>
<name>myvm<name>
</vm>
</template>

5.209.2. list GET

Returns the list of virtual machine templates.

For example:

GET /ovirt-engine/api/templates

Will return the list of virtual machines and virtual machine templates.

Table 5.644. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

339
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of templates to return.

search String In A query string used to restrict the returned

templates.

template Template[] Out The list of virtual machine templates.

s

5.209.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.209.2.2. max

Sets the maximum number of templates to return. If not specified all the templates are returned.

5.210. UNMANAGEDNETWORK

Table 5.645. Methods summary

Name Summary

get

remove

5.210.1. get GET

Table 5.646. Parameters summary

340
 CHAPTER 5. SERVICES

Name Type Direction Summary

network Unmanaged Out

Network

5.210.2. remove DELETE

Table 5.647. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.211. UNMANAGEDNETWORKS

Table 5.648. Methods summary

Name Summary

list

5.211.1. list GET

Table 5.649. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of networks to return.

networks Unmanaged Out

Network[]

5.211.1.1. max

Sets the maximum number of networks to return. If not specified all the networks are returned.

341
Red Hat Virtualization 4.0 REST API Guide

5.212. USER

A service to manage a user in the system. Use this service to either get users details or remove
users. In order to add new users please use Section 5.213, “Users”.

Table 5.650. Methods summary

Name Summary

get Gets the system user information.

remove Removes the system user.

5.212.1. get GET

Gets the system user information.

Usage:

GET /ovirt-engine/api/users/1234

Will return the user information:

<user href="/ovirt-engine/api/users/1234" id="1234">

<name>admin</name>
<link href="/ovirt-engine/api/users/1234/sshpublickeys"
rel="sshpublickeys"/>
<link href="/ovirt-engine/api/users/1234/roles" rel="roles"/>
<link href="/ovirt-engine/api/users/1234/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/users/1234/tags" rel="tags"/>
<department></department>
<domain_entry_id>23456</domain_entry_id>
<email>user1@domain.com</email>
<last_name>Lastname</last_name>
<namespace>*</namespace>
<principal>user1</principal>
<user_name>user1@domain-authz</user_name>
<domain href="/ovirt-engine/api/domains/45678" id="45678">
<name>domain-authz</name>
</domain>
</user>

Table 5.651. Parameters summary

342
 CHAPTER 5. SERVICES

Name Type Direction Summary

user User Out The system user.

5.212.2. remove DELETE

Removes the system user.

Usage:

DELETE /ovirt-engine/api/users/1234

Table 5.652. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.213. USERS
A service to manage the users in the system.

Table 5.653. Methods summary

Name Summary

add Add user from a directory service.

list List all the users in the system.

5.213.1. add POST

Add user from a directory service.

For example, to add the myuser user from the myextension-authz authorization provider send a
request like this:

POST /ovirt-engine/api/users

With a request body like this:

343
Red Hat Virtualization 4.0 REST API Guide

<user>
<user_name>myuser@myextension-authz</user_name>
<domain>
<name>myextension-authz</name>
</domain>
</user>

In case you are working with Active Directory you have to pass user principal name (UPN) as
username, followed by authorization provider name. Due to bug 1147900 you need to provide also
principal parameter set to UPN of the user.

For example, to add the user with UPN myuser@mysubdomain.mydomain.com from the
myextension-authz authorization provider send a request body like this:

<user>
<principal>myuser@mysubdomain.mydomain.com</principal>
<user_name>myuser@mysubdomain.mydomain.com@myextension-
authz</user_name>
<domain>
<name>myextension-authz</name>
</domain>
</user>

Table 5.654. Parameters summary

Name Type Direction Summary

user User In/Out

5.213.2. list GET

List all the users in the system.

Usage:

GET /ovirt-engine/api/users

Will return the list of users:

<users>
<user href="/ovirt-engine/api/users/1234" id="1234">
<name>admin</name>
<link href="/ovirt-engine/api/users/1234/sshpublickeys"
rel="sshpublickeys"/>
<link href="/ovirt-engine/api/users/1234/roles" rel="roles"/>
<link href="/ovirt-engine/api/users/1234/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/users/1234/tags" rel="tags"/>
<domain_entry_id>23456</domain_entry_id>
<namespace>*</namespace>

344
 CHAPTER 5. SERVICES

<principal>user1</principal>
<user_name>user1@domain-authz</user_name>
<domain href="/ovirt-engine/api/domains/45678" id="45678">
<name>domain-authz</name>
</domain>
</user>
</users>

Table 5.655. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

max Integer In Sets the maximum number of users to return.

search String In A query string used to restrict the returned users.

users User[] Out The list of users.

5.213.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into
account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.213.2.2. max

Sets the maximum number of users to return. If not specified all the users are returned.

5.214. VIRTUALFUNCTIONALLOWEDNETWORK

Table 5.656. Methods summary

Name Summary

get

345
Red Hat Virtualization 4.0 REST API Guide

Name Summary

remove

5.214.1. get GET

Table 5.657. Parameters summary

Name Type Direction Summary

network Network Out

5.214.2. remove DELETE

Table 5.658. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.215. VIRTUALFUNCTIONALLOWEDNETWORKS

Table 5.659. Methods summary

Name Summary

add

list

5.215.1. add POST

Table 5.660. Parameters summary

346
 CHAPTER 5. SERVICES

Name Type Direction Summary

network Network In/Out

5.215.2. list GET

Table 5.661. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of networks to return.

networks Network[] Out

5.215.2.1. max

Sets the maximum number of networks to return. If not specified all the networks are returned.

5.216. VM

Table 5.662. Methods summary

Name Summary

cancelmigrat This operation stops any migration of a virtual machine to another physical host.
ion

clone

commitsnapsh
ot

detach Detaches a virtual machine from a pool.

export Export a virtual machine to an export domain.

347
Red Hat Virtualization 4.0 REST API Guide

Name Summary

freezefilesy Freeze virtual machine file systems.

stems

get Retrieves the description of the virtual machine.

logon Initiates the automatic user logon to access a virtual machine from an external
console.

maintenance

migrate This operation migrates a virtual machine to another physical host.

previewsnaps
hot

reboot This operation sends a reboot request to a virtual machine.

remove Removes the virtual machine, including the virtual disks attached to it.

reordermacad
dresses

shutdown This operation sends a shutdown request to a virtual machine.

start Starts the virtual machine.

stop This operation forces a virtual machine to power-off.

suspend This operation saves the virtual machine state to disk and stops it.

thawfilesyst Thaw virtual machine file systems.

ems

348
 CHAPTER 5. SERVICES

Name Summary

ticket Generates a time-sensitive authentication token for accessing a virtual machine’s

display.

undosnapshot

update

5.216.1. cancelmigration POST

This operation stops any migration of a virtual machine to another physical host.

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

The cancel migration action does not take any action specific parameters, so the request body
should contain an empty action:

<action/>

Table 5.663. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the migration should cancelled

asynchronously.

5.216.2. clone POST

Table 5.664. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the clone should be performed

asynchronously.

vm Vm In

5.216.3. commitsnapshot POST

349
Red Hat Virtualization 4.0 REST API Guide

5.216.3. commitsnapshot POST

Table 5.665. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the snapshots should be committed

asynchronously.

5.216.4. detach POST

Detaches a virtual machine from a pool.

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

The detach action does not take any action specific parameters, so the request body should contain
an empty action:

<action/>

Table 5.666. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the detach should be performed

asynchronously.

5.216.5. export POST

Export a virtual machine to an export domain.

For example to export virtual machine 123 to the export domain myexport, send a request like
this:

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

With a request body like this:

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

350
 CHAPTER 5. SERVICES

Table 5.667. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the export should be performed

asynchronously.

discard_ Boolean In The discard_snapshots parameter is to be

snapshot used when the virtual machine should be exported
s with all its snapshots collapsed.

exclusiv Boolean In The exclusive parameter is to be used when

e the virtual machine should be exported even if
another copy of it already exists in the export
domain (override).

storage_ StorageDom In
domain ain

5.216.6. freezefilesystems POST

Freeze virtual machine file systems.

This operation freezes a virtual machine’s file systems using the QEMU guest agent when taking a
live snapshot of a running virtual machine. Normally, this is done automatically by the manager, but
this must be executed manually with the API for virtual machines using OpenStack Volume (Cinder)
disks.

Example:

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

<action/>

Table 5.668. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the freeze should be performed

asynchronously.

5.216.7. get GET

351
Red Hat Virtualization 4.0 REST API Guide

Retrieves the description of the virtual machine.

Table 5.669. Parameters summary

Name Type Direction Summary

all_cont Boolean In Indicates if all the attributes of the virtual machine

ent should be included in the response.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

next_run Boolean In Indicates if the returned result describes the virtual

machine as it is currently running, or if describes it
with the modifications that have already been
performed but that will have effect only when it is
restarted.

vm Vm Out Description of the virtual machine.

5.216.7.1. all_content

Indicates if all the attributes of the virtual machine should be included in the response.

By default the following attributes are excluded:

console

initialization.configuration.data - The OVF document describing the virtual

machine.

rng_source

soundcard

virtio_scsi

For example, to retrieve the complete representation of the virtual machine '123' send a request like
this:

GET /ovirt-engine/api/vms/123?all_content=true

Note

The reason for not including these attributes is performance: they are seldom used and
they require additional queries to the database. So try to use the this parameter only when
it is really needed.

352
 CHAPTER 5. SERVICES

5.216.7.2. next_run

Indicates if the returned result describes the virtual machine as it is currently running, or if describes
it with the modifications that have already been performed but that will have effect only when it is
restarted. By default the values is false.

If the parameter is included in the request, but without a value, it is assumed that the value is true,
so the following request:

GET /vms/{vm:id};next_run

Is equivalent to using the value true:

GET /vms/{vm:id};next_run=true

5.216.8. logon POST

Initiates the automatic user logon to access a virtual machine from an external console.

This action requires the ovirt-guest-agent-gdm-plugin and the ovirt-guest-agent-

pam-module packages to be installed and the ovirt-guest-agent service to be running on the
virtual machine.

Users require the appropriate user permissions for the virtual machine in order to access the virtual
machine from an external console.

This is how an example request would look like:

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

Request body:

<action/>

Table 5.670. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the logon should be performed

asynchronously.

5.216.9. maintenance POST

Table 5.671. Parameters summary

353
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

maintena Boolean In
nce_enab
led

5.216.10. migrate POST

This operation migrates a virtual machine to another physical host.

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

One can specify a specific host to migrate the virtual machine to:

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

Table 5.672. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the migration should be performed

asynchronously.

cluster Cluster In Specifies the cluster the virtual machine should

migrate to.

force Boolean In Specifies the virtual machine should migrate

although it might be defined as non migratable.

host Host In Specifies a specific host the virtual machine should

migrate to.

5.216.10.1. cluster

Specifies the cluster the virtual machine should migrate to. This is an optional parameter. By default,
the virtual machine is migrated to another host within the same cluster.

354
 CHAPTER 5. SERVICES

5.216.10.2. force

Specifies the virtual machine should migrate although it might be defined as non migratable. This is
an optional parameter. By default, it is set to false.

5.216.10.3. host

Specifies a specific host the virtual machine should migrate to. This is an optional parameters. By
default, the oVirt Engine automatically selects a default host for migration within the same cluster. If
an API user requires a specific host, the user can specify the host with either an id or name
parameter.

5.216.11. previewsnapshot POST

Table 5.673. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the preview should be performed

asynchronously.

disks Disk[] In

restore_ Boolean In
memory

snapshot Snapshot In

vm Vm In

5.216.12. reboot POST

This operation sends a reboot request to a virtual machine.

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

The reboot action does not take any action specific parameters, so the request body should contain
an empty action:

<action/>

355
Red Hat Virtualization 4.0 REST API Guide

Table 5.674. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the reboot should be performed

asynchronously.

5.216.13. remove DELETE

Removes the virtual machine, including the virtual disks attached to it.

For example, to remove the virtual machine with identifier 123 send a request like this:

DELETE /ovirt-engine/api/vms/123

Table 5.675. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

detach_o Boolean In Indicates if the attached virtual disks should be

nly detached first and preserved instead of being
removed.

force Boolean In Indicates if the virtual machine should be forcibly

removed.

5.216.13.1. force

Indicates if the virtual machine should be forcibly removed.

Locked virtual machines and virtual machines with locked disk images cannot be removed without
this flag set to true.

5.216.14. reordermacaddresses POST

Table 5.676. Parameters summary

356
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.216.15. shutdown POST

This operation sends a shutdown request to a virtual machine.

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

The shutdown action does not take any action specific parameters, so the request body should
contain an empty action:

<action/>

Table 5.677. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the shutdown should be performed

asynchronously.

5.216.16. start POST

Starts the virtual machine.

If the virtual environment is complete and the virtual machine contains all necessary components to
function, it can be started.

This example starts the virtual machine:

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

With a request body:

<action/>

Table 5.678. Parameters summary

Name Type Direction Summary

357
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

pause Boolean In If set to true, start the virtual machine in paused

mode.

use_clou Boolean In If set to true, the initialization type is set to cloud-

d_init init.

use_sysp Boolean In If set to true, the initialization type is set to

rep Sysprep.

vm Vm In The definition of the virtual machine for this specific

run.

5.216.16.1. pause

If set to true, start the virtual machine in paused mode. Default is false.

5.216.16.2. use_cloud_init

If set to true, the initialization type is set to cloud-init. The default value is false. See this for
details.

5.216.16.3. use_sysprep

If set to true, the initialization type is set to Sysprep. The default value is false. See this for
details.

5.216.16.4. vm

The definition of the virtual machine for this specific run.

For example:

<action>
<vm>
<os>
<boot>

358
 CHAPTER 5. SERVICES

<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm>
</action>

This will set the boot device to the CDROM only for this specific start. After the virtual machine will
be powered off, this definition will be reverted.

5.216.17. stop POST

This operation forces a virtual machine to power-off.

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

The stop action does not take any action specific parameters, so the request body should contain an
empty action:

<action/>

Table 5.679. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.216.18. suspend POST

This operation saves the virtual machine state to disk and stops it. Start a suspended virtual
machine and restore the virtual machine state with the start action.

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

The suspend action does not take any action specific parameters, so the request body should
contain an empty action:

<action/>

Table 5.680. Parameters summary

359
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.216.19. thawfilesystems POST

Thaw virtual machine file systems.

This operation thaws a virtual machine’s file systems using the QEMU guest agent when taking a
live snapshot of a running virtual machine. Normally, this is done automatically by the manager, but
this must be executed manually with the API for virtual machines using OpenStack Volume (Cinder)
disks.

Example:

POST /api/vms/123/thawfilesystems

<action/>

Table 5.681. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.216.20. ticket POST

Generates a time-sensitive authentication token for accessing a virtual machine’s display.

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

The client-provided action optionally includes a desired ticket value and/or an expiry time in seconds.

In any case, the response specifies the actual ticket value and expiry used.

<action>
<ticket>
<value>abcd12345</value>
<expiry>120</expiry>
</ticket>
</action>

Table 5.682. Parameters summary

360
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the generation of the ticket should be

performed asynchronously.

ticket Ticket In/Out

5.216.21. undosnapshot POST

Table 5.683. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the action should be performed

asynchronously.

5.216.22. update PUT

Table 5.684. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

next_run Boolean In Indicates if the update should be applied to the

virtual machine immediately, or if it should be
applied only when the virtual machine is restarted.

vm Vm In/Out

5.216.22.1. next_run

Indicates if the update should be applied to the virtual machine immediately, or if it should be applied
only when the virtual machine is restarted. The default value is false, so by default changes are
applied immediately.

5.217. VMAPPLICATION

361
Red Hat Virtualization 4.0 REST API Guide

A service that provides information about an application installed in a virtual machine.

Table 5.685. Methods summary

Name Summary

get Returns the information about the application.

5.217.1. get GET

Returns the information about the application.

Table 5.686. Parameters summary

Name Type Direction Summary

applicat Application Out The information about the application.

ion

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.217.1.1. application

The information about the application.

The information consists of name attribute containing the name of the application (which is an
arbitrary string that may also contain additional information such as version) and vm attribute
identifying the virtual machine.

For example, a request like this:

GET /ovirt-engine/api/vms/123/applications/789

May return information like this:

<application href="/ovirt-engine/api/vms/123/applications/789" id="789">

<name>ovirt-guest-agent-common-1.0.12-3.el7</name>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</application>

5.218. VMAPPLICATIONS
A service that provides information about applications installed in a virtual machine.

362
 CHAPTER 5. SERVICES

Table 5.687. Methods summary

Name Summary

list Returns a list of applications installed in the virtual machine.

5.218.1. list GET

Returns a list of applications installed in the virtual machine.

Table 5.688. Parameters summary

Name Type Direction Summary

applicat Application[] Out A list of applications installed in the virtual machine.

ions

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of applications to

return.

5.218.1.1. applications

A list of applications installed in the virtual machine.

For example, a request like this:

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

May return a list like this:

<applications>
<application href="/ovirt-engine/api/vms/123/applications/456"
id="456">
<name>kernel-3.10.0-327.36.1.el7</name>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</application>
<application href="/ovirt-engine/api/vms/123/applications/789"
id="789">
<name>ovirt-guest-agent-common-1.0.12-3.el7</name>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</application>
</applications>

363
Red Hat Virtualization 4.0 REST API Guide

5.218.1.2. max

Sets the maximum number of applications to return. If not specified all the applications are returned.

5.219. VMCDROM
Manages a CDROM device of a virtual machine.

Changing and ejecting the disk is done using always the update method, to change the value of the
file attribute.

Table 5.689. Methods summary

Name Summary

get Returns the information about this CDROM device.

update Updates the information about this CDROM device.

5.219.1. get GET

Returns the information about this CDROM device.

The information consists of cdrom attribute containing reference to the CDROM device, the virtual
machine, and optionally the inserted disk.

If there is a disk inserted then the file attribute will contain a reference to the ISO image:

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">

<file id="mycd.iso"/>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</cdrom>

If there is no disk inserted then the file attribute won’t be reported:

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">

<vm href="/ovirt-engine/api/vms/123" id="123"/>
</cdrom>

Table 5.690. Parameters summary

364
 CHAPTER 5. SERVICES

Name Type Direction Summary

cdrom Cdrom Out The information about the CDROM device.

current Boolean In Indicates if the operation should return the

information for the currently running virtual
machine.

5.219.1.1. current

Indicates if the operation should return the information for the currently running virtual machine. This
parameter is optional, and the default value is false.

5.219.2. update PUT

Updates the information about this CDROM device.

It allows to change or eject the disk by changing the value of the file attribute. For example, to
insert or change the disk send a request like this:

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-
000000000000

The body should contain the new value for the file attribute:

<cdrom>
<file id="mycd.iso"/>
</cdrom>

The value of the id attribute, mycd.iso in this example, should correspond to a file available in an
attached ISO storage domain.

To eject the disk use a file with an empty id:

<cdrom>
<file id=""/>
</cdrom>

By default the above operations change permanently the disk that will be visible to the virtual
machine after the next boot, but they don’t have any effect on the currently running virtual machine.
If you want to change the disk that is visible to the current running virtual machine, add the
current=true parameter. For example, to eject the current disk send a request like this:

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-
000000000000?current=true

With a request body like this:

365
Red Hat Virtualization 4.0 REST API Guide

<cdrom>
<file id=""/>
</cdrom>

Important

The changes made with the current=true parameter are never persisted, so they
won’t have any effect after the virtual machine is rebooted.

Table 5.691. Parameters summary

Name Type Direction Summary

cdrom Cdrom In/Out The information about the CDROM device.

current Boolean In Indicates if the update should apply to the currently

running virtual machine, or to the virtual machine
after the next boot.

5.219.2.1. current

Indicates if the update should apply to the currently running virtual machine, or to the virtual machine
after the next boot. This parameter is optional, and the default value is false, which means that by
default the update will have effect only after the next boot.

5.220. VMCDROMS
Manages the CDROM devices of a virtual machine.

Currently virtual machines have exactly one CDROM device. No new devices can be added, and the
existing one can’t be removed, thus there are no add or remove methods. Changing and ejecting
CDROM disks is done with the update method of the service that manages the CDROM device.

Table 5.692. Methods summary

Name Summary

list Returns the list of CDROM devices of the virtual machine.

5.220.1. list GET

Returns the list of CDROM devices of the virtual machine.

366
 CHAPTER 5. SERVICES

Table 5.693. Parameters summary

Name Type Direction Summary

cdroms Cdrom[] Out The list of CDROM devices of the virtual machine.

max Integer In Sets the maximum number of CDROMs to return.

5.220.1.1. max

Sets the maximum number of CDROMs to return. If not specified all the CDROMs are returned.

5.221. VMDISK

Table 5.694. Methods summary

Name Summary

activate

deactivate

export

get

move

remove Detach the disk from the virtual machine.

update

5.221.1. activate POST

Table 5.695. Parameters summary

367
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the activation should be performed

asynchronously.

5.221.2. deactivate POST

Table 5.696. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the deactivation should be performed

asynchronously.

5.221.3. export POST

Table 5.697. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the export should be performed

asynchronously.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.221.4. get GET

Table 5.698. Parameters summary

Name Type Direction Summary

disk Disk Out

5.221.5. move POST

Table 5.699. Parameters summary

368
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the move should be performed

asynchronously.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

5.221.6. remove DELETE

Detach the disk from the virtual machine.

Note

In version 3 of the API this used to also remove the disk completely from the system, but
starting with version 4 it doesn’t. If you need to remove it completely use the remove
method of the top level disk service.

Table 5.700. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.221.7. update PUT

Table 5.701. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

disk Disk In/Out

5.222. VMDISKS

369
Red Hat Virtualization 4.0 REST API Guide

Table 5.702. Methods summary

Name Summary

add

list

5.222.1. add POST

Table 5.703. Parameters summary

Name Type Direction Summary

disk Disk In/Out

5.222.2. list GET

Table 5.704. Parameters summary

Name Type Direction Summary

disks Disk[] Out

max Integer In Sets the maximum number of disks to return.

5.222.2.1. max

Sets the maximum number of disks to return. If not specified all the disks are returned.

5.223. VMGRAPHICSCONSOLE

Table 5.705. Methods summary

370
 CHAPTER 5. SERVICES

Name Summary

get Gets the configuration of the graphics console.

proxyticket

remove

5.223.1. get GET

Gets the configuration of the graphics console.

Table 5.706. Parameters summary

Name Type Direction Summary

console GraphicsCo Out

nsole

current Boolean In Use the following query to obtain the current run-
time configuration of the graphics console.

5.223.1.1. current

Use the following query to obtain the current run-time configuration of the graphics console.

GET /ovit-engine/api/vms/{vm:id}/graphicsconsoles/{console:id}?
current=true

The default value is false.

5.223.2. proxyticket POST

Table 5.707. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the generation of the ticket should be

performed asynchronously.

371
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

proxy_ti ProxyTicket Out

cket

5.223.3. remove DELETE

Table 5.708. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.224. VMHOSTDEVICE
A service to manage individual host device attached to a virtual machine.

Table 5.709. Methods summary

Name Summary

get Retrieve information about particular host device attached to given virtual machine.

remove Remove the attachment of this host device from given virtual machine.

5.224.1. get GET

Retrieve information about particular host device attached to given virtual machine.

Example:

GET /ovirt-engine/api/vms/123/hostdevices/456

<host_device href="/ovirt-engine/api/hosts/543/devices/456" id="456">

<name>pci_0000_04_00_0</name>
<capability>pci</capability>
<iommu_group>30</iommu_group>
<placeholder>true</placeholder>
<product id="0x13ba">
<name>GM107GL [Quadro K2200]</name>

372
 CHAPTER 5. SERVICES

</product>
<vendor id="0x10de">
<name>NVIDIA Corporation</name>
</vendor>
<host href="/ovirt-engine/api/hosts/543" id="543"/>
<parent_device href="/ovirt-engine/api/hosts/543/devices/456" id="456">
<name>pci_0000_00_03_0</name>
</parent_device>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</host_device>

Table 5.710. Parameters summary

Name Type Direction Summary

device HostDevice Out Retrieved information about the host device

attached to given virtual machine.

5.224.2. remove DELETE

Remove the attachment of this host device from given virtual machine.

Note

In case this device serves as an IOMMU placeholder, it cannot be removed (remove will
result only in setting its placeholder flag to true). Note that all IOMMU placeholder
devices will be removed automatically as soon as there will be no more non-placeholder
devices (all devices from given IOMMU group are detached).

DELETE /ovirt-engine/api/vms/123/hostdevices/456

Table 5.711. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.225. VMHOSTDEVICES
A service to manage host devices attached to a virtual machine.

Table 5.712. Methods summary

373
Red Hat Virtualization 4.0 REST API Guide

Name Summary

add Attach target device to given virtual machine.

list List the host devices assigned to given virtual machine.

5.225.1. add POST

Attach target device to given virtual machine.

Example:

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

With request body of type HostDevice, for example

<host_device id="123" />

Note

A necessary precondition for a successful host device attachment is that the virtual
machine must be pinned to exactly one host. The device ID is then taken relative to this
host.

Note

Attachment of a PCI device that is part of a bigger IOMMU group will result in attachment
of the remaining devices from that IOMMU group as "placeholders". These devices are
then identified using the placeholder attribute of the HostDevice type set to true.

In case you want attach a device that already serves as an IOMMU placeholder, simply issue an
explicit Add operation for it, and its placeholder flag will be cleared, and the device will be
accessible to the virtual machine.

Table 5.713. Parameters summary

Name Type Direction Summary

device HostDevice In/Out The host device to be attached to given virtual

machine.

5.225.2. list GET

374
 CHAPTER 5. SERVICES

List the host devices assigned to given virtual machine.

Table 5.714. Parameters summary

Name Type Direction Summary

device HostDevice[] Out Retrieved list of host devices attached to given

virtual machine.

max Integer In Sets the maximum number of devices to return.

5.225.2.1. max

Sets the maximum number of devices to return. If not specified all the devices are returned.

5.226. VMNIC

Table 5.715. Methods summary

Name Summary

activate

deactivate

get

remove Removes the NIC.

update Updates the NIC.

5.226.1. activate POST

Table 5.716. Parameters summary

375
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

async Boolean In Indicates if the activation should be performed

asynchronously.

5.226.2. deactivate POST

Table 5.717. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the deactivation should be performed

asynchronously.

5.226.3. get GET

Table 5.718. Parameters summary

Name Type Direction Summary

nic Nic Out

5.226.4. remove DELETE

Removes the NIC.

For example, to remove the NIC with id 456 from the virtual machine with id 123 send a request
like this:

DELETE /ovirt-engine/api/vms/123/nics/456

376
 CHAPTER 5. SERVICES

Important

The hotplugging feature only supports virtual machine operating systems with hotplugging
operations. Example operating systems include:

Red Hat Enterprise Linux 6

Red Hat Enterprise Linux 5

Windows Server 2008 and

Windows Server 2003

Table 5.719. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.226.5. update PUT

Updates the NIC.

For example, to update the NIC having with 456 belonging to virtual the machine with id 123 send a
request like this:

PUT /ovirt-engine/api/vms/123/nics/456

With a request body like this:

<nic>
<name>mynic</name>
<interface>e1000</interface>
</nic>

Important

The hotplugging feature only supports virtual machine operating systems with hotplugging
operations. Example operating systems include:

Red Hat Enterprise Linux 6

Red Hat Enterprise Linux 5

Windows Server 2008 and

Windows Server 2003

377
Red Hat Virtualization 4.0 REST API Guide

Table 5.720. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

nic Nic In/Out

5.227. VMNICS

Table 5.721. Methods summary

Name Summary

add Adds a NIC to the virtual machine.

list

5.227.1. add POST

Adds a NIC to the virtual machine.

The following example adds a network interface named mynic using virtio and the ovirtmgmt
network to the virtual machine.

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

<nic>
<interface>virtio</interface>
<name>mynic</name>
<network>
<name>ovirtmgmt</name>
</network>
</nic>

The following example sends that request using curl:

curl \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \

378
 CHAPTER 5. SERVICES

--cacert /etc/pki/ovirt-engine/ca.pem \
--data '
<nic>
<name>mynic</name>
<network>
<name>ovirtmgmt</name>
</network>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/123/nics

Important

The hotplugging feature only supports virtual machine operating systems with hotplugging
operations. Example operating systems include:

Red Hat Enterprise Linux 6

Red Hat Enterprise Linux 5

Windows Server 2008 and

Windows Server 2003

Table 5.722. Parameters summary

Name Type Direction Summary

nic Nic In/Out

5.227.2. list GET

Table 5.723. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of NICs to return.

nics Nic[] Out

5.227.2.1. max

Sets the maximum number of NICs to return. If not specified all the NICs are returned.

379
Red Hat Virtualization 4.0 REST API Guide

5.228. VMNUMANODE

Table 5.724. Methods summary

Name Summary

get

remove Removes a virtual NUMA node.

update Updates a virtual NUMA node.

5.228.1. get GET

Table 5.725. Parameters summary

Name Type Direction Summary

node VirtualNuma Out

Node

5.228.2. remove DELETE

Removes a virtual NUMA node.

An example of removing a virtual NUMA node:

DELETE /ovirt-engine/api/vms/123/numanodes/456

Table 5.726. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.228.3. update PUT

Updates a virtual NUMA node.

380
 CHAPTER 5. SERVICES

An example of pinning a virtual NUMA node to a physical NUMA node on the host:

PUT /ovirt-engine/api/vms/123/numanodes/456

The request body should contain the following:

<vm_numa_node>
<numa_node_pins>
<numa_node_pin>
<index>0</index>
</numa_node_pin>
</numa_node_pins>
</vm_numa_node>

Table 5.727. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

node VirtualNuma In/Out

Node

5.229. VMNUMANODES

Table 5.728. Methods summary

Name Summary

add Creates a new virtual NUMA node for the virtual machine.

list Lists virtual NUMA nodes of a virtual machine.

5.229.1. add POST

Creates a new virtual NUMA node for the virtual machine.

An example of creating a NUMA node:

POST /ovirt-engine/api/vms/c7ecd2dc/numanodes
Accept: application/xml
Content-type: application/xml

381
Red Hat Virtualization 4.0 REST API Guide

The request body can contain the following:

<vm_numa_node>
<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>1024</memory>
</vm_numa_node>

Table 5.729. Parameters summary

Name Type Direction Summary

node VirtualNuma In/Out

Node

5.229.2. list GET

Lists virtual NUMA nodes of a virtual machine.

Table 5.730. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of nodes to return.

nodes VirtualNuma Out

Node[]

5.229.2.1. max

Sets the maximum number of nodes to return. If not specified all the nodes are returned.

5.230. VMPOOL
A service to manage a virtual machines pool.

Table 5.731. Methods summary

382
 CHAPTER 5. SERVICES

Name Summary

allocatevm This operation allocates a virtual machine in the virtual machine pool.

get Get the virtual machine pool.

remove Removes a virtual machine pool.

update Update the virtual machine pool.

5.230.1. allocatevm POST

This operation allocates a virtual machine in the virtual machine pool.

POST /ovirt-engine/api/vmpools/123/allocatevm

The allocate virtual machine action does not take any action specific parameters, so the request
body should contain an empty action:

<action/>

Table 5.732. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the allocation should be performed

asynchronously.

5.230.2. get GET

Get the virtual machine pool.

GET /ovirt-engine/api/vmpools/123

You will get a XML response like that one:

<vm_pool id="123">
<actions>...</actions>
<name>MyVmPool</name>
<description>MyVmPool description</description>
<link href="/ovirt-engine/api/vmpools/123/permissions"
rel="permissions"/>
<max_user_vms>1</max_user_vms>

383
Red Hat Virtualization 4.0 REST API Guide

<prestarted_vms>0</prestarted_vms>
<size>100</size>
<stateful>false</stateful>
<type>automatic</type>
<use_latest_template_version>false</use_latest_template_version>
<cluster id="123"/>
<template id="123"/>
<vm id="123">...</vm>
...
</vm_pool>

Table 5.733. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

pool VmPool Out Retrieved virtual machines pool.

5.230.3. remove DELETE

Removes a virtual machine pool.

DELETE /ovirt-engine/api/vmpools/123

Table 5.734. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.230.4. update PUT

Update the virtual machine pool.

PUT /ovirt-engine/api/vmpools/123

The name, description, size, prestarted_vms and max_user_vms attributes can be updated
after the virtual machine pool has been created.

<vmpool>
<name>VM_Pool_B</name>

384
 CHAPTER 5. SERVICES

<description>Virtual Machine Pool B</description>

<size>3</size>
<prestarted_vms>1</size>
<max_user_vms>2</size>
</vmpool>

Table 5.735. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

pool VmPool In/Out The virtual machine pool that is being updated.

5.231. VMPOOLS
Provides read-write access to virtual machines pools.

Table 5.736. Methods summary

Name Summary

add Creates a new virtual machine pool.

list Get a list of available virtual machines pools.

5.231.1. add POST

Creates a new virtual machine pool.

A new pool requires the name, cluster and template attributes. Identify the cluster and template
with the id or name nested attributes:

POST /ovirt-engine/api/vmpools

With the following body:

<vmpool>
<name>mypool</name>
<cluster id="123"/>
<template id="456"/>
</vmpool>

385
Red Hat Virtualization 4.0 REST API Guide

Table 5.737. Parameters summary

Name Type Direction Summary

pool VmPool In/Out Pool to add.

5.231.2. list GET

Get a list of available virtual machines pools.

GET /ovirt-engine/api/vmpools

You will receive the following response:

<vm_pools>
<vm_pool id="123">
...
</vm_pool>
...
</vm_pools>

Table 5.738. Parameters summary

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of pools to return.

pools VmPool[] Out Retrieved pools.

search String In A query string used to restrict the returned pools.

5.231.2.1. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into

386
 CHAPTER 5. SERVICES

account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.231.2.2. max

Sets the maximum number of pools to return. If this value is not specified, all of the pools are
returned.

5.232. VMREPORTEDDEVICE

Table 5.739. Methods summary

Name Summary

get

5.232.1. get GET

Table 5.740. Parameters summary

Name Type Direction Summary

reported ReportedDe Out

_device vice

5.233. VMREPORTEDDEVICES

Table 5.741. Methods summary

Name Summary

list

5.233.1. list GET

Table 5.742. Parameters summary

387
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

max Integer In Sets the maximum number of devices to return.

reported ReportedDe Out

_device vice[]

5.233.1.1. max

Sets the maximum number of devices to return. If not specified all the devices are returned.

5.234. VMSESSION

Table 5.743. Methods summary

Name Summary

get

5.234.1. get GET

Table 5.744. Parameters summary

Name Type Direction Summary

session Session Out

5.235. VMSESSIONS
Provides information about virtual machine user sessions.

Table 5.745. Methods summary

Name Summary

list Lists all user sessions for this virtual machine.

388
 CHAPTER 5. SERVICES

5.235.1. list GET

Lists all user sessions for this virtual machine.

For example, to retrieve the session information for virtual machine 123 send a request like this:

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

The response body will contain something like this:

<sessions>
<session href="/ovirt-engine/api/vms/123/sessions/456" id="456">
<console_user>true</console_user>
<ip>
<address>192.168.122.1</address>
</ip>
<user href="/ovirt-engine/api/users/789" id="789"/>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
</session>
...
</sessions>

Table 5.746. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of sessions to return.

sessions Session[] Out

5.235.1.1. max

Sets the maximum number of sessions to return. If not specified all the sessions are returned.

5.236. VMWATCHDOG
A service managing a watchdog on virtual machines.

Table 5.747. Methods summary

Name Summary

get Returns the information about the watchdog.

389
Red Hat Virtualization 4.0 REST API Guide

Name Summary

remove Removes the watchdog from the virtual machine.

update Updates the information about the watchdog.

5.236.1. get GET

Returns the information about the watchdog.

Table 5.748. Parameters summary

Name Type Direction Summary

watchdog Watchdog Out The information about the watchdog.

5.236.1.1. watchdog

The information about the watchdog.

The information consists of model element, action element and the reference to the virtual
machine. It may look like this:

<watchdogs>
<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-
0000-000000000000" id="00000000-0000-0000-0000-000000000000">
<vm href="/ovirt-engine/api/vms/123" id="123"/>
<action>poweroff</action>
<model>i6300esb</model>
</watchdog>
</watchdogs>

5.236.2. remove DELETE

Removes the watchdog from the virtual machine.

For example, to remove a watchdog from a virtual machine, send a request like this:

DELETE /ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-
000000000000

Table 5.749. Parameters summary

390
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.236.3. update PUT

Updates the information about the watchdog.

You can update the information using action and model elements.

For example, to update a watchdog, send a request like this:

PUT /ovirt-engine/api/vms/123/watchdogs
<watchdog>
<action>reset</action>
</watchdog>

with response body:

<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-
0000-000000000000" id="00000000-0000-0000-0000-000000000000">
<vm href="/ovirt-engine/api/vms/123" id="123"/>
<action>reset</action>
<model>i6300esb</model>
</watchdog>

Table 5.750. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

watchdog Watchdog In/Out The information about the watchdog.

5.236.3.1. watchdog

The information about the watchdog.

The request data must contain at least one of model and action elements. The response data
contains complete information about the updated watchdog.

5.237. VMWATCHDOGS
Lists the watchdogs of a virtual machine.

391
Red Hat Virtualization 4.0 REST API Guide

Table 5.751. Methods summary

Name Summary

add Adds new watchdog to the virtual machine.

list The list of watchdogs of the virtual machine.

5.237.1. add POST

Adds new watchdog to the virtual machine.

For example, to add a watchdog to a virtual machine, send a request like this:

POST /ovirt-engine/api/vms/123/watchdogs
<watchdog>
<action>poweroff</action>
<model>i6300esb</model>
</watchdog>

with response body:

<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-
0000-000000000000" id="00000000-0000-0000-0000-000000000000">
<vm href="/ovirt-engine/api/vms/123" id="123"/>
<action>poweroff</action>
<model>i6300esb</model>
</watchdog>

Table 5.752. Parameters summary

Name Type Direction Summary

watchdog Watchdog In/Out The information about the watchdog.

5.237.1.1. watchdog

The information about the watchdog.

The request data must contain model element (such as i6300esb) and action element (one of
none, reset, poweroff, dump, pause). The response data additionally contains references to the
added watchdog and to the virtual machine.

5.237.2. list GET

392
 CHAPTER 5. SERVICES

The list of watchdogs of the virtual machine.

Table 5.753. Parameters summary

Name Type Direction Summary

max Integer In Sets the maximum number of watchdogs to return.

watchdog Watchdog[] Out The information about the watchdog.

s

5.237.2.1. max

Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.

5.237.2.2. watchdogs

The information about the watchdog.

The information consists of model element, action element and the reference to the virtual
machine. It may look like this:

<watchdogs>
<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-
0000-000000000000" id="00000000-0000-0000-0000-000000000000">
<vm href="/ovirt-engine/api/vms/123" id="123"/>
<action>poweroff</action>
<model>i6300esb</model>
</watchdog>
</watchdogs>

5.238. VMS

Table 5.754. Methods summary

Name Summary

add Creates a new virtual machine.

list

5.238.1. add POST

393
Red Hat Virtualization 4.0 REST API Guide

Creates a new virtual machine.

The virtual machine can be created in different ways:

From a template. In this case the identifier or name of the template must be provided. For
example, using a plain shell script and XML:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
<name>myvm</name>
<template>
<name>Blank</name>
</template>
<cluster>
<name>mycluster</name>
</cluster>
</vm>
' \
"${url}/vms"

From a snapshot. In this case the identifier of the snapshot has to be provided. For example,
using a plain shel script and XML:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
<name>myvm</name>
<snapshots>
<snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/>
</snapshots>
<cluster>
<name>mycluster</name>

394
 CHAPTER 5. SERVICES

</cluster>
</vm>
' \
"${url}/vms"

When creating a virtual machine from a template or from a snapshot it is usually useful to explicitly
indicate in what storage domain to create the disks for the virtual machine. If the virtual machine is
created from a template then this is achieved passing a set of disk_attachment elements that
indicate the mapping:

<vm>
...
<disk_attachments>
<disk_attachment>
<disk id="8d4bd566-6c86-4592-a4a7-912dbf93c298">
<storage_domains>
<storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
</storage_domains>
</disk>
<disk_attachment>
</disk_attachments>
</vm>

When the virtual machine is created from a snapshot this set of disks is slightly different, it uses the
image_id attribute instead of id.

<vm>
...
<disk_attachments>
<disk_attachment>
<disk>
<image_id>8d4bd566-6c86-4592-a4a7-912dbf93c298</image_id>
<storage_domains>
<storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
</storage_domains>
</disk>
<disk_attachment>
</disk_attachments>
</vm>

It is possible to specify additional virtual machine parameters in the XML description, e.g. a virtual
machine of desktop type, with 2 GiB of RAM and additional description can be added sending a
request body like the following:

<vm>
<name>myvm</name>
<description>My Desktop Virtual Machine</description>
<type>desktop</type>
<memory>2147483648</memory>
...
</vm>

A bootable CDROM device can be set like this:

<vm>

395
Red Hat Virtualization 4.0 REST API Guide

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

In order to boot from CDROM, you first need to insert a disk, as described in the CDROM service.
Then booting from that CDROM can be specified using the os.boot.devices attribute:

<vm>
...
<os>
<boot>
<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm>

In all cases the name or identifier of the cluster where the virtual machine will be created is
mandatory.

Table 5.755. Parameters summary

Name Type Direction Summary

clone Boolean In Specifies if the virtual machine should be

independent of the template.

clone_pe Boolean In Specifies if the permissions of the template should

rmission be copied to the virtual machine.
s

vm Vm In/Out

5.238.1.1. clone

Specifies if the virtual machine should be independent of the template.

When a virtual machine is created from a template by default the disks of the virtual machine
depend on the disks of the template, they are using the copy on write mechanism so that only the
differences from the template take up real storage space. If this parameter is specified and the value
is true then the disks of the created virtual machine will be cloned, and independent of the
template. For example, to create an independent virtual machine, send a request like this:

POST /ovirt-engine/vms?clone=true

396
 CHAPTER 5. SERVICES

With a request body like this:

<vm>
<name>myvm<name>
<template>
<name>mytemplate<name>
</template>
<cluster>
<name>mycluster<name>
</cluster>
</vm>

Note

When this parameter is true the permissions of the template will also be copied, as when
using clone_permissions=true.

5.238.1.2. clone_permissions

Specifies if the permissions of the template should be copied to the virtual machine.

If this optional parameter is provided, and its values is true then the permissions of the template
(only the direct ones, not the inherited ones) will be copied to the created virtual machine. For
example, to create a virtual machine from the mytemplate template copying its permissions, send
a request like this:

POST /ovirt-engine/api/vms?clone_permissions=true

With a request body like this:

<vm>
<name>myvm<name>
<template>
<name>mytemplate<name>
</template>
<cluster>
<name>mycluster<name>
</cluster>
</vm>

5.238.2. list GET

Table 5.756. Parameters summary

Name Type Direction Summary

all_cont Boolean In Indicates if all the attributes of the virtual machines

ent should be included in the response.

397
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

case_sen Boolean In Indicates if the search performed using the

sitive search parameter should be performed taking
case into account.

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In The maximum number of results to return.

search String In A query string used to restrict the returned virtual

machines.

vms Vm[] Out

5.238.2.1. all_content

Indicates if all the attributes of the virtual machines should be included in the response.

By default the following attributes are excluded:

console

initialization.configuration.data - The OVF document describing the virtual

machine.

rng_source

soundcard

virtio_scsi

For example, to retrieve the complete representation of the virtual machines send a request like this:

GET /ovirt-engine/api/vms?all_content=true

Note

The reason for not including these attributes is performance: they are seldom used and
they require additional queries to the database. So try to use the this parameter only when
it is really needed.

5.238.2.2. case_sensitive

Indicates if the search performed using the search parameter should be performed taking case into

398
 CHAPTER 5. SERVICES

account. The default value is true, which means that case is taken into account. If you want to
search ignoring case set it to false.

5.239. VNICPROFILE
This service manages a vNIC profile.

Table 5.757. Methods summary

Name Summary

get Retrieves details about a vNIC profile.

remove Removes the vNIC profile.

update Updates details of a vNIC profile.

5.239.1. get GET

Retrieves details about a vNIC profile.

Table 5.758. Parameters summary

Name Type Direction Summary

profile VnicProfile Out

5.239.2. remove DELETE

Removes the vNIC profile.

Table 5.759. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

399
Red Hat Virtualization 4.0 REST API Guide

5.239.3. update PUT

Updates details of a vNIC profile.

Table 5.760. Parameters summary

Name Type Direction Summary

async Boolean In Indicates if the update should be performed

asynchronously.

profile VnicProfile In/Out The vNIC profile that is being updated.

5.240. VNICPROFILES
This service manages the collection of all vNIC profiles.

Table 5.761. Methods summary

Name Summary

add Add a vNIC profile.

list List all vNIC profiles.

5.240.1. add POST

Add a vNIC profile.

For example to add vNIC profile 123 to network 456 send a request to:

POST /ovirt-engine/api/networks/456/vnicprofiles

With the following body:

<vnic_profile id="123">
<name>new_vNIC_name</name>
<pass_through>
<mode>disabled</mode>
</pass_through>
<port_mirroring>false</port_mirroring>
</vnic_profile>

400
 CHAPTER 5. SERVICES

Please note that there is a default network filter to each VNIC profile. For more details of how the
default network filter is calculated please refer to the documentation in NetworkFilters.

The output of creating a new VNIC profile depends in the body arguments that were given. In case
no network filter was given, the default network filter will be configured. For example:

<vnic_profile href="/ovirt-engine/api/vnicprofiles/123" id="123">

<name>new_vNIC_name</name>
<link href="/ovirt-engine/api/vnicprofiles/123/permissions"
rel="permissions"/>
<pass_through>
<mode>disabled</mode>
</pass_through>
<port_mirroring>false</port_mirroring>
<network href="/ovirt-engine/api/networks/456" id="456"/>
<network_filter href="/ovirt-engine/api/networkfilters/789" id="789"/>
</vnic_profile>

In case an empty network filter was given, no network filter will be configured for the specific VNIC
profile regardless of the VNIC profile’s default network filter. For example:

<vnic_profile>
<name>no_network_filter</name>
<network_filter/>
</vnic_profile>

In case that a specific valid network filter id was given, the VNIC profile will be configured with the
given network filter regardless of the VNIC profiles’s default network filter. For example:

<vnic_profile>
<name>user_choice_network_filter</name>
<network_filter id= "0000001b-001b-001b-001b-0000000001d5"/>
</vnic_profile>

Table 5.762. Parameters summary

Name Type Direction Summary

profile VnicProfile In/Out The vNIC profile that is being added.

5.240.2. list GET

List all vNIC profiles.

Table 5.763. Parameters summary

401
Red Hat Virtualization 4.0 REST API Guide

Name Type Direction Summary

max Integer In Sets the maximum number of profiles to return.

profiles VnicProfile[] Out The list of all vNIC profiles.

5.240.2.1. max

Sets the maximum number of profiles to return. If not specified all the profiles are returned.

5.241. WEIGHT

Table 5.764. Methods summary

Name Summary

get

remove

5.241.1. get GET

Table 5.765. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

weight Weight Out

5.241.2. remove DELETE

Table 5.766. Parameters summary

402
 CHAPTER 5. SERVICES

Name Type Direction Summary

async Boolean In Indicates if the remove should be performed

asynchronously.

5.242. WEIGHTS

Table 5.767. Methods summary

Name Summary

add

list

5.242.1. add POST

Table 5.768. Parameters summary

Name Type Direction Summary

weight Weight In/Out

5.242.2. list GET

Table 5.769. Parameters summary

Name Type Direction Summary

filter Boolean In Indicates if the results should be filtered according

to the permissions of the user.

max Integer In Sets the maximum number of weights to return.

weights Weight[] Out

403
Red Hat Virtualization 4.0 REST API Guide

5.242.2.1. max

Sets the maximum number of weights to return. If not specified all the weights are returned.

404
 CHAPTER 6. TYPES

CHAPTER 6. TYPES

This section enumerates all the data types that are available in the API.

6.1. ACCESSPROTOCOL ENUM

Table 6.1. Values summary

Name Summary

cifs

gluster

nfs

6.2. ACTION STRUCT

Table 6.2. Attributes summary

Name Type Summary

async Boolean

bricks GlusterBrick[]

certificates Certificate[]

check_connec Boolean
tivity

clone Boolean

cluster Cluster

405
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

collapse_sna Boolean
pshots

comment String Free text containing comments about this object.

connectivity Integer
_timeout

data_center DataCenter

deploy_hoste Boolean
d_engine

description String A human-readable description in plain text.

details GlusterVolumePr
ofileDetails

discard_snap Boolean
shots

disk Disk

disks Disk[]

exclusive Boolean

fault Fault

fence_type String

406
 CHAPTER 6. TYPES

Name Type Summary

filter Boolean

fix_layout Boolean

force Boolean

grace_period GracePeriod

host Host

id String A unique identifier.

image String

import_as_te Boolean
mplate

is_attached Boolean

iscsi IscsiDetails

iscsi_target String[]
s

job Job

logical_unit LogicalUnit[]
s

maintenance_ Boolean
enabled

407
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

modified_bon HostNic[]
ds

modified_lab NetworkLabel[]
els

modified_net NetworkAttachme
work_attachm nt[]
ents

name String A human-readable name in plain text.

option Option

pause Boolean

power_manage PowerManageme
ment nt

proxy_ticket ProxyTicket

reason String

removed_bond HostNic[]
s

removed_labe NetworkLabel[]
ls

removed_netw NetworkAttachme
ork_attachme nt[]
nts

408
 CHAPTER 6. TYPES

Name Type Summary

resolution_t String
ype

restore_memo Boolean
ry

root_passwor String
d

snapshot Snapshot

ssh Ssh

status String

stop_gluster Boolean
_service

storage_doma StorageDomain
in

storage_doma StorageDomain[]
ins

succeeded Boolean

synchronized NetworkAttachme
_network_att nt[]
achments

template Template

ticket Ticket

409
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

undeploy_hos Boolean
ted_engine

use_cloud_in Boolean
it

use_sysprep Boolean

virtual_func HostNicVirtualFun
tions_config ctionsConfiguratio
uration n

vm Vm

6.3. AFFINITYGROUP STRUCT

An affinity group represents a group of virtual machines with a defined relationship.

Table 6.3. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

enforcing Boolean Specifies whether the affinity group uses hard or soft
enforcement of the affinity applied to virtual machines that are
members of that affinity group.

id String A unique identifier.

name String A human-readable name in plain text.

410
 CHAPTER 6. TYPES

Name Type Summary

positive Boolean Specifies whether the affinity group applies positive affinity or
negative affinity to virtual machines that are members of that
affinity group.

Table 6.4. Links summary

Name Type Summary

cluster Cluster A reference to the cluster to which the affinity group applies.

vms Vm[] A list of all virtual machines assigned to this affinity group.

6.4. AFFINITYLABEL STRUCT

The affinity label can influence virtual machine scheduling. It is most frequently used to create a
sub-cluster from the available hosts.

Table 6.5. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

read_only Boolean The read_only property marks a label that can not be
modified.

6.4.1. read_only

411
Red Hat Virtualization 4.0 REST API Guide

The read_only property marks a label that can not be modified. This is usually the case when
listing internally-generated labels.

Table 6.6. Links summary

Name Type Summary

hosts Host[] A list of hosts that were labeled using this scheduling label.

vms Vm[] A list of virtual machines that were labeled using this
scheduling label.

6.5. AGENT STRUCT

Type representing a fence agent.

Table 6.7. Attributes summary

Name Type Summary

address String Fence agent address.

comment String Free text containing comments about this object.

concurrent Boolean Specifies whether the agent should be used concurrently or

sequentially.

description String A human-readable description in plain text.

encrypt_opti Boolean Specifies whether the options should be encrypted.

ons

id String A unique identifier.

name String A human-readable name in plain text.

412
 CHAPTER 6. TYPES

Name Type Summary

options Option[] Fence agent options (comma-delimited list of key-value

pairs).

order Integer The order of this agent if used with other agents.

password String Fence agent password.

port Integer Fence agent port.

type String Fence agent type.

username String Fence agent user name.

Table 6.8. Links summary

Name Type Summary

host Host Reference to the host service.

6.5.1. host

Reference to the host service. Each fence agent belongs to a single host.

6.6. AGENTCONFIGURATION STRUCT

Table 6.9. Attributes summary

Name Type Summary

address String

413
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

broker_type MessageBrokerTy
pe

network_mapp String
ings

password String

port Integer

username String

6.7. API STRUCT

This type contains the information returned by the root service of the API.

To get that information send a request like this:

GET /ovirt-engine/api

The result will be like this:

<api>
<link rel="hosts" href="/ovirt-engine/api/hosts"/>
<link rel="vms" href="/ovirt-engine/api/vms"/>
...
<product_info>
<name>oVirt Engine</name>
<vendor>ovirt.org</vendor>
<version>
<build>0</build>
<full_version>4.1.0_master</full_version>
<major>4</major>
<minor>1</minor>
<revision>0</revision>
</version>
</product_info>
<special_objects>
<link rel="templates/blank" href="..."/>
<link rel="tags/root" href="..."/>
</special_objects>
<summary>
<vms>
<total>10</total>

414
 CHAPTER 6. TYPES

<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>
<time>2016-12-12T12:22:25.866+01:00</time>
</api>

Table 6.10. Attributes summary

Name Type Summary

product_info ProductInfo Information about the product, such as its name, the name of
the vendor, and the version.

special_obje SpecialObjects References to special objects, such as the blank template and
cts the root of the hierarchy of tags.

summary ApiSummary A summary containing the total number of relevant objects,

such as virtual machines, hosts, and storage domains.

time Date The date and time when this information was generated.

6.8. APISUMMARY STRUCT

A summary containing the total number of relevant objects, such as virtual machines, hosts, and
storage domains.

Table 6.11. Attributes summary

Name Type Summary

hosts ApiSummaryItem The summary of hosts.

415
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

storage_doma ApiSummaryItem The summary of storage domains.

ins

users ApiSummaryItem The summary of users.

vms ApiSummaryItem The summary of virtual machines.

6.9. APISUMMARYITEM STRUCT

This type contains an item of the API summary. Each item contains the total and active number of
some kind of object.

Table 6.12. Attributes summary

Name Type Summary

active Integer The total number of active objects.

total Integer The total number of objects.

6.10. APPLICATION STRUCT

Table 6.13. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

416
 CHAPTER 6. TYPES

Table 6.14. Links summary

Name Type Summary

vm Vm

6.11. ARCHITECTURE ENUM

Table 6.15. Values summary

Name Summary

ppc64

undefined

x86_64

6.12. AUTHORIZEDKEY STRUCT

Table 6.16. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

key String

name String A human-readable name in plain text.

417
Red Hat Virtualization 4.0 REST API Guide

Table 6.17. Links summary

Name Type Summary

user User

6.13. AUTONUMASTATUS ENUM

Table 6.18. Values summary

Name Summary

disable

enable

unknown

6.14. BALANCE STRUCT

Table 6.19. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.20. Links summary

418
 CHAPTER 6. TYPES

Name Type Summary

scheduling_p SchedulingPolicy
olicy

scheduling_p SchedulingPolicy
olicy_unit Unit

6.15. BIOS STRUCT

Table 6.21. Attributes summary

Name Type Summary

boot_menu BootMenu

6.16. BLOCKSTATISTIC STRUCT

Table 6.22. Attributes summary

Name Type Summary

statistics Statistic[]

6.17. BONDING STRUCT

Represents a network interfaces bond.

Table 6.23. Attributes summary

Name Type Summary

ad_partner_m Mac The ad_partner_mac property of the partner bond in

ac mode 4.

options Option[] A list of option elements for a bonded interface.

419
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

slaves HostNic[] A list of slave NICs for a bonded interface.

6.17.1. ad_partner_mac

The ad_partner_mac property of the partner bond in mode 4. Bond mode 4 is the 802.3ad
standard, also called dynamic link aggregation - Wikipedia, Presentation. ad_partner_mac is the
MAC address of the system (switch) at the other end of a bond. This parameter is read-only. Setting
it will have no effect on the bond. It is retrieved from
/sys/class/net/bondX/bonding/ad_partner_mac file on the system where the bond is
located.

6.17.2. options

A list of option elements for a bonded interface. Each option contains property name and value
attributes. Only required when adding bonded interfaces.

6.17.3. slaves

A list of slave NICs for a bonded interface. Only required when adding bonded interfaces.

6.18. BOOKMARK STRUCT

Table 6.24. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

value String

6.19. BOOT STRUCT

420
 CHAPTER 6. TYPES

Table 6.25. Attributes summary

Name Type Summary

devices BootDevice[]

6.20. BOOTDEVICE ENUM

Table 6.26. Values summary

Name Summary

cdrom

hd

network

6.21. BOOTMENU STRUCT

Table 6.27. Attributes summary

Name Type Summary

enabled Boolean

6.22. BOOTPROTOCOL ENUM

Defines the options of the IP address assignment method to a NIC.

Table 6.28. Values summary

Name Summary

autoconf Stateless address auto-configuration.

421
Red Hat Virtualization 4.0 REST API Guide

Name Summary

dhcp Dynamic host configuration protocol.

none No address configuration.

static Statically-defined address, mask and gateway.

6.22.1. autoconf

Stateless address auto-configuration.

The mechanism is defined by RFC 4862. Please refer to this wikipedia article for more information.

Note

The value is valid for IPv6 addresses only.

6.22.2. dhcp

Dynamic host configuration protocol.

Please refer to this wikipedia article for more information.

6.23. BRICKPROFILEDETAIL STRUCT

Table 6.29. Attributes summary

Name Type Summary

profile_deta ProfileDetail[]
ils

Table 6.30. Links summary

Name Type Summary

brick GlusterBrick

422
 CHAPTER 6. TYPES

6.24. CDROM STRUCT

Table 6.31. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

file File

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.32. Links summary

Name Type Summary

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

template Template Optionally references to a template the device is used by.

vm Vm Don’t use this element, use vms instead.

vms Vm[] References to the virtual machines that are using this device.

6.24.1. vms

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.25. CERTIFICATE STRUCT

423
Red Hat Virtualization 4.0 REST API Guide

Table 6.33. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

content String

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

organization String

subject String

6.26. CLOUDINIT STRUCT

Table 6.34. Attributes summary

Name Type Summary

authorized_k AuthorizedKey[]
eys

files File[]

host Host

network_conf NetworkConfigura
iguration tion

424
 CHAPTER 6. TYPES

Name Type Summary

regenerate_s Boolean
sh_keys

timezone String

users User[]

6.27. CLUSTER STRUCT

Type representation of a cluster.

A JSON representation of a cluster

{
"cluster" : [ {
"ballooning_enabled" : "false",
"cpu" : {
"architecture" : "x86_64",
"type" : "Intel SandyBridge Family"
},
"custom_scheduling_policy_properties" : {
"property" : [ {
"name" : "HighUtilization",
"value" : "80"
}, {
"name" : "CpuOverCommitDurationMinutes",
"value" : "2"
} ]
},
"error_handling" : {
"on_error" : "migrate"
},
"fencing_policy" : {
"enabled" : "true",
"skip_if_connectivity_broken" : {
"enabled" : "false",
"threshold" : "50"
},
"skip_if_gluster_bricks_up" : "false",
"skip_if_gluster_quorum_not_met" : "false",
"skip_if_sd_active" : {
"enabled" : "false"
}
},
"gluster_service" : "false",
"ha_reservation" : "false",

425
Red Hat Virtualization 4.0 REST API Guide

"ksm" : {
"enabled" : "true",
"merge_across_nodes" : "true"
},
"maintenance_reason_required" : "false",
"memory_policy" : {
"over_commit" : {
"percent" : "100"
},
"transparent_hugepages" : {
"enabled" : "true"
}
},
"migration" : {
"auto_converge" : "inherit",
"bandwidth" : {
"assignment_method" : "auto"
},
"compressed" : "inherit",
"policy" : {
"id" : "00000000-0000-0000-0000-000000000000"
}
},
"optional_reason" : "false",
"required_rng_sources" : {
"required_rng_source" : [ "random" ]
},
"switch_type" : "legacy",
"threads_as_cores" : "false",
"trusted_service" : "false",
"tunnel_migration" : "false",
"version" : {
"major" : "4",
"minor" : "1"
},
"virt_service" : "true",
"data_center" : {
"href" : "/ovirt-engine/api/datacenters/123",
"id" : "123"
},
"mac_pool" : {
"href" : "/ovirt-engine/api/macpools/456",
"id" : "456"
},
"scheduling_policy" : {
"href" : "/ovirt-engine/api/schedulingpolicies/789",
"id" : "789"
},
"actions" : {
"link" : [ {
"href" : "/ovirt-engine/api/clusters/234/resetemulatedmachine",
"rel" : "resetemulatedmachine"
} ]
},
"name" : "Default",
"description" : "The default server cluster",

426
 CHAPTER 6. TYPES

"href" : "/ovirt-engine/api/clusters/234",
"id" : "234",
"link" : [ {
"href" : "/ovirt-engine/api/clusters/234/permissions",
"rel" : "permissions"
}, {
"href" : "/ovirt-engine/api/clusters/234/cpuprofiles",
"rel" : "cpuprofiles"
}, {
"href" : "/ovirt-engine/api/clusters/234/networkfilters",
"rel" : "networkfilters"
}, {
"href" : "/ovirt-engine/api/clusters/234/networks",
"rel" : "networks"
}, {
"href" : "/ovirt-engine/api/clusters/234/affinitygroups",
"rel" : "affinitygroups"
}, {
"href" : "/ovirt-engine/api/clusters/234/glusterhooks",
"rel" : "glusterhooks"
}, {
"href" : "/ovirt-engine/api/clusters/234/glustervolumes",
"rel" : "glustervolumes"
} ]
} ]
}

Table 6.35. Attributes summary

Name Type Summary

ballooning_e Boolean
nabled

comment String Free text containing comments about this object.

cpu Cpu

custom_sched Property[] Custom scheduling policy properties of the cluster.

uling_policy
_properties

description String A human-readable description in plain text.

display Display

427
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

error_handli ErrorHandling
ng

fencing_poli FencingPolicy Custom fencing policy can be defined for a cluster.

cy

gluster_serv Boolean
ice

ha_reservati Boolean
on

id String A unique identifier.

ksm Ksm

maintenance_ Boolean
reason_requi
red

memory_polic MemoryPolicy
y

migration MigrationOptions

name String A human-readable name in plain text.

optional_rea Boolean
son

required_rng RngSource[]
_sources

428
 CHAPTER 6. TYPES

Name Type Summary

serial_numbe SerialNumber
r

supported_ve Version[]
rsions

switch_type SwitchType Type of switch to be used by all networks in given cluster.

threads_as_c Boolean
ores

trusted_serv Boolean
ice

tunnel_migra Boolean
tion

version Version The compatibility version of the cluster.

virt_service Boolean

6.27.1. custom_scheduling_policy_properties

Custom scheduling policy properties of the cluster. These optional properties override the properties
of the scheduling policy specified by the scheduling_policy link, and apply only for this specific
cluster.

For example, to update the custom properties of the cluster, send a request:

PUT /ovirt-engine/api/clusters/123

With a request body:

<cluster>
<custom_scheduling_policy_properties>
<property>
<name>HighUtilization</name>

429
Red Hat Virtualization 4.0 REST API Guide

<value>70</value>
</property>
</custom_scheduling_policy_properties>
</cluster>

Update operations using the custom_scheduling_policy_properties attribute will not update

the the properties of the scheduling policy specified by the scheduling_policy link, they will only
be reflected on this specific cluster.

6.27.2. fencing_policy

Custom fencing policy can be defined for a cluster.

Here is an example:

PUT /ovirt-engine/api/cluster/123

With request body:

<cluster>
<fencing_policy>
<enabled>true</enabled>
<skip_if_sd_active>
<enabled>false</enabled>
</skip_if_sd_active>
<skip_if_connectivity_broken>
<enabled>false</enabled>
<threshold>50</threshold>
</skip_if_connectivity_broken>
</fencing_policy>
</cluster>

6.27.3. version

The compatibility version of the cluster.

All hosts in this cluster must support at least this compatibility version.

For example:

GET /ovirt-engine/api/clusters/123

Will respond:

<cluster>
...
<version>
<major>4</major>
<minor>0</minor>
</version>
...
</cluster>

To update the compatibility version, use:

430
 CHAPTER 6. TYPES

PUT /ovirt-engine/api/clusters/123

With a request body:

<cluster>
<version>
<major>4</major>
<minor>1</minor>
</version>
</cluster>

In order to update the cluster compatibility version, all hosts in the cluster must support the new
compatibility version.

Table 6.36. Links summary

Name Type Summary

affinity_gro AffinityGroup[]
ups

cpu_profiles CpuProfile[]

data_center DataCenter

gluster_hook GlusterHook[]
s

gluster_volu GlusterVolume[]
mes

management_n Network
etwork

network_filt NetworkFilter[]
ers

networks Network[]

permissions Permission[]

431
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

scheduling_p SchedulingPolicy Reference to the default scheduling policy used by this cluster.
olicy

6.27.4. scheduling_policy

Reference to the default scheduling policy used by this cluster.

Note

The scheduling policy properties are taken by default from the referenced scheduling
policy, but they are overridden by the properties specified in the
custom_scheduling_policy_properties attribute for this cluster.

6.28. CLUSTERLEVEL STRUCT

Describes the capabilities supported by a specific cluster level.

Table 6.37. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

cpu_types CpuType[] The CPU types supported by this cluster level.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

permits Permit[] The permits supported by this cluster level.

6.29. CONFIGURATION STRUCT

432
 CHAPTER 6. TYPES

Table 6.38. Attributes summary

Name Type Summary

data String The document describing the virtual machine.

type ConfigurationTyp
e

6.29.1. data

The document describing the virtual machine.

Example of the OVF document:

<?xml version='1.0' encoding='UTF-8'?>

<ovf:Envelope xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1/"
xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-
schema/2/CIM_ResourceAllocationSettingData"
xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-
schema/2/CIM_VirtualSystemSettingData"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
ovf:version="3.5.0.0">
<References/>
<Section xsi:type="ovf:NetworkSection_Type">
<Info>List of networks</Info>
<Network ovf:name="Network 1"/>
</Section>
<Section xsi:type="ovf:DiskSection_Type">
<Info>List of Virtual Disks</Info>
</Section>
<Content ovf:id="out" xsi:type="ovf:VirtualSystem_Type">
<CreationDate>2014/12/03 04:25:45</CreationDate>
<ExportDate>2015/02/09 14:12:24</ExportDate>
<DeleteProtected>false</DeleteProtected>
<SsoMethod>guest_agent</SsoMethod>
<IsSmartcardEnabled>false</IsSmartcardEnabled>
<TimeZone>Etc/GMT</TimeZone>
<default_boot_sequence>0</default_boot_sequence>
<Generation>1</Generation>
<VmType>1</VmType>
<MinAllocatedMem>1024</MinAllocatedMem>
<IsStateless>false</IsStateless>
<IsRunAndPause>false</IsRunAndPause>
<AutoStartup>false</AutoStartup>
<Priority>1</Priority>
<CreatedByUserId>fdfc627c-d875-11e0-90f0-
83df133b58cc</CreatedByUserId>
<IsBootMenuEnabled>false</IsBootMenuEnabled>
<IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled>
<IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled>

433
Red Hat Virtualization 4.0 REST API Guide

<Name>VM_export</Name>
<TemplateId>00000000-0000-0000-0000-000000000000</TemplateId>
<TemplateName>Blank</TemplateName>
<IsInitilized>false</IsInitilized>
<Origin>3</Origin>
<DefaultDisplayType>1</DefaultDisplayType>
<TrustedService>false</TrustedService>
<OriginalTemplateId>00000000-0000-0000-0000-
000000000000</OriginalTemplateId>
<OriginalTemplateName>Blank</OriginalTemplateName>
<UseLatestVersion>false</UseLatestVersion>
<Section ovf:id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a"
ovf:required="false"
xsi:type="ovf:OperatingSystemSection_Type">
<Info>Guest Operating System</Info>
<Description>other</Description>
</Section>
<Section xsi:type="ovf:VirtualHardwareSection_Type">
<Info>1 CPU, 1024 Memory</Info>
<System>
<vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType>
</System>
<Item>
<rasd:Caption>1 virtual cpu</rasd:Caption>
<rasd:Description>Number of virtual CPU</rasd:Description>
<rasd:InstanceId>1</rasd:InstanceId>
<rasd:ResourceType>3</rasd:ResourceType>
<rasd:num_of_sockets>1</rasd:num_of_sockets>
<rasd:cpu_per_socket>1</rasd:cpu_per_socket>
</Item>
<Item>
<rasd:Caption>1024 MB of memory</rasd:Caption>
<rasd:Description>Memory Size</rasd:Description>
<rasd:InstanceId>2</rasd:InstanceId>
<rasd:ResourceType>4</rasd:ResourceType>
<rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits>
<rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
</Item>
<Item>
<rasd:Caption>USB Controller</rasd:Caption>
<rasd:InstanceId>3</rasd:InstanceId>
<rasd:ResourceType>23</rasd:ResourceType>
<rasd:UsbPolicy>DISABLED</rasd:UsbPolicy>
</Item>
</Section>
</Content>
</ovf:Envelope>

6.30. CONFIGURATIONTYPE ENUM

Table 6.39. Values summary

434
 CHAPTER 6. TYPES

Name Summary

ovf

6.31. CONSOLE STRUCT

Table 6.40. Attributes summary

Name Type Summary

enabled Boolean

6.32. CORE STRUCT

Table 6.41. Attributes summary

Name Type Summary

index Integer

socket Integer

6.33. CPU STRUCT

Table 6.42. Attributes summary

Name Type Summary

architecture Architecture

cores Core[]

cpu_tune CpuTune

435
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

level Integer

mode CpuMode

name String

speed Decimal

topology CpuTopology

type String

6.34. CPUMODE ENUM

Table 6.43. Values summary

Name Summary

custom

host_model

host_passthr
ough

6.35. CPUPROFILE STRUCT

Table 6.44. Attributes summary

436
 CHAPTER 6. TYPES

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.45. Links summary

Name Type Summary

cluster Cluster

permissions Permission[]

qos Qos

6.36. CPUTOPOLOGY STRUCT

Table 6.46. Attributes summary

Name Type Summary

cores Integer

sockets Integer

threads Integer

6.37. CPUTUNE STRUCT

437
Red Hat Virtualization 4.0 REST API Guide

Table 6.47. Attributes summary

Name Type Summary

vcpu_pins VcpuPin[]

6.38. CPUTYPE STRUCT

Describes a supported CPU type.

Table 6.48. Attributes summary

Name Type Summary

architecture Architecture The architecture of the CPU.

level Integer The level of the CPU type.

name String The name of the CPU type, for example Intel Conroe
Family .

6.39. CREATIONSTATUS ENUM

Table 6.49. Values summary

Name Summary

complete

failed

in_progress

pending

438
 CHAPTER 6. TYPES

6.40. CUSTOMPROPERTY STRUCT

Table 6.50. Attributes summary

Name Type Summary

name String

regexp String

value String

6.41. DATACENTER STRUCT

Table 6.51. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

local Boolean

name String A human-readable name in plain text.

quota_mode QuotaModeType

status DataCenterStatus

storage_form StorageFormat
at

439
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

supported_ve Version[]
rsions

version Version The compatibility version of the data center.

6.41.1. version

The compatibility version of the data center.

All clusters in this data center must already be set to at least this compatibility version.

For example:

GET /ovirt-engine/api/datacenters/123

Will respond:

<data_center>
...
<version>
<major>4</major>
<minor>0</minor>
</version>
...
</data_center>

To update the compatibility version, use:

PUT /ovirt-engine/api/datacenters/123

With a request body:

<data_center>
<version>
<major>4</major>
<minor>1</minor>
</version>
</data_center>

Table 6.52. Links summary

Name Type Summary

clusters Cluster[] Reference to clusters inside this data center.

440
 CHAPTER 6. TYPES

Name Type Summary

iscsi_bonds IscsiBond[] Reference to ISCSI bonds used by this data center.

mac_pool MacPool Reference to the MAC pool used by this data center.

networks Network[] Reference to networks attached to this data center.

permissions Permission[] Reference to permissions assigned to this data center.

qoss Qos[] Reference to quality of service used by this data center.

quotas Quota[] Reference to quotas assigned to this data center.

storage_doma StorageDomain[] Reference to storage domains attached to this data center.

ins

6.42. DATACENTERSTATUS ENUM

Table 6.53. Values summary

Name Summary

contend

maintenance

not_operatio
nal

problematic

441
Red Hat Virtualization 4.0 REST API Guide

Name Summary

uninitialize
d

up

6.43. DEVICE STRUCT

A device wraps links to potential parents of a device.

Table 6.54. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.55. Links summary

Name Type Summary

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

template Template Optionally references to a template the device is used by.

vm Vm Don’t use this element, use vms instead.

442
 CHAPTER 6. TYPES

Name Type Summary

vms Vm[] References to the virtual machines that are using this device.

6.43.1. vms

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.44. DISK STRUCT

Represents a virtual disk device.

Table 6.56. Attributes summary

Name Type Summary

active Boolean Indicates if the disk is visible to the virtual machine.

actual_size Integer The actual size of the disk, in bytes.

alias String

bootable Boolean Indicates if the disk is marked as bootable.

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

format DiskFormat The underlying storage format.

id String A unique identifier.

image_id String

443
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

interface DiskInterface The type of interface driver used to connect the disk device to
the virtual machine.

logical_name String

lun_storage HostStorage

name String A human-readable name in plain text.

propagate_er Boolean Indicates if disk errors should not cause virtual machine to be
rors paused and, instead, disk errors should be propagated to the
the guest operating system.

provisioned_ Integer The virtual size of the disk, in bytes.

size

read_only Boolean Indicates if the disk is in read-only mode.

sgio ScsiGenericIO

shareable Boolean Indicates if the disk can be attached to multiple virtual

machines.

sparse Boolean Indicates if the physical storage for the disk should not be
preallocated.

status DiskStatus The status of the disk device.

storage_type DiskStorageType

uses_scsi_re Boolean
servation

444
 CHAPTER 6. TYPES

Name Type Summary

wipe_after_d Boolean Indicates if the disk’s blocks will be read back as zeros after it
elete is deleted:

- On block storage, the disk will be zeroed and only then

deleted.

6.44.1. active

Indicates if the disk is visible to the virtual machine.

Important

When adding a disk attachment to a virtual machine, the server accepts requests that
don’t contain this attribute, but the effect is then undefined. In some cases the disk will be
automatically activated and in other cases it won’t. To avoid issues it is strongly
recommended to always include the this attribute with the desired value.

6.44.2. actual_size

The actual size of the disk, in bytes.

The actual size is the number of bytes actually used by the disk, and it will be smaller than the
provisioned size for disks that use the cow format.

6.44.3. bootable

Indicates if the disk is marked as bootable.

Important

This attribute only makes sense for disks that are actually connected to virtual machines,
and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved
here only for backwards compatibility, and it will be removed in the future.

6.44.4. interface

The type of interface driver used to connect the disk device to the virtual machine.

Important

This attribute only makes sense for disks that are actually connected to virtual machines,
and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved
here only for backwards compatibility, and it will be removed in the future.

6.44.5. provisioned_size

445
Red Hat Virtualization 4.0 REST API Guide

6.44.5. provisioned_size

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

6.44.6. shareable

Indicates if the disk can be attached to multiple virtual machines.

Important

When a disk is attached to multiple virtual machines it is the responsibility of the guest
operating systems of those virtual machines to coordinate access to it, to avoid corruption
of the data, for example using a shared file system like GlusterFS or GFS.

6.44.7. wipe_after_delete

Indicates if the disk’s blocks will be read back as zeros after it is deleted:

On block storage, the disk will be zeroed and only then deleted.

On file storage, since the file system already guarantees that previously removed blocks are
read back as zeros, the disk will be deleted immediately.

Table 6.57. Links summary

Name Type Summary

disk_profile DiskProfile

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

openstack_vo OpenStackVolum
lume_type eType

permissions Permission[]

quota Quota

snapshot Snapshot

446
 CHAPTER 6. TYPES

Name Type Summary

statistics Statistic[] Statistics exposed by the disk.

storage_doma StorageDomain
in

storage_doma StorageDomain[] The storage domains associated with this disk.

ins

template Template Optionally references to a template the device is used by.

vm Vm Don’t use this element, use vms instead.

vms Vm[] References to the virtual machines that are using this device.

6.44.8. statistics

Statistics exposed by the disk. For example:

<statistics>
<statistic href="/ovirt-engine/api/disks/123/statistics/456" id="456">
<name>data.current.read</name>
<description>Read data rate</description>
<kind>gauge</kind>
<type>decimal</type>
<unit>bytes_per_second</unit>
<values>
<value>
<datum>1052</datum>
</value>
</values>
<disk href="/ovirt-engine/api/disks/123" id="123"/>
</statistic>
...
</statistics>

These statistics aren’t directly included when the disk is retrieved, only a link. To obtain the statistics
follow that link:

GET /ovirt-engine/api/disks/123/statistics

6.44.9. storage_domains

447
Red Hat Virtualization 4.0 REST API Guide

The storage domains associated with this disk.

Note

Only required when the first disk is being added to a virtual machine that was not itself
created from a template.

6.44.10. vms

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.45. DISKATTACHMENT STRUCT

Describes how a disk is attached to a virtual machine.

Table 6.58. Attributes summary

Name Type Summary

active Boolean This flag indicates if the disk is active in the virtual machine
it’s attached to.

bootable Boolean Defines whether the disk is bootable.

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

interface DiskInterface The type of interface driver used to connect the disk device to
the virtual machine.

logical_name String The logical name of the virtual machine’s disk, as seen from
inside the virtual machine.

name String A human-readable name in plain text.

448
 CHAPTER 6. TYPES

6.45.1. active

This flag indicates if the disk is active in the virtual machine it’s attached to.

A disk attached to a virtual machine in an active status is connected to the virtual machine at run
time and can be used.

6.45.2. logical_name

The logical name of the virtual machine’s disk, as seen from inside the virtual machine.

The logical name of a disk is reported only when the guest agent is installed and running inside the
virtual machine.

For example, if the guest operating system is Linux and the disk is connected via a VirtIO interface,
the logical name will be reported as /dev/vda:

<disk_attachment>
...
<logical_name>/dev/vda</logical_name>
</disk_attachment>

If the guest operating system is Windows, the logical name will be reported as
\\.\PHYSICALDRIVE0.

Table 6.59. Links summary

Name Type Summary

disk Disk The reference to the disk.

template Template The reference to the template.

vm Vm The reference to the virtual machine.

6.46. DISKFORMAT ENUM

The underlying storage format of disks.

Table 6.60. Values summary

Name Summary

cow The Copy On Write format allows snapshots, with a small performance overhead.

449
Red Hat Virtualization 4.0 REST API Guide

Name Summary

raw The raw format does not allow snapshots, but offers improved performance.

6.47. DISKINTERFACE ENUM

Table 6.61. Values summary

Name Summary

ide

spapr_vscsi

virtio

virtio_scsi

6.48. DISKPROFILE STRUCT

Table 6.62. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.63. Links summary

450
 CHAPTER 6. TYPES

Name Type Summary

permissions Permission[]

qos Qos

storage_doma StorageDomain
in

6.49. DISKSNAPSHOT STRUCT

Table 6.64. Attributes summary

Name Type Summary

active Boolean Indicates if the disk is visible to the virtual machine.

actual_size Integer The actual size of the disk, in bytes.

alias String

bootable Boolean Indicates if the disk is marked as bootable.

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

format DiskFormat The underlying storage format.

id String A unique identifier.

image_id String

451
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

interface DiskInterface The type of interface driver used to connect the disk device to
the virtual machine.

logical_name String

lun_storage HostStorage

name String A human-readable name in plain text.

propagate_er Boolean Indicates if disk errors should not cause virtual machine to be
rors paused and, instead, disk errors should be propagated to the
the guest operating system.

provisioned_ Integer The virtual size of the disk, in bytes.

size

read_only Boolean Indicates if the disk is in read-only mode.

sgio ScsiGenericIO

shareable Boolean Indicates if the disk can be attached to multiple virtual

machines.

sparse Boolean Indicates if the physical storage for the disk should not be
preallocated.

status DiskStatus The status of the disk device.

storage_type DiskStorageType

uses_scsi_re Boolean
servation

452
 CHAPTER 6. TYPES

Name Type Summary

wipe_after_d Boolean Indicates if the disk’s blocks will be read back as zeros after it
elete is deleted:

- On block storage, the disk will be zeroed and only then

deleted.

6.49.1. active

Indicates if the disk is visible to the virtual machine.

Important

When adding a disk attachment to a virtual machine, the server accepts requests that
don’t contain this attribute, but the effect is then undefined. In some cases the disk will be
automatically activated and in other cases it won’t. To avoid issues it is strongly
recommended to always include the this attribute with the desired value.

6.49.2. actual_size

The actual size of the disk, in bytes.

The actual size is the number of bytes actually used by the disk, and it will be smaller than the
provisioned size for disks that use the cow format.

6.49.3. bootable

Indicates if the disk is marked as bootable.

Important

This attribute only makes sense for disks that are actually connected to virtual machines,
and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved
here only for backwards compatibility, and it will be removed in the future.

6.49.4. interface

The type of interface driver used to connect the disk device to the virtual machine.

Important

This attribute only makes sense for disks that are actually connected to virtual machines,
and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved
here only for backwards compatibility, and it will be removed in the future.

6.49.5. provisioned_size

453
Red Hat Virtualization 4.0 REST API Guide

6.49.5. provisioned_size

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

6.49.6. shareable

Indicates if the disk can be attached to multiple virtual machines.

Important

When a disk is attached to multiple virtual machines it is the responsibility of the guest
operating systems of those virtual machines to coordinate access to it, to avoid corruption
of the data, for example using a shared file system like GlusterFS or GFS.

6.49.7. wipe_after_delete

Indicates if the disk’s blocks will be read back as zeros after it is deleted:

On block storage, the disk will be zeroed and only then deleted.

On file storage, since the file system already guarantees that previously removed blocks are
read back as zeros, the disk will be deleted immediately.

Table 6.65. Links summary

Name Type Summary

disk Disk

disk_profile DiskProfile

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

openstack_vo OpenStackVolum
lume_type eType

permissions Permission[]

quota Quota

454
 CHAPTER 6. TYPES

Name Type Summary

snapshot Snapshot

statistics Statistic[] Statistics exposed by the disk.

storage_doma StorageDomain
in

storage_doma StorageDomain[] The storage domains associated with this disk.

ins

template Template Optionally references to a template the device is used by.

vm Vm Don’t use this element, use vms instead.

vms Vm[] References to the virtual machines that are using this device.

6.49.8. statistics

Statistics exposed by the disk. For example:

<statistics>
<statistic href="/ovirt-engine/api/disks/123/statistics/456" id="456">
<name>data.current.read</name>
<description>Read data rate</description>
<kind>gauge</kind>
<type>decimal</type>
<unit>bytes_per_second</unit>
<values>
<value>
<datum>1052</datum>
</value>
</values>
<disk href="/ovirt-engine/api/disks/123" id="123"/>
</statistic>
...
</statistics>

These statistics aren’t directly included when the disk is retrieved, only a link. To obtain the statistics
follow that link:

GET /ovirt-engine/api/disks/123/statistics

455
Red Hat Virtualization 4.0 REST API Guide

6.49.9. storage_domains

The storage domains associated with this disk.

Note

Only required when the first disk is being added to a virtual machine that was not itself
created from a template.

6.49.10. vms

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.50. DISKSTATUS ENUM

Table 6.66. Values summary

Name Summary

illegal

locked

ok

6.51. DISKSTORAGETYPE ENUM

Table 6.67. Values summary

Name Summary

cinder

image

lun

456
 CHAPTER 6. TYPES

6.52. DISKTYPE ENUM

Table 6.68. Values summary

Name Summary

data

system

6.53. DISPLAY STRUCT

Table 6.69. Attributes summary

Name Type Summary

address String

allow_overri Boolean
de

certificate Certificate

copy_paste_e Boolean
nabled

disconnect_a String
ction

file_transfe Boolean
r_enabled

keyboard_lay String
out

457
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

monitors Integer

port Integer

proxy String

secure_port Integer

single_qxl_p Boolean
ci

smartcard_en Boolean
abled

type DisplayType

6.54. DISPLAYTYPE ENUM

Table 6.70. Values summary

Name Summary

spice

vnc

6.55. DNS STRUCT

Represents the DNS resolver configuration.

Table 6.71. Attributes summary

458
 CHAPTER 6. TYPES

Name Type Summary

search_domai Host[] Array of hosts serving as search domains.

ns

servers Host[] Array of hosts serving as DNS servers.

6.56. DOMAIN STRUCT

This type represents a directory service domain.

Table 6.72. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

user User

Table 6.73. Links summary

Name Type Summary

groups Group[] A reference to all groups in the directory service.

users User[] A reference to a list of all users in the directory service.

6.56.1. users

459
Red Hat Virtualization 4.0 REST API Guide

A reference to a list of all users in the directory service. This information is used to add new users to
the Red Hat Virtualization environment.

6.57. ENTITYEXTERNALSTATUS ENUM

Type representing an external entity status.

Table 6.74. Values summary

Name Summary

error The external entity status is erroneous.

failure The external entity has an issue that causes failures.

info There external entity status is okay but with some information that might be relevant.

ok The external entity status is okay.

warning The external entity status is okay but with an issue that might require attention.

6.57.1. error

The external entity status is erroneous. This might require a moderate attention.

6.57.2. failure

The external entity has an issue that causes failures. This might require immediate attention.

6.58. ENTITYPROFILEDETAIL STRUCT

Table 6.75. Attributes summary

Name Type Summary

profile_deta ProfileDetail[]
ils

6.59. ERRORHANDLING STRUCT

460
 CHAPTER 6. TYPES

6.59. ERRORHANDLING STRUCT

Table 6.76. Attributes summary

Name Type Summary

on_error MigrateOnError

6.60. EVENT STRUCT

Type representing an event.

Table 6.77. Attributes summary

Name Type Summary

code Integer The event code.

comment String Free text containing comments about this object.

correlation_ String The event correlation identifier.

id

custom_data String Free text representing custom event data.

custom_id Integer A custom event identifier.

description String A human-readable description in plain text.

flood_rate Integer Defines the flood rate.

id String A unique identifier.

name String A human-readable name in plain text.

461
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

origin String Free text identifying the origin of the event.

severity LogSeverity The event severity.

time Date The event time.

6.60.1. correlation_id

The event correlation identifier. Used in order to correlate several events together.

6.60.2. flood_rate

Defines the flood rate. This prevents flooding in case an event appeared more than once in the
defined rate. Defaults is 30 seconds.

Table 6.78. Links summary

Name Type Summary

cluster Cluster Reference to the cluster service.

data_center DataCenter Reference to the data center service.

host Host Reference to the host service.

storage_doma StorageDomain Reference to the storage domain service.

in

template Template Reference to the template service.

user User Reference to the user service.

vm Vm Reference to the virtual machine service.

462
 CHAPTER 6. TYPES

6.60.3. cluster

Reference to the cluster service. Event can be associated with a cluster.

6.60.4. data_center

Reference to the data center service. Event can be associated with a data center.

6.60.5. host

Reference to the host service. Event can be associated with a host.

6.60.6. storage_domain

Reference to the storage domain service. Event can be associated with a storage domain.

6.60.7. template

Reference to the template service. Event can be associated with a template.

6.60.8. user

Reference to the user service. Event can be associated with a user.

6.60.9. vm

Reference to the virtual machine service. Event can be associated with a virtual machine.

6.61. EXTERNALCOMPUTERESOURCE STRUCT

Table 6.79. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

463
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

provider String

url String

user String

Table 6.80. Links summary

Name Type Summary

external_hos ExternalHostProvi
t_provider der

6.62. EXTERNALDISCOVEREDHOST STRUCT

Table 6.81. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

ip String

last_report String

mac String

464
 CHAPTER 6. TYPES

Name Type Summary

name String A human-readable name in plain text.

subnet_name String

Table 6.82. Links summary

Name Type Summary

external_hos ExternalHostProvi
t_provider der

6.63. EXTERNALHOST STRUCT

Table 6.83. Attributes summary

Name Type Summary

address String

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.84. Links summary

465
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

external_hos ExternalHostProvi
t_provider der

6.64. EXTERNALHOSTGROUP STRUCT

Table 6.85. Attributes summary

Name Type Summary

architecture String
_name

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

domain_name String

id String A unique identifier.

name String A human-readable name in plain text.

operating_sy String
stem_name

subnet_name String

Table 6.86. Links summary

466
 CHAPTER 6. TYPES

Name Type Summary

external_hos ExternalHostProvi
t_provider der

6.65. EXTERNALHOSTPROVIDER STRUCT

Table 6.87. Attributes summary

Name Type Summary

authenticati String Defines the external provider authentication URL address.

on_url

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

password String Defines password for the user during the authentication
process.

properties Property[] Array of provider name/value properties.

requires_aut Boolean Defines whether provider authentication is required or not.

hentication

url String Defines URL address of the external provider.

username String Defines user name to be used during authentication process.

467
Red Hat Virtualization 4.0 REST API Guide

6.65.1. requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during
authentication.

Table 6.88. Links summary

Name Type Summary

certificates Certificate[]

compute_reso ExternalCompute
urces Resource[]

discovered_h ExternalDiscovere
osts dHost[]

host_groups ExternalHostGrou
p[]

hosts Host[]

6.66. EXTERNALPROVIDER STRUCT

Represents an external provider.

Table 6.89. Attributes summary

Name Type Summary

authenticati String Defines the external provider authentication URL address.

on_url

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

468
 CHAPTER 6. TYPES

Name Type Summary

id String A unique identifier.

name String A human-readable name in plain text.

password String Defines password for the user during the authentication
process.

properties Property[] Array of provider name/value properties.

requires_aut Boolean Defines whether provider authentication is required or not.

hentication

url String Defines URL address of the external provider.

username String Defines user name to be used during authentication process.

6.66.1. requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during
authentication.

6.67. EXTERNALSTATUS ENUM

Table 6.90. Values summary

Name Summary

error

failure

info

469
Red Hat Virtualization 4.0 REST API Guide

Name Summary

ok

warning

6.68. EXTERNALSYSTEMTYPE ENUM

Represents the type of the external system that is associated with the step.

Table 6.91. Values summary

Name Summary

gluster Represents Gluster as the external system which is associated with the step.

vdsm Represents VDSM as the external system which is associated with the step.

6.69. EXTERNALVMIMPORT STRUCT

Describes parameters of virtual machine import operation from external system.

Table 6.92. Attributes summary

Name Type Summary

name String Name of the virtual machine to be imported as is defined

within the external system.

password String Password to authenticate against external hypervisor system.

provider ExternalVmProvid Type of external virtual machine provider.

erType

sparse Boolean Specifies the disk allocation policy of resulting virtual machine:
true for sparse, false for preallocated.

470
 CHAPTER 6. TYPES

Name Type Summary

url String URL to be passed to the virt-v2v tool for conversion.

username String Username to authenticate against external hypervisor system.

6.69.1. url

URL to be passed to the virt-v2v tool for conversion.

Example:

vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1

More examples can be found at http://libguestfs.org/virt-v2v.1.html.

Table 6.93. Links summary

Name Type Summary

cluster Cluster Specifies the target cluster of the resulting virtual machine.

cpu_profile CpuProfile Optionally specifies the cpu profile of the resulting virtual
machine.

drivers_iso File Optional name of ISO carrying drivers that can be used during
the virt-v2v conversion process.

host Host Optional specification of host (using host’s ID) to be used for
the conversion process.

quota Quota Optionally specifies the quota that will be applied to the
resulting virtual machine.

storage_doma StorageDomain Specifies the target storage domain for converted disks.
in

vm Vm Virtual machine entity used to specify the name of the newly

created virtual machine.

471
Red Hat Virtualization 4.0 REST API Guide

6.69.2. host

Optional specification of host (using host’s ID) to be used for the conversion process. If not
specified, one is selected automatically.

6.69.3. vm

Virtual machine entity used to specify the name of the newly created virtual machine.

If name is not specified, the source virtual machine name will be used.

6.70. EXTERNALVMPROVIDERTYPE ENUM

Describes type of external hypervisor system.

Table 6.94. Values summary

Name Summary

kvm

vmware

xen

6.71. FAULT STRUCT

Table 6.95. Attributes summary

Name Type Summary

detail String

reason String

6.72. FENCETYPE ENUM

Type representing the type of the fence operation.

Table 6.96. Values summary

472
 CHAPTER 6. TYPES

Name Summary

manual Manual host fencing via power management.

restart Restart the host via power management.

start Start the host via power management.

status Check the host power status via power management.

stop Stop the host via power management.

6.73. FENCINGPOLICY STRUCT

Type representing a cluster fencing policy.

Table 6.97. Attributes summary

Name Type Summary

enabled Boolean Enable or disable fencing on this cluster.

skip_if_conn SkipIfConnectivity If enabled, we will not fence a host in case more than a
ectivity_bro Broken configurable percentage of hosts in the cluster lost
ken connectivity as well.

skip_if_sd_a SkipIfSdActive If enabled, we will skip fencing in case the host maintains its
ctive lease in the storage.

6.73.1. skip_if_connectivity_broken

If enabled, we will not fence a host in case more than a configurable percentage of hosts in the
cluster lost connectivity as well. This comes to prevent fencing storm in cases where there is a
global networking issue in the cluster.

6.73.2. skip_if_sd_active

473
Red Hat Virtualization 4.0 REST API Guide

If enabled, we will skip fencing in case the host maintains its lease in the storage. It means that if the
host still has storage access then it won’t get fenced.

6.74. FILE STRUCT

Table 6.98. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

content String

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

type String

Table 6.99. Links summary

Name Type Summary

storage_doma StorageDomain
in

6.75. FILTER STRUCT

Table 6.100. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

474
 CHAPTER 6. TYPES

Name Type Summary

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

position Integer

Table 6.101. Links summary

Name Type Summary

scheduling_p SchedulingPolicy
olicy_unit Unit

6.76. FLOPPY STRUCT

Table 6.102. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

file File

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.103. Links summary

475
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

template Template Optionally references to a template the device is used by.

vm Vm Don’t use this element, use vms instead.

vms Vm[] References to the virtual machines that are using this device.

6.76.1. vms

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.77. FOPSTATISTIC STRUCT

Table 6.104. Attributes summary

Name Type Summary

name String

statistics Statistic[]

6.78. GLUSTERBRICK STRUCT

Table 6.105. Attributes summary

Name Type Summary

brick_dir String

comment String Free text containing comments about this object.

476
 CHAPTER 6. TYPES

Name Type Summary

description String A human-readable description in plain text.

device String

fs_name String

gluster_clie GlusterClient[]
nts

id String A unique identifier.

memory_pools GlusterMemoryPo
ol[]

mnt_options String

name String A human-readable name in plain text.

pid Integer

port Integer

server_id String

status GlusterBrickStatu
s

Table 6.106. Links summary

477
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

gluster_volu GlusterVolume
me

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

statistics Statistic[]

template Template Optionally references to a template the device is used by.

vm Vm Don’t use this element, use vms instead.

vms Vm[] References to the virtual machines that are using this device.

6.78.1. vms

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.79. GLUSTERBRICKADVANCEDDETAILS STRUCT

Table 6.107. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

device String

478
 CHAPTER 6. TYPES

Name Type Summary

fs_name String

gluster_clie GlusterClient[]
nts

id String A unique identifier.

memory_pools GlusterMemoryPo
ol[]

mnt_options String

name String A human-readable name in plain text.

pid Integer

port Integer

Table 6.108. Links summary

Name Type Summary

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

template Template Optionally references to a template the device is used by.

vm Vm Don’t use this element, use vms instead.

vms Vm[] References to the virtual machines that are using this device.

6.79.1. vms

479
Red Hat Virtualization 4.0 REST API Guide

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.80. GLUSTERBRICKMEMORYINFO STRUCT

Table 6.109. Attributes summary

Name Type Summary

memory_pools GlusterMemoryPo
ol[]

6.81. GLUSTERBRICKSTATUS ENUM

Table 6.110. Values summary

Name Summary

down Brick is in down state, the data cannot be stored or retrieved from it.

unknown When the status cannot be determined due to host being non-responsive.

up Brick is in up state, the data can be stored or retrieved from it.

6.82. GLUSTERCLIENT STRUCT

Table 6.111. Attributes summary

Name Type Summary

bytes_read Integer

bytes_writte Integer
n

480
 CHAPTER 6. TYPES

Name Type Summary

client_port Integer

host_name String

6.83. GLUSTERHOOK STRUCT

Table 6.112. Attributes summary

Name Type Summary

checksum String

comment String Free text containing comments about this object.

conflict_sta Integer
tus

conflicts String

content String

content_type HookContentType

description String A human-readable description in plain text.

gluster_comm String
and

id String A unique identifier.

name String A human-readable name in plain text.

481
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

stage HookStage

status GlusterHookStatu
s

Table 6.113. Links summary

Name Type Summary

cluster Cluster

server_hooks GlusterServerHoo
k[]

6.84. GLUSTERHOOKSTATUS ENUM

Table 6.114. Values summary

Name Summary

disabled Hook is disabled in the cluster.

enabled Hook is enabled in the cluster.

missing Unknown/missing hook status.

6.85. GLUSTERMEMORYPOOL STRUCT

Table 6.115. Attributes summary

482
 CHAPTER 6. TYPES

Name Type Summary

alloc_count Integer

cold_count Integer

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

hot_count Integer

id String A unique identifier.

max_alloc Integer

max_stdalloc Integer

name String A human-readable name in plain text.

padded_size Integer

pool_misses Integer

type String

6.86. GLUSTERSERVERHOOK STRUCT

Table 6.116. Attributes summary

483
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

checksum String

comment String Free text containing comments about this object.

content_type HookContentType

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

status GlusterHookStatu
s

Table 6.117. Links summary

Name Type Summary

host Host

6.87. GLUSTERSTATE ENUM

Table 6.118. Values summary

Name Summary

down

unknown

484
 CHAPTER 6. TYPES

Name Summary

up

6.88. GLUSTERVOLUME STRUCT

Table 6.119. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

disperse_cou Integer
nt

id String A unique identifier.

name String A human-readable name in plain text.

options Option[]

redundancy_c Integer
ount

replica_coun Integer
t

status GlusterVolumeSta
tus

stripe_count Integer

485
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

transport_ty TransportType[]
pes

volume_type GlusterVolumeTy
pe

Table 6.120. Links summary

Name Type Summary

bricks GlusterBrick[]

cluster Cluster

statistics Statistic[]

6.89. GLUSTERVOLUMEPROFILEDETAILS STRUCT

Table 6.121. Attributes summary

Name Type Summary

brick_profil BrickProfileDetail[
e_details ]

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

486
 CHAPTER 6. TYPES

Name Type Summary

name String A human-readable name in plain text.

nfs_profile_ NfsProfileDetail[]
details

6.90. GLUSTERVOLUMESTATUS ENUM

Table 6.122. Values summary

Name Summary

down Volume needs to be started, for clients to be able to mount and use it.

unknown When the status cannot be determined due to host being non-responsive.

up Volume is started, and can be mounted and used by clients.

6.91. GLUSTERVOLUMETYPE ENUM

Type representing the type of Gluster Volume.

Table 6.123. Values summary

Name Summary

disperse Dispersed volumes are based on erasure codes, providing space-efficient protection
against disk or server failures.

distribute Distributed volumes distributes files throughout the bricks in the volume.

distributed_ Distributed dispersed volumes distribute files across dispersed subvolumes.

disperse

487
Red Hat Virtualization 4.0 REST API Guide

Name Summary

distributed_ Distributed replicated volumes distributes files across replicated bricks in the
replicate volume.

distributed_ Distributed striped volumes stripe data across two or more nodes in the cluster.
stripe

distributed_ Distributed striped replicated volumes distributes striped data across replicated
striped_repl bricks in the cluster.
icate

replicate Replicated volumes replicates files across bricks in the volume.

stripe Striped volumes stripes data across bricks in the volume.

striped_repl Striped replicated volumes stripes data across replicated bricks in the cluster.
icate

6.91.1. disperse

Dispersed volumes are based on erasure codes, providing space-efficient protection against disk or
server failures.

Dispersed volumes an encoded fragment of the original file to each brick in a way that only a subset
of the fragments is needed to recover the original file. The number of bricks that can be missing
without losing access to data is configured by the administrator on volume creation time.

6.91.2. distribute

Distributed volumes distributes files throughout the bricks in the volume.

Distributed volumes can be used where the requirement is to scale storage and the redundancy is
either not important or is provided by other hardware/software layers.

6.91.3. distributed_disperse

Distributed dispersed volumes distribute files across dispersed subvolumes.

This has the same advantages of distribute replicate volumes, but using disperse to store the data
into the bricks.

6.91.4. distributed_replicate

488
 CHAPTER 6. TYPES

6.91.4. distributed_replicate

Distributed replicated volumes distributes files across replicated bricks in the volume.

Distributed replicated volumes can be used in environments where the requirement is to scale
storage and high-reliability is critical. Distributed replicated volumes also offer improved read
performance in most environments.

6.91.5. distributed_stripe

Distributed striped volumes stripe data across two or more nodes in the cluster.

Distributed striped volumes should be used where the requirement is to scale storage and in high
concurrency environments accessing very large files is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not
recommended and it will be removed in future release.

6.91.6. distributed_striped_replicate

Distributed striped replicated volumes distributes striped data across replicated bricks in the cluster.

For best results, distributed striped replicated volumes should be used in highly concurrent
environments where parallel access of very large files and performance is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not
recommended and it will be removed in future release.

6.91.7. replicate

Replicated volumes replicates files across bricks in the volume.

Replicated volumes can be used in environments where high-availability and high-reliability are
critical.

6.91.8. stripe

Striped volumes stripes data across bricks in the volume.

For best results, striped volumes should only in high concurrency environments accessing very large
files.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not
recommended and it will be removed in future release.

6.91.9. striped_replicate

Striped replicated volumes stripes data across replicated bricks in the cluster.

For best results, striped replicated volumes should be used in highly concurrent environments where
there is parallel access of very large files and performance is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not
recommended and it will be removed in future release.

6.92. GRACEPERIOD STRUCT

489
Red Hat Virtualization 4.0 REST API Guide

6.92. GRACEPERIOD STRUCT

Table 6.124. Attributes summary

Name Type Summary

expiry Integer

6.93. GRAPHICSCONSOLE STRUCT

Table 6.125. Attributes summary

Name Type Summary

address String

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

port Integer

protocol GraphicsType

tls_port Integer

Table 6.126. Links summary

490
 CHAPTER 6. TYPES

Name Type Summary

instance_typ InstanceType
e

template Template

vm Vm

6.94. GRAPHICSTYPE ENUM

Table 6.127. Values summary

Name Summary

spice

vnc

6.95. GROUP STRUCT

This type represents all groups in the directory service.

Table 6.128. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

domain_entry String The containing directory service domain id.

_id

491
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

id String A unique identifier.

name String A human-readable name in plain text.

namespace String Namespace where group resides.

Table 6.129. Links summary

Name Type Summary

domain Domain A link to the domain containing this group.

permissions Permission[] A link to the permissions sub-collection for permissions

attached to this group.

roles Role[] A link to the roles sub-collection for roles attached to this
group.

tags Tag[] A link to the tags sub-collection for tags attached to this
group.

6.95.1. roles

A link to the roles sub-collection for roles attached to this group. Used only to represent the initial
role assignments for a new group, thereafter modification of role assignments are only supported via
the roles sub-collection.

6.96. GUESTOPERATINGSYSTEM STRUCT

Table 6.130. Attributes summary

Name Type Summary

architecture String

492
 CHAPTER 6. TYPES

Name Type Summary

codename String

distribution String

family String

kernel Kernel

version Version

6.97. HARDWAREINFORMATION STRUCT

Table 6.131. Attributes summary

Name Type Summary

family String

manufacturer String

product_name String

serial_numbe String
r

supported_rn RngSource[]
g_sources

uuid String

version String

493
Red Hat Virtualization 4.0 REST API Guide

6.98. HIGHAVAILABILITY STRUCT

Table 6.132. Attributes summary

Name Type Summary

enabled Boolean

priority Integer

6.99. HOOK STRUCT

Table 6.133. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

event_name String

id String A unique identifier.

md5 String

name String A human-readable name in plain text.

Table 6.134. Links summary

Name Type Summary

host Host

494
 CHAPTER 6. TYPES

6.100. HOOKCONTENTTYPE ENUM

Represents content type of hook script.

Table 6.135. Values summary

Name Summary

binary Binary content type of the hook.

text Text content type of the hook.

6.101. HOOKSTAGE ENUM

Table 6.136. Values summary

Name Summary

post

pre

6.102. HOOKSTATUS ENUM

Type represents the status of a hook.

Table 6.137. Values summary

Name Summary

disabled Hook is disabled.

enabled Hook is enabled.

missing Hook is missing.

495
Red Hat Virtualization 4.0 REST API Guide

6.103. HOST STRUCT

Type representing a host.

Table 6.138. Attributes summary

Name Type Summary

address String The host address (FQDN/IP).

auto_numa_st AutoNumaStatus The host auto non uniform memory access (NUMA) status.
atus

certificate Certificate The host certificate.

comment String Free text containing comments about this object.

cpu Cpu The CPU type of this host.

description String A human-readable description in plain text.

device_passt HostDevicePasst Specifies whether host device passthrough is enabled on this

hrough hrough host.

display Display Optionally specify the display address of this host explicitly.

external_sta ExternalStatus The host external status.

tus

hardware_inf HardwareInformat The host hardware information.

ormation ion

hosted_engin HostedEngine The hosted engine status on this host.

e

id String A unique identifier.

496
 CHAPTER 6. TYPES

Name Type Summary

iscsi IscsiDetails The host iSCSI details.

kdump_status KdumpStatus The host KDUMP status.

ksm Ksm Kernel SamePage Merging (KSM) reduces references to

memory pages from multiple identical pages to a single page
reference.

libvirt_vers Version The host libvirt version.

ion

max_scheduli Integer The max scheduling memory on this host in bytes.

ng_memory

memory Integer The amount of physical memory on this host in bytes.

name String A human-readable name in plain text.

numa_support Boolean Specifies whether non uniform memory access (NUMA) is

ed supported on this host.

os OperatingSystem The operating system on this host.

override_ipt Boolean Specifies whether we should override firewall definitions.

ables

port Integer The host port.

power_manage PowerManageme The host power management definitions.

ment nt

497
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

protocol HostProtocol The protocol that the engine uses to communicate with the
host.

root_passwor String When creating a new host, a root password is required if the
d password authentication method is chosen, but this is not
subsequently included in the representation.

se_linux SeLinux The host SElinux status.

spm Spm The host storage pool manager (SPM) status and definition.

ssh Ssh The SSH definitions.

status HostStatus The host status.

status_detai String The host status details.

l

summary VmSummary The virtual machine summary - how many are active,
migrating and total.

transparent_ TransparentHuge Transparent huge page support expands the size of memory
huge_pages Pages pages beyond the standard 4 KiB limit.

type HostType Indicates if the host contains a full installation of the operating
system or a scaled-down version intended only to host virtual
machines.

update_avail Boolean Specifies whether there is an oVirt-related update on this

able host.

version Version The version of VDSM.

6.103.1. external_status

498
 CHAPTER 6. TYPES

6.103.1. external_status

The host external status. This can be used by third-party software to change the host external status
in case of an issue. This has no effect on the host lifecycle, unless a third-party software checks for
this status and acts accordingly.

6.103.2. kdump_status

The host KDUMP status. KDUMP happens when the host kernel has crashed and it is now going
through memory dumping.

6.103.3. ksm

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

For example, to enable KSM for host 123, send a request like this:

PUT /ovirt-engine/api/hosts/123

With a request body like this:

<host>
<ksm>
<enabled>true</enabled>
</ksm>
</host>

6.103.4. libvirt_version

The host libvirt version. For more information on libvirt please go to libvirt.

6.103.5. override_iptables

Specifies whether we should override firewall definitions. This applies only when the host is installed
or re-installed.

6.103.6. se_linux

The host SElinux status. Security-Enhanced Linux (SELinux) is a component in the Linux kernel that
provides a mechanism for supporting access control security policies.

6.103.7. spm

The host storage pool manager (SPM) status and definition. Use it to set the SPM priority of this
host, and to see whether this is the current SPM or not.

6.103.8. status_detail

The host status details. Relevant for Gluster hosts.

6.103.9. transparent_huge_pages

499
Red Hat Virtualization 4.0 REST API Guide

6.103.9. transparent_huge_pages

Transparent huge page support expands the size of memory pages beyond the standard 4 KiB limit.
This reduces memory consumption and increases host performance.

For example, to enable transparent huge page support for host 123, send a request like this:

PUT /ovirt-engine/api/hosts/123

With a request body like this:

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

6.103.10. version

The version of VDSM.

For example:

GET /ovirt-engine/api/hosts/123

This GET request will return the following output:

<host>
...
<version>
<build>999</build>
<full_version>vdsm-4.18.999-419.gitcf06367.el7</full_version>
<major>4</major>
<minor>18</minor>
<revision>0</revision>
</version>
...
</host>

Table 6.139. Links summary

Name Type Summary

affinity_lab AffinityLabel[]
els

agents Agent[]

500
 CHAPTER 6. TYPES

Name Type Summary

cluster Cluster

devices Device[]

external_hos ExternalHostProvi
t_provider der

hooks Hook[]

katello_erra KatelloErratum[] Lists all the Katello errata assigned to the host.
ta

network_atta NetworkAttachme
chments nt[]

nics Nic[]

numa_nodes NumaNode[]

permissions Permission[]

statistics Statistic[] Each host resource exposes a statistics sub-collection for

host-specific statistics.

storage_conn StorageConnectio
ection_exten nExtension[]
sions

storages HostStorage[]

tags Tag[]

501
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

unmanaged_ne UnmanagedNetw
tworks ork[]

6.103.11. katello_errata

Lists all the Katello errata assigned to the host.

GET /ovirt-engine/api/hosts/123/katelloerrata

You will receive response in XML like this one:

<katello_errata>
<katello_erratum href="/ovirt-engine/api/katelloerrata/456" id="456">
<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for
XYZ</summary>
<packages>
<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...
</packages>
</katello_erratum>
...
</katello_errata>

6.103.12. statistics

Each host resource exposes a statistics sub-collection for host-specific statistics.

An example of an XML representation:

<statistics>
<statistic href="/ovirt-engine/api/hosts/123/statistics/456" id="456">
<name>memory.total</name>
<description>Total memory</description>
<kind>gauge</kind>
<type>integer</type>
<unit>bytes</unit>
<values>
<value>
<datum>25165824000</datum>
</value>
</values>
<host href="/ovirt-engine/api/hosts/123" id="123"/>

502
 CHAPTER 6. TYPES

</statistic>
...
</statistics>

Note

This statistics sub-collection is read-only.

The following list shows the statistic types for hosts:

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.shared Memory in bytes shared 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.

503
Red Hat Virtualization 4.0 REST API Guide

Name Description

cpu.current.user Percentage of CPU usage for user slice.

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.

boot.time Boot time of the machine.

6.104. HOSTDEVICE STRUCT

Table 6.140. Attributes summary

Name Type Summary

capability String

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

iommu_group Integer

name String A human-readable name in plain text.

physical_fun HostDevice
ction

504
 CHAPTER 6. TYPES

Name Type Summary

placeholder Boolean

product Product

vendor Vendor

virtual_func Integer
tions

Table 6.141. Links summary

Name Type Summary

host Host

parent_devic HostDevice
e

vm Vm

6.105. HOSTDEVICEPASSTHROUGH STRUCT

Table 6.142. Attributes summary

Name Type Summary

enabled Boolean

6.106. HOSTNIC STRUCT

Represents a host NIC.

For example, the XML representation of a host NIC looks like this:

505
Red Hat Virtualization 4.0 REST API Guide

<host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456">

<name>eth0</name>
<boot_protocol>static</boot_protocol>
<bridged>true</bridged>
<custom_configuration>true</custom_configuration>
<ip>
<address>192.168.122.39</address>
<gateway>192.168.122.1</gateway>
<netmask>255.255.255.0</netmask>
<version>v4</version>
</ip>
<ipv6>
<gateway>::</gateway>
<version>v6</version>
</ipv6>
<ipv6_boot_protocol>none</ipv6_boot_protocol>
<mac>
<address>52:54:00:0c:79:1d</address>
</mac>
<mtu>1500</mtu>
<status>up</status>
</host_nic>

A bonded interface is represented as a HostNic object containing the bonding and slaves
attributes.

For example, the XML representation of a bonded host NIC looks like this:

<host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456">

<name>bond0</name>
<mac address="00:00:00:00:00:00"/>
<ip>
<address>192.168.122.39</address>
<gateway>192.168.122.1</gateway>
<netmask>255.255.255.0</netmask>
<version>v4</version>
</ip>
<boot_protocol>dhcp</boot_protocol>
<bonding>
<options>
<option>
<name>mode</name>
<value>4</value>
<type>Dynamic link aggregation (802.3ad)</type>
</option>
<option>
<name>miimon</name>
<value>100</value>
</option>
</options>
<slaves>
<host_nic id="123"/>
<host_nic id="456"/>
</slaves>
</bonding>

506
 CHAPTER 6. TYPES

<mtu>1500</mtu>
<bridged>true</bridged>
<custom_configuration>false</custom_configuration>
</host_nic>

Table 6.143. Attributes summary

Name Type Summary

ad_aggregato Integer The ad_aggregator_id property of a bond or bond slave,

r_id for bonds in mode 4.

base_interfa String The base interface of the NIC.

ce

bonding Bonding The bonding parameters of the NIC.

boot_protoco BootProtocol The IPv4 boot protocol configuration of the NIC.

l

bridged Boolean Defines the bridged network status.

check_connec Boolean
tivity

comment String Free text containing comments about this object.

custom_confi Boolean
guration

description String A human-readable description in plain text.

id String A unique identifier.

ip Ip The IPv4 address of the NIC.

507
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

ipv6 Ip The IPv6 address of the NIC.

ipv6_boot_pr BootProtocol The IPv6 boot protocol configuration of the NIC.

otocol

mac Mac The MAC address of the NIC.

mtu Integer The maximum transmission unit for the interface.

name String A human-readable name in plain text.

network_labe NetworkLabel[] The labels that are applied to this NIC.

ls

override_con Boolean
figuration

properties Property[]

speed Integer

statistics Statistic[] A link to the statistics of the NIC.

status NicStatus

virtual_func HostNicVirtualFun For a SR-IOV physical function NIC describes its virtual
tions_config ctionsConfiguratio functions configuration.
uration n

vlan Vlan

6.106.1. ad_aggregator_id

508
 CHAPTER 6. TYPES

The ad_aggregator_id property of a bond or bond slave, for bonds in mode 4. Bond mode 4 is
the 802.3ad standard, also called dynamic link aggregation - WikipediaPresentation. This is only
valid for bonds in mode 4, or NICs (NIC - network interface card) which are part of a bond. It is not
present for bonds in other modes, or NICs which are not part in a bond in mode 4. The
ad_aggregator_id property indicates which of the bond slaves are active. The value of the
ad_aggregator_id of an active slave is the same the value of the ad_aggregator_id property
of the bond. This parameter is read only. Setting it will have no effect on the bond/NIC. It is retrieved
from /sys/class/net/bondX/bonding/ad_aggregator file for a bond, and the
/sys/class/net/ensX/bonding_slave/ad_aggregator_id file for a NIC.

6.106.2. bridged

Defines the bridged network status. Set to true for a bridged network and false for a bridgeless
network.

6.106.3. statistics

A link to the statistics of the NIC.

The data types for HostNic statistical values:

data.current.rx - The rate in bytes per second of data received.

data.current.tx - The rate in bytes per second of data transmitted.

data.total.rx - Total received data.

data.total.tx - Total transmitted data.

errors.total.rx - Total errors from receiving data.

errors.total.tx - Total errors from transmitting data.

Table 6.144. Links summary

Name Type Summary

host Host

network Network A reference to the network which the interface should be

connected.

physical_fun HostNic For a SR-IOV virtual function NIC references to its physical
ction function NIC.

qos Qos A link to the quality-of-service configuration of the interface.

509
Red Hat Virtualization 4.0 REST API Guide

6.106.4. network

A reference to the network which the interface should be connected. A blank network id is allowed.

6.107. HOSTNICVIRTUALFUNCTIONSCONFIGURATION STRUCT

Describes virtual functions configuration for an SR-IOV enabled physical function NIC.

Table 6.145. Attributes summary

Name Type Summary

all_networks Boolean Defines whether all networks are allowed to be defined on the
_allowed related virtual functions or specified ones only.

max_number_o Integer Maximum number of virtual functions the NIC supports.

f_virtual_fu
nctions

number_of_vi Integer Number of currently defined virtual functions.

rtual_functi
ons

6.107.1. max_number_of_virtual_functions

Maximum number of virtual functions the NIC supports. Read-only property.

6.107.2. number_of_virtual_functions

Number of currently defined virtual functions. User-defined value between 0 and

maxNumberOfVirtualFunctions.

6.108. HOSTPROTOCOL ENUM

The protocol used by the engine to communicate with a host.

Table 6.146. Values summary

Name Summary

stomp JSON-RPC protocol on top of STOMP.

510
 CHAPTER 6. TYPES

Name Summary

xml XML-RPC protocol.

6.109. HOSTSTATUS ENUM

Type representing a host status.

Table 6.147. Values summary

Name Summary

connecting The engine cannot communicate with the host for a specific threshold so it is now
trying to connect before going through fencing.

down The host is down.

error The host is in error status.

initializing The host is initializing.

install_fail The host installation failed.

ed

installing The host is being installed.

installing_o The host operating system is now installing.

s

kdumping The host kernel has crashed and it is now going through memory dumping.

maintenance The host is in maintenance status.

non_operatio The host is non operational.

nal

511
Red Hat Virtualization 4.0 REST API Guide

Name Summary

non_responsi The host is not responsive.

ve

pending_appr The host is pending administrator approval.

oval

preparing_fo The host is preparing for maintenance.

r_maintenanc
e

reboot The host is being rebooted.

unassigned The host is in activation process.

up The host is up.

6.109.1. error

The host is in error status. This will happen if we will try to run a virtual machine several times and it
will fail.

6.109.2. initializing

The host is initializing. This is an intermediate step before moving the host to 'up' status.

6.109.3. install_failed

The host installation failed. In such cases look at the event log to understand what failed the
installation, and issue a re-install.

6.109.4. installing_os

The host operating system is now installing. This status is relevant when using a Satellite/Foreman
provider, and issuing a bare-metal provisioning (discovered host provisioning).

6.109.5. maintenance

The host is in maintenance status. When a host is in maintenance it cannot run virtual machines.

6.109.6. non_operational

512
 CHAPTER 6. TYPES

The host is non operational. This can happen due to various reasons, such as not having a
connection with the storage, not supporting a mandatory network, not supporting the cluster level,
and more.

6.109.7. non_responsive

The host is not responsive. This means that the engine is not able to communicate with the host.

6.109.8. pending_approval

The host is pending administrator approval. This is relevant only for vintage ovirt-node / RHV-H.

6.109.9. preparing_for_maintenance

The host is preparing for maintenance. During this time the engine makes sure to live migrate all the
virtual machines from this host to other hosts. Once all migrations have been completed the host will
move to 'maintenance' status.

6.110. HOSTSTORAGE STRUCT

Table 6.148. Attributes summary

Name Type Summary

address String

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

logical_unit LogicalUnit[]
s

mount_option String
s

name String A human-readable name in plain text.

513
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

nfs_retrans Integer The number of times to retry a request before attempting

further recovery actions.

nfs_timeo Integer The time in tenths of a second to wait for a response before
retrying NFS requests.

nfs_version NfsVersion

override_lun Boolean
s

password String

path String

port Integer

portal String

target String

type StorageType

username String

vfs_type String

volume_group VolumeGroup

6.110.1. nfs_retrans

514
 CHAPTER 6. TYPES

The number of times to retry a request before attempting further recovery actions. The value must
be in the range of 0 to 65535. For more details see the description of the retrans mount option in
the nfs man page.

6.110.2. nfs_timeo

The time in tenths of a second to wait for a response before retrying NFS requests. The value must
be in the range of 0 to 65535. For more details see the description of the timeo mount option in the
nfs man page.

Table 6.149. Links summary

Name Type Summary

host Host

6.111. HOSTTYPE ENUM

This enumerated type is used to what type of operating system is used by the host.

Table 6.150. Values summary

Name Summary

ovirt_node The host is NGN (Next Generation Node) - a new implementation of RHEV_H which
is like RHEL, CentOS or Fedora installation.

rhel The host contains a full RHEL, CentOS or Fedora installation.

rhev_h The host contains a small scaled version of RHEL, CentOS or Fedora, used solely
to host virtual machines.

6.111.1. ovirt_node

The host is NGN (Next Generation Node) - a new implementation of RHEV_H which is like RHEL,
CentOS or Fedora installation. The main difference between NGN and legacy RHEV-H is that NGN
has a writeable file system and will handle its installation instead of pushing RPMs to it by the
engine in legacy RHEV-H.

6.112. HOSTEDENGINE STRUCT

515
Red Hat Virtualization 4.0 REST API Guide

Table 6.151. Attributes summary

Name Type Summary

active Boolean

configured Boolean

global_maint Boolean
enance

local_mainte Boolean
nance

score Integer

6.113. ICON STRUCT

Icon of virtual machine or template.

Table 6.152. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

data String Base64 encode content of the icon file.

description String A human-readable description in plain text.

id String A unique identifier.

media_type String Format of icon file.

name String A human-readable name in plain text.

516
 CHAPTER 6. TYPES

Name Type Summary

6.113.1. media_type

Format of icon file.

One of:

image/jpeg

image/png

image/gif

6.114. IDENTIFIED STRUCT

This interface is the base model for all types that represent objects with an identifier.

Table 6.153. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

6.115. IMAGE STRUCT

Table 6.154. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

517
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.155. Links summary

Name Type Summary

storage_doma StorageDomain
in

6.116. IMAGETRANSFER STRUCT

This type contains information regarding an image transfer being performed.

Table 6.156. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

phase ImageTransferPh The current phase of the image transfer in progress.

ase

518
 CHAPTER 6. TYPES

Name Type Summary

proxy_url String The URL of the proxy server that the user inputs or outputs to.

signed_ticke String The signed ticket that should be attached as an

t Authentication header in the HTTPS request for the
proxy server to input or output to (See the proxy_url
attribute).

6.116.1. phase

The current phase of the image transfer in progress. Each transfer needs a managed session, which
must be opened for the user to input or output an image. Please refer to image transfer for further
documentation.

6.116.2. proxy_url

The URL of the proxy server that the user inputs or outputs to. This attribute is available only if the
image transfer entity is in the transferring phase. See phase for details.

Table 6.157. Links summary

Name Type Summary

host Host The host which will be used to write to the image which is
targeted for input or output.

image Image The image which is targeted for I/O.

6.117. IMAGETRANSFERPHASE ENUM

A list of possible phases for an image transfer entity. Each of these values defines a specific point in
a transfer flow.

Please refer to image transfer for more information.

Table 6.158. Values summary

Name Summary

cancelled This phase will be set as a result of the user cancelling the transfer.

519
Red Hat Virtualization 4.0 REST API Guide

Name Summary

finalizing_f This phase can only be set in the Administration Portal, and indicates that there was
ailure an error during the transfer, and it is being finalized with a failure.

finalizing_s This phase will be set when the user calls finalize.
uccess

finished_fai Indicates that the targeted image failed the verification, and cannot be used.
lure

finished_suc Indicates that the transfer session was successfully closed, and the targeted image
cess was verified and ready to be used.

initializing The initial phase of an image transfer.

paused_syste This phase means the session timed out, or some other error occurred with this
m transfer; for example ovirt-imageio-daemon is not running in the selected host.

paused_user This phase is a result of a pause call by the user, using pause.

resuming The phase where the transfer has been resumed by the client calling resume.

transferring The phase where the transfer session is open, and the client can input or output the
desired image using the preferred tools.

unknown An unknown phase.

6.117.1. cancelled

This phase will be set as a result of the user cancelling the transfer. The cancellation can only be
performed in the Administration Portal.

6.117.2. finalizing_success

520
 CHAPTER 6. TYPES

This phase will be set when the user calls finalize. Calling finalize is essential to finish the transfer
session, and finish using the targeted image. After finalizing, the phase will be changed to
finished_success or finished_failure.

Refer to image transfer for more information.

6.117.3. finished_failure

Indicates that the targeted image failed the verification, and cannot be used. After reaching this
phase, the image transfer entity will be deleted, and the targeted image will be set to illegal.

6.117.4. finished_success

Indicates that the transfer session was successfully closed, and the targeted image was verified and
ready to be used. After reaching this phase, the image transfer entity will be deleted.

6.117.5. initializing

The initial phase of an image transfer. It is set while the transfer session is establishing. Once the
session is established, the phase will be changed to transferring

6.117.6. paused_system

This phase means the session timed out, or some other error occurred with this transfer; for
example ovirt-imageio-daemon is not running in the selected host. To resume the session, the client
should call resume. After resuming, the phase will change to resuming.

6.117.7. resuming

The phase where the transfer has been resumed by the client calling resume. Resuming starts a
new session, and after calling it, the phase will be changed to transferring, or paused_system
in case of a failure.

6.117.8. unknown

An unknown phase. This will only be set in cases of unpredictable errors.

6.118. INHERITABLEBOOLEAN ENUM

Enum representing the boolean value that can be either set, or inherited from a higher level. The
inheritance order is virtual machine → cluster → engine-config.

Table 6.159. Values summary

Name Summary

false Set the value to false on this level.

521
Red Hat Virtualization 4.0 REST API Guide

Name Summary

inherit Inherit the value from higher level.

true Set the value to true on this level.

6.119. INITIALIZATION STRUCT

Table 6.160. Attributes summary

Name Type Summary

active_direc String
tory_ou

authorized_s String
sh_keys

cloud_init CloudInit

configuratio Configuration
n

custom_scrip String
t

dns_search String

dns_servers String

domain String

host_name String

522
 CHAPTER 6. TYPES

Name Type Summary

input_locale String

nic_configur NicConfiguration[]
ations

org_name String

regenerate_i Boolean
ds

regenerate_s Boolean
sh_keys

root_passwor String
d

system_local String
e

timezone String

ui_language String

user_locale String

user_name String

windows_lice String
nse_key

6.120. INSTANCETYPE STRUCT

Describes the hardware configuration of virtual machines.

523
Red Hat Virtualization 4.0 REST API Guide

For example medium instance type includes 1 virtual CPU and 4 GiB of memory. It is a top-level
entity (e.g. not bound to any data center or cluster). The attributes that are used for instance types
and are common to virtual machine and template types are:

console

cpu

custom_cpu_model

custom_emulated_machine

display

high_availability

io

memory

memory_policy

migration

migration_downtime

os

rng_device

soundcard_enabled

usb

virtio_scsi

When creating a virtual machine from both an instance type and a template, the virtual machine will
inherit the hardware configurations from the instance type

Note

An instance type inherits it’s attributes from the template entity although most template
attributes are not used in instance types.

Table 6.161. Attributes summary

Name Type Summary

bios Bios Reference to virtual machine’s BIOS configuration.

comment String Free text containing comments about this object.

524
 CHAPTER 6. TYPES

Name Type Summary

console Console Console configured for this virtual machine.

cpu Cpu The configuration of the virtual machine CPU.

cpu_shares Integer

creation_tim Date The virtual machine creation date.

e

custom_compa Version Virtual machine custom compatibility version.

tibility_ver
sion

custom_cpu_m String
odel

custom_emula String
ted_machine

custom_prope CustomProperty[] Properties sent to VDSM to configure various hooks.

rties

delete_prote Boolean If true, the virtual machine cannot be deleted.

cted

description String A human-readable description in plain text.

display Display The virtual machine display configuration.

domain Domain Domain configured for this virtual machine.

high_availab HighAvailability The virtual machine high availability configuration.

ility

525
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

id String A unique identifier.

initializati Initialization Reference to virtual machine’s initialization configuration.

on

io Io For performance tuning of IO threading.

large_icon Icon Virtual machine’s large icon.

memory Integer The virtual machine’s memory, in bytes.

memory_polic MemoryPolicy Reference to virtual machine’s memory management

y configuration.

migration MigrationOptions Reference to configuration of migration of running virtual

machine to another host.

migration_do Integer Maximum time the virtual machine can be non responsive
wntime during its live migration to another host in ms.

name String A human-readable name in plain text.

origin String The origin of this virtual machine.

os OperatingSystem Operating system type installed on the virtual machine.

rng_device RngDevice Random Number Generator device configuration for this

virtual machine.

serial_numbe SerialNumber Virtual machine’s serial number in a cluster.

r

526
 CHAPTER 6. TYPES

Name Type Summary

small_icon Icon Virtual machine’s small icon.

soundcard_en Boolean If true, the sound card is added to the virtual machine.
abled

sso Sso Reference to the Single Sign On configuration this virtual

machine is configured for.

start_paused Boolean If true, the virtual machine will be initially in 'paused' state
after start.

stateless Boolean If true, the virtual machine is stateless - it’s state (disks) are
rolled-back after shutdown.

status TemplateStatus The status of the template.

time_zone TimeZone The virtual machine’s time zone set by oVirt.

tunnel_migra Boolean If true, the network data transfer will be encrypted during
tion virtual machine live migration.

type VmType Determines whether the virtual machine is optimized for

desktop or server.

usb Usb Configuration of USB devices for this virtual machine (count,
type).

version TemplateVersion Indicates whether this is a base version or a sub version of

another template.

virtio_scsi VirtioScsi Reference to VirtIO SCSI configuration.

527
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

vm Vm The virtual machine configuration associated with this

template.

6.120.1. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the
threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and
threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>

6.120.2. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If

custom_compatibility_version is set, it overrides the cluster’s compatibility version for this
particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine
resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

6.120.3. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically
restarted when it unexpectedly goes down.

6.120.4. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

6.120.5. memory

528
 CHAPTER 6. TYPES

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following
request:

PUT /ovirt-engine/api/vms/123

With the following request body:

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

Note

Memory in the example is converted to bytes using the following formula:

1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the
example above to increase memory while the virtual machine is running.

6.120.6. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in
ms.

Set either explicitly for the virtual machine or by engine-config -s

DefaultMaximumMigrationDowntime=[value]

6.120.7. origin

The origin of this virtual machine.

Possible values:

ovirt

rhev

vmware

xen

external

hosted_engine

managed_hosted_engine

kvm

529
Red Hat Virtualization 4.0 REST API Guide

physical_machine

hyperv

6.120.8. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating
system.

6.120.9. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be
automatically signed in the virtual machine’s operating system when console is opened.

Table 6.162. Links summary

Name Type Summary

cdroms Cdrom[] References to the CD-ROM devices attached to the template.

cluster Cluster Reference to cluster the virtual machine belongs to.

cpu_profile CpuProfile Reference to CPU profile used by this virtual machine.

disk_attachm DiskAttachment[] References to the disks attached to the template.

ents

graphics_con GraphicsConsole[ References to the graphic consoles attached to the template.

soles ]

nics Nic[] References to the network interfaces attached to the

template.

permissions Permission[] References to the user permissions attached to the template.

quota Quota Reference to quota configuration set for this virtual machine.

storage_doma StorageDomain Reference to storage domain the virtual machine belongs to.
in

530
 CHAPTER 6. TYPES

Name Type Summary

tags Tag[] References to the tags attached to the template.

watchdogs Watchdog[] References to the watchdog devices attached to the template.

6.121. IO STRUCT

Table 6.163. Attributes summary

Name Type Summary

threads Integer

6.122. IP STRUCT
Represents the IP configuration of a network interface.

Table 6.164. Attributes summary

Name Type Summary

address String The text representation of the IP address.

gateway String The address of the default gateway.

netmask String The network mask.

version IpVersion The version of the IP protocol.

6.122.1. address

The text representation of the IP address.

For example, an IPv4 address will be represented as follows:

531
Red Hat Virtualization 4.0 REST API Guide

<ip>
<address>192.168.0.1</address>
...
</ip>

An IPv6 address will be represented as follows:

<ip>
<address>2620:52:0:20f0:4216:7eff:feaa:1b50</address>
...
</ip>

6.122.2. version

The version of the IP protocol.

Note

From version 4.1 of the Manager this attribute will be optional, and when a value is not
provided, it will be inferred from the value of the address attribute.

6.123. IPADDRESSASSIGNMENT STRUCT

Table 6.165. Attributes summary

Name Type Summary

assignment_m BootProtocol
ethod

ip Ip

6.124. IPVERSION ENUM

Defines the values for the IP protocol version.

Table 6.166. Values summary

Name Summary

v4 IPv4.

532
 CHAPTER 6. TYPES

Name Summary

v6 IPv6.

6.125. ISCSIBOND STRUCT

Table 6.167. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.168. Links summary

Name Type Summary

data_center DataCenter

networks Network[]

storage_conn StorageConnectio
ections n[]

6.126. ISCSIDETAILS STRUCT

Table 6.169. Attributes summary

533
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

address String

disk_id String

initiator String

lun_mapping Integer

password String

paths Integer

port Integer

portal String

product_id String

serial String

size Integer

status String

storage_doma String
in_id

target String

username String

534
 CHAPTER 6. TYPES

Name Type Summary

vendor_id String

volume_group String
_id

6.127. JOB STRUCT

Represents a job, which monitors execution of a flow in the system. A job can contain multiple steps
in a hierarchic structure. The steps can be processed in parallel, depends on the implementation of
the flow.

Table 6.170. Attributes summary

Name Type Summary

auto_cleared Boolean Indicates if the job should be cleared automatically after it

was completed by the system.

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

end_time Date The end time of the job.

external Boolean Indicates if the job is originated by an external system.

id String A unique identifier.

last_updated Date The last update date of the job.

name String A human-readable name in plain text.

start_time Date The start time of the job.

535
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

status JobStatus The status of the job.

6.127.1. external

Indicates if the job is originated by an external system. External jobs are managed externally, by the
creator of the job.

Table 6.171. Links summary

Name Type Summary

owner User The user who is the owner of the job.

steps Step[] The steps of the job.

6.128. JOBSTATUS ENUM

Represents the status of the job.

Table 6.172. Values summary

Name Summary

aborted The aborted job status.

failed The failed job status.

finished The finished job status.

started The started job status.

unknown The unknown job status.

6.128.1. aborted

536
 CHAPTER 6. TYPES

The aborted job status. This status is applicable for an external job that was forcibly aborted.

6.128.2. finished

The finished job status. This status describes a completed job execution.

6.128.3. started

The started job status. This status represents a job which is currently being executed.

6.128.4. unknown

The unknown job status. This status represents jobs which their resolution is not known, i.e. jobs
that were executed before the system was unexpectedly restarted.

6.129. KATELLOERRATUM STRUCT

Type representing a Katello erratum.

Table 6.173. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

issued Date The date when the Katello erratum was issued.

name String A human-readable name in plain text.

packages Package[] The list of packages which solve the issue reported by the
Katello erratum.

severity String The severity of the Katello erratum.

solution String The solution for the issue described by the Katello erratum.

537
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

summary String The summary of the Katello erratum.

title String The title of the Katello erratum.

type String The type of the Katello erratum.

6.129.1. severity

The severity of the Katello erratum.

The supported severities are moderate, important or critical.

6.129.2. type

The type of the Katello erratum.

The supported types are bugfix, enhancement or security.

Table 6.174. Links summary

Name Type Summary

host Host Reference to the host that the Katello erratum is assigned to.

vm Vm Reference to the virtual machine that the Katello erratum is

assigned to.

6.130. KDUMPSTATUS ENUM

Table 6.175. Values summary

Name Summary

disabled

enabled

538
 CHAPTER 6. TYPES

Name Summary

unknown

6.131. KERNEL STRUCT

Table 6.176. Attributes summary

Name Type Summary

version Version

6.132. KSM STRUCT

Table 6.177. Attributes summary

Name Type Summary

enabled Boolean

merge_across Boolean
_nodes

6.133. LOGSEVERITY ENUM

Enum representing a severity of an event.

Table 6.178. Values summary

Name Summary

alert Alert severity.

error Error severity.

539
Red Hat Virtualization 4.0 REST API Guide

Name Summary

normal Normal severity.

warning Warning severity.

6.133.1. alert

Alert severity. Used to specify a condition that requires an immediate attention.

6.133.2. error

Error severity. Used to specify that there is an error that needs to be examined.

6.133.3. normal

Normal severity. Used for information events.

6.133.4. warning

Warning severity. Used to warn something might be wrong.

6.134. LOGICALUNIT STRUCT

Table 6.179. Attributes summary

Name Type Summary

address String

disk_id String

id String

lun_mapping Integer

password String

540
 CHAPTER 6. TYPES

Name Type Summary

paths Integer

port Integer

portal String

product_id String

serial String

size Integer

status LunStatus

storage_doma String
in_id

target String

username String

vendor_id String

volume_group String
_id

6.135. LUNSTATUS ENUM

Table 6.180. Values summary

541
Red Hat Virtualization 4.0 REST API Guide

Name Summary

free

unusable

used

6.136. MAC STRUCT

Table 6.181. Attributes summary

Name Type Summary

address String

6.137. MACPOOL STRUCT

Represents a MAC address pool.

Example of an XML representation of a MAC address pool:

<mac_pool href="/ovirt-engine/api/macpools/123" id="123">

<name>Default</name>
<description>Default MAC pool</description>
<allow_duplicates>false</allow_duplicates>
<default_pool>true</default_pool>
<ranges>
<range>
<from>00:1A:4A:16:01:51</from>
<to>00:1A:4A:16:01:E6</to>
</range>
</ranges>
</mac_pool>

Table 6.182. Attributes summary

542
 CHAPTER 6. TYPES

Name Type Summary

allow_duplic Boolean Defines whether duplicate MAC addresses are permitted in

ates the pool.

comment String Free text containing comments about this object.

default_pool Boolean Defines whether this is the default pool.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

ranges Range[] Defines the range of MAC addresses for the pool.

6.137.1. allow_duplicates

Defines whether duplicate MAC addresses are permitted in the pool. If not specified, defaults to
false.

6.137.2. default_pool

Defines whether this is the default pool. If not specified, defaults to false.

6.137.3. ranges

Defines the range of MAC addresses for the pool. Multiple ranges can be defined.

6.138. MEMORYOVERCOMMIT STRUCT

Table 6.183. Attributes summary

Name Type Summary

percent Integer

543
Red Hat Virtualization 4.0 REST API Guide

6.139. MEMORYPOLICY STRUCT

Table 6.184. Attributes summary

Name Type Summary

ballooning Boolean

guaranteed Integer

over_commit MemoryOverCom
mit

transparent_ TransparentHuge
huge_pages Pages

6.140. MESSAGEBROKERTYPE ENUM

Table 6.185. Values summary

Name Summary

qpid

rabbit_mq

6.141. METHOD STRUCT

Table 6.186. Attributes summary

Name Type Summary

id SsoMethod

6.142. MIGRATEONERROR ENUM

544
 CHAPTER 6. TYPES

Table 6.187. Values summary

Name Summary

do_not_migra
te

migrate

migrate_high
ly_available

6.143. MIGRATIONBANDWIDTH STRUCT

Defines the bandwidth used by migration.

Table 6.188. Attributes summary

Name Type Summary

assignment_m MigrationBandwid The method used to assign the bandwidth.

ethod thAssignmentMet
hod

custom_value Integer Custom bandwidth in Mbps.

6.143.1. custom_value

Custom bandwidth in Mbps. Will be applied only if the assignmentMethod attribute is custom.

6.144. MIGRATIONBANDWIDTHASSIGNMENTMETHOD ENUM

Defines the method how the migration bandwidth is assigned.

Table 6.189. Values summary

545
Red Hat Virtualization 4.0 REST API Guide

Name Summary

auto Takes the bandwidth from QoS if QoS defined.

custom Custom defined bandwidth in Mbit/s.

hypervisor_d Takes the value as configured on the hypervisor.

efault

6.144.1. auto

Takes the bandwidth from QoS if QoS defined. If not, taken from detected link speed being used. If
nothing detected, falls back to hypervisor_default value.

6.145. MIGRATIONOPTIONS STRUCT

Table 6.190. Attributes summary

Name Type Summary

auto_converg InheritableBoolea
e n

bandwidth MigrationBandwid The bandwidth which is allowed to be used by the migrations.

th

compressed InheritableBoolea
n

Table 6.191. Links summary

Name Type Summary

policy MigrationPolicy Reference to the migration policy as defined using engine-

config .

6.146. MIGRATIONPOLICY STRUCT

546
 CHAPTER 6. TYPES

A policy describing how the migration is going to be treated (convergence, how many parallel
migrations allowed).

Table 6.192. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

6.147. NETWORK STRUCT

Logical network.

An example of the JSON representation of a logical network:

{
"network" : [ {
"data_center" : {
"href" : "/ovirt-engine/api/datacenters/123",
"id" : "123"
},
"stp" : "false",
"mtu" : "0",
"usages" : {
"usage" : [ "vm" ]
},
"name" : "ovirtmgmt",
"description" : "Management Network",
"href" : "/ovirt-engine/api/networks/456",
"id" : "456",
"link" : [ {
"href" : "/ovirt-engine/api/networks/456/permissions",
"rel" : "permissions"
}, {
"href" : "/ovirt-engine/api/networks/456/vnicprofiles",
"rel" : "vnicprofiles"
}, {
"href" : "/ovirt-engine/api/networks/456/labels",

547
Red Hat Virtualization 4.0 REST API Guide

"rel" : "labels"
} ]
} ]
}

An example of the XML representation of the same logical network:

<network href="/ovirt-engine/api/networks/456" id="456">

<name>ovirtmgmt</name>
<description>Management Network</description>
<link href="/ovirt-engine/api/networks/456/permissions"
rel="permissions"/>
<link href="/ovirt-engine/api/networks/456/vnicprofiles"
rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/456/labels" rel="labels"/>
<data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
<stp>false</stp>
<mtu>0</mtu>
<usages>
<usage>vm</usage>
</usages>
</network>

Table 6.193. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

display Boolean

id String A unique identifier.

ip Ip

mtu Integer Specifies the maximum transmission unit for the network.

name String A human-readable name in plain text.

548
 CHAPTER 6. TYPES

Name Type Summary

profile_requ Boolean
ired

required Boolean

status NetworkStatus

stp Boolean Specifies whether spanning tree protocol is enabled for the
network.

usages NetworkUsage[] Defines a set of usage elements for the network.

vlan Vlan

6.147.1. usages

Defines a set of usage elements for the network.

Users can, for example, specify that the network is to be used for virtual machine traffic and also for
display traffic with the vm and display values.

Table 6.194. Links summary

Name Type Summary

cluster Cluster

data_center DataCenter A reference to the data center of which the network is a

member.

network_labe NetworkLabel[] A reference to the labels assigned to the network.

ls

permissions Permission[] A reference to the permissions of the network.

549
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

qos Qos

vnic_profile VnicProfile[] A reference to the profiles of the network.

s

6.148. NETWORKATTACHMENT STRUCT

Describes how a host connects to a network.

An XML representation of a network attachment on a host:

<network_attachment href="/ovirt-
engine/api/hosts/123/nics/456/networkattachments/789" id="789">
<network href="/ovirt-engine/api/networks/234" id="234"/>
<host_nic href="/ovirt-engine/api/hosts/123/nics/123" id="123"/>
<in_sync>true</in_sync>
<ip_address_assignments>
<ip_address_assignment>
<assignment_method>static</assignment_method>
<ip>
<address>192.168.122.39</address>
<gateway>192.168.122.1</gateway>
<netmask>255.255.255.0</netmask>
<version>v4</version>
</ip>
</ip_address_assignment>
</ip_address_assignments>
<reported_configurations>
<reported_configuration>
<name>mtu</name>
<expected_value>1500</expected_value>
<actual_value>1500</actual_value>
<in_sync>true</in_sync>
</reported_configuration>
<reported_configuration>
<name>bridged</name>
<expected_value>true</expected_value>
<actual_value>true</actual_value>
<in_sync>true</in_sync>
</reported_configuration>
...
</reported_configurations>
</network_attachment>

When attaching a network to a network interface card, the network element is required, with either
an id or a name.

For example, to attach a network to a host network interface card, send a request like this:

550
 CHAPTER 6. TYPES

POST /ovirt-engine/api/hosts/123/nics/456/networkattachments

With a request body like this:

<networkattachment>
<network id="234"/>
</networkattachment>

To attach a newtwork to a host, send a request like this:

POST /ovirt-engine/api/hosts/123/networkattachments

With a request body like this:

<network_attachment>
<network id="234"/>
<host_nic id="456"/>
</network_attachment>

The ip_address_assignments and properties elements are updatable post-creation.

For example to update a newtork attachment, send a request like this:

PUT /ovirt-engine/api/hosts/123/nics/456/networkattachments/789

With a request body like this:

<network_attachment>
<ip_address_assignments>
<ip_address_assignment>
<assignment_method>static</assignment_method>
<ip>
<address>7.1.1.1</address>
<gateway>7.1.1.2</gateway>
<netmask>255.255.255.0</netmask>
<version>v4</version>
</ip>
</ip_address_assignment>
</ip_address_assignments>
</network_attachment>

To detach a network from the network interface card send a request like this:

DELETE /ovirt-engine/api/hosts/123/nics/456/networkattachments/789

Important

Changes to network attachment configuration must be explicitly committed.

An XML representation of a network attachment’s properties sub-collection:

<network_attachment>

551
Red Hat Virtualization 4.0 REST API Guide

<properties>
<property>
<name>bridge_opts</name>
<value>
forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
</value>
</property>
</properties>
...
</network_attachment>

Table 6.195. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

in_sync Boolean

ip_address_a IpAddressAssign The IP configuration of the network.

ssignments ment[]

name String A human-readable name in plain text.

properties Property[] Defines custom properties for the network configuration.

reported_con ReportedConfigur A read-only list of configuration properties.

figurations ation[]

6.148.1. properties

Defines custom properties for the network configuration.

Bridge options have the set name of bridge_opts. Separate multiple entries with a whitespace
character. The following keys are valid for bridge_opts:

552
 CHAPTER 6. TYPES

Name Default value

forward_delay 1500

gc_timer 3765

group_addr 1:80:c2:0:0:0

group_fwd_mask 0x0

hash_elasticity 4

hash_max 512

hello_time 200

hello_timer 70

max_age 2000

multicast_last_member_count 2

multicast_last_member_interval 100

multicast_membership_interval 26000

multicast_querier 0

multicast_querier_interval 25500

multicast_query_interval 13000

553
Red Hat Virtualization 4.0 REST API Guide

Name Default value

multicast_query_response_interval 1000

multicast_query_use_ifaddr 0

multicast_router 1

multicast_snooping 1

multicast_startup_query_count 2

multicast_startup_query_interval 3125

Table 6.196. Links summary

Name Type Summary

host Host

host_nic HostNic A reference to the host network interface.

network Network A reference to the network to which the interface is attached.

qos Qos

6.149. NETWORKCONFIGURATION STRUCT

Table 6.197. Attributes summary

554
 CHAPTER 6. TYPES

Name Type Summary

dns Dns

nics Nic[]

6.150. NETWORKFILTER STRUCT

Network filter enables to filter packets send to/from the VM’s nic according to defined rules.

There are several types of network filters supported based on libvirt. More details about the different
network filters can be found here.

In addition to libvirt’s network filters, there are two additional network filters: The first called vdsm-
no-mac-spoofing, composed of no-mac-spoofing and no-arp-mac-spoofing. The second called
ovirt-no-filter is used when no network filter is to be defined for the VM’s nic. ovirt-no-
filter network filter is only used for internal implementation, and doesn’t exist on the nics.

This is a example of the XML representation:

<network_filter id="00000019-0019-0019-0019-00000000026c">
<name>example-filter</name>
<version>
<major>4</major>
<minor>0</minor>
<build>-1</build>
<revision>-1</revision>
</version>
</network_filter>

If any part of the version is not present, it is represented by -1.

Table 6.198. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

555
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

version Version Represent the minimal supported version of the specific

NetworkFilter for which it was first introduced.

6.151. NETWORKLABEL STRUCT

Represents a label which can be added to a host network interface.

Table 6.199. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.200. Links summary

Name Type Summary

host_nic HostNic

network Network

6.152. NETWORKPLUGINTYPE ENUM

Table 6.201. Values summary

556
 CHAPTER 6. TYPES

Name Summary

open_vswitch

6.153. NETWORKSTATUS ENUM

Table 6.202. Values summary

Name Summary

non_operatio
nal

operational

6.154. NETWORKUSAGE ENUM

Table 6.203. Values summary

Name Summary

display

gluster The network will be used for Gluster(bricks) data traffic.

management

migration

vm

6.155. NFSPROFILEDETAIL STRUCT

Table 6.204. Attributes summary

557
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

nfs_server_i String
p

profile_deta ProfileDetail[]
ils

6.156. NFSVERSION ENUM

Table 6.205. Values summary

Name Summary

auto

v3

v4

v4_1

6.157. NIC STRUCT

Represents a NIC of a virtual machine.

For example, the XML representation of a NIC will look like this:

<nic href="/ovirt-engine/api/vms/123/nics/456" id="456">

<name>nic1</name>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
<interface>virtio</interface>
<linked>true</linked>
<mac>
<address>02:00:00:00:00:00</address>
</mac>
<plugged>true</plugged>
<vnic_profile href="/ovirt-engine/api/vnicprofiles/789" id="789"/>
</nic>

Table 6.206. Attributes summary

558
 CHAPTER 6. TYPES

Name Type Summary

boot_protoco BootProtocol
l

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

interface NicInterface The type of driver used for the NIC.

linked Boolean Defines if the NIC is linked to the virtual machine.

mac Mac The MAC address of the interface.

name String A human-readable name in plain text.

on_boot Boolean

plugged Boolean Defines if the NIC is plugged in to the virtual machine.

Table 6.207. Links summary

Name Type Summary

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

network Network A reference to the network which the interface should be

connected to.

559
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

network_atta NetworkAttachme
chments nt[]

network_labe NetworkLabel[]
ls

reported_dev ReportedDevice[]
ices

statistics Statistic[] A link to the statistics for the NIC.

template Template Optionally references to a template the device is used by.

virtual_func NetworkLabel[]
tion_allowed
_labels

virtual_func Network[]
tion_allowed
_networks

vm Vm Don’t use this element, use vms instead.

vms Vm[] References to the virtual machines that are using this device.

vnic_profile VnicProfile

6.157.1. network

A reference to the network which the interface should be connected to. A blank network id is
allowed.

Usage of this element for creating or updating a NIC is deprecated, use vnic_profile instead. It
is preserved because it is still in use by the initialization element, as a holder for IP
addresses and other network details.

560
 CHAPTER 6. TYPES

6.157.2. vms

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.158. NICCONFIGURATION STRUCT

Table 6.208. Attributes summary

Name Type Summary

boot_protoco BootProtocol
l

ip Ip

name String

on_boot Boolean

6.159. NICINTERFACE ENUM

Table 6.209. Values summary

Name Summary

e1000

pci_passthro
ugh

rtl8139

rtl8139_virt
io

561
Red Hat Virtualization 4.0 REST API Guide

Name Summary

spapr_vlan

virtio

6.160. NICSTATUS ENUM

Table 6.210. Values summary

Name Summary

down

up

6.161. NUMANODE STRUCT

Represents a physical NUMA node.

Example XML representation:

<host_numa_node href="/ovirt-
engine/api/hosts/0923f1ea/numanodes/007cf1ab" id="007cf1ab">
<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>65536</memory>
<node_distance>40 20 40 10</node_distance>
<host href="/ovirt-engine/api/hosts/0923f1ea" id="0923f1ea"/>
</host_numa_node>

Table 6.211. Attributes summary

562
 CHAPTER 6. TYPES

Name Type Summary

comment String Free text containing comments about this object.

cpu Cpu

description String A human-readable description in plain text.

id String A unique identifier.

index Integer

memory Integer Memory of the NUMA node in MB.

name String A human-readable name in plain text.

node_distanc String
e

Table 6.212. Links summary

Name Type Summary

host Host

statistics Statistic[]

6.162. NUMANODEPIN STRUCT

Represents pinning of a virtual NUMA node to a physical NUMA node.

Table 6.213. Attributes summary

563
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

host_numa_no NumaNode Deprecated - has no function.

de

index Integer Index of a physical NUMA node to which the virtual NUMA
node is pinned.

pinned Boolean Deprecated - should always be true.

6.163. NUMATUNEMODE ENUM

Table 6.214. Values summary

Name Summary

interleave

preferred

strict

6.164. OPENSTACKIMAGE STRUCT

Table 6.215. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

564
 CHAPTER 6. TYPES

Name Type Summary

name String A human-readable name in plain text.

Table 6.216. Links summary

Name Type Summary

openstack_im OpenStackImage
age_provider Provider

6.165. OPENSTACKIMAGEPROVIDER STRUCT

Table 6.217. Attributes summary

Name Type Summary

authenticati String Defines the external provider authentication URL address.

on_url

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

password String Defines password for the user during the authentication
process.

properties Property[] Array of provider name/value properties.

565
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

requires_aut Boolean Defines whether provider authentication is required or not.

hentication

tenant_name String

url String Defines URL address of the external provider.

username String Defines user name to be used during authentication process.

6.165.1. requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during
authentication.

Table 6.218. Links summary

Name Type Summary

certificates Certificate[]

images OpenStackImage[
]

6.166. OPENSTACKNETWORK STRUCT

Table 6.219. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

566
 CHAPTER 6. TYPES

Name Type Summary

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.220. Links summary

Name Type Summary

openstack_ne OpenStackNetwor
twork_provid kProvider
er

6.167. OPENSTACKNETWORKPROVIDER STRUCT

Table 6.221. Attributes summary

Name Type Summary

agent_config AgentConfiguratio Agent configuration settings.

uration n

authenticati String Defines the external provider authentication URL address.

on_url

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

567
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

password String Defines password for the user during the authentication
process.

plugin_type NetworkPluginTyp Network plugin type.

e

properties Property[] Array of provider name/value properties.

read_only Boolean Indicates whether the provider is read-only.

requires_aut Boolean Defines whether provider authentication is required or not.

hentication

tenant_name String

type OpenStackNetwor The type of provider.

kProviderType

url String Defines URL address of the external provider.

username String Defines user name to be used during authentication process.

6.167.1. read_only

Indicates whether the provider is read-only.

A read-only provider does not allow adding, modifying or deleting of networks or subnets. Port-
related operations are allowed, as they are required for the provisioning of virtual NICs.

6.167.2. requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during
authentication.

Table 6.222. Links summary

568
 CHAPTER 6. TYPES

Name Type Summary

certificates Certificate[] Reference to the certificates list.

networks OpenStackNetwor Reference to OpenStack networks list.

k[]

subnets OpenStackSubnet Reference to OpenStack networks subnets list.

[]

6.168. OPENSTACKNETWORKPROVIDERTYPE ENUM

The OpenStack network provider can either be implemented by OpenStack Neutron, in which case
the Neutron agent is automatically installed on the hosts, or it can be an external provider
implementing the OpenStack API, in which case the virtual interface driver will be a custom solution
installed manually.

Table 6.223. Values summary

Name Summary

external Indicates that the provider is an external one, implementing the OpenStack Neutron
API.

neutron Indicates that the provider is OpenStack Neutron.

6.168.1. external

Indicates that the provider is an external one, implementing the OpenStack Neutron API. The virtual
interface driver in this case is implemented by the external provider.

6.168.2. neutron

Indicates that the provider is OpenStack Neutron. The standard OpenStack Neutron agent will be
used as the virtual interface driver.

6.169. OPENSTACKPROVIDER STRUCT

Table 6.224. Attributes summary

569
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

authenticati String Defines the external provider authentication URL address.

on_url

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

password String Defines password for the user during the authentication
process.

properties Property[] Array of provider name/value properties.

requires_aut Boolean Defines whether provider authentication is required or not.

hentication

tenant_name String

url String Defines URL address of the external provider.

username String Defines user name to be used during authentication process.

6.169.1. requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during
authentication.

6.170. OPENSTACKSUBNET STRUCT

Table 6.225. Attributes summary

570
 CHAPTER 6. TYPES

Name Type Summary

cidr String Defines network CIDR.

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

dns_servers String[] Defines a list of DNS servers.

gateway String Defines IP gateway.

id String A unique identifier.

ip_version String Defines IP version.

name String A human-readable name in plain text.

6.170.1. ip_version

Defines IP version.

Values can be v4' for IPv4 or `v6 for IPv6.

Table 6.226. Links summary

Name Type Summary

openstack_ne OpenStackNetwor Reference to the service managing the OpenStack network.

twork k

6.171. OPENSTACKVOLUMEPROVIDER STRUCT

Table 6.227. Attributes summary

571
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

authenticati String Defines the external provider authentication URL address.

on_url

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

password String Defines password for the user during the authentication
process.

properties Property[] Array of provider name/value properties.

requires_aut Boolean Defines whether provider authentication is required or not.

hentication

tenant_name String

url String Defines URL address of the external provider.

username String Defines user name to be used during authentication process.

6.171.1. requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during
authentication.

Table 6.228. Links summary

572
 CHAPTER 6. TYPES

Name Type Summary

authenticati OpenstackVolum
on_keys eAuthenticationKe
y[]

certificates Certificate[]

data_center DataCenter

volume_types OpenStackVolum
eType[]

6.172. OPENSTACKVOLUMETYPE STRUCT

Table 6.229. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

properties Property[]

Table 6.230. Links summary

573
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

openstack_vo OpenStackVolum
lume_provide eProvider
r

6.173. OPENSTACKVOLUMEAUTHENTICATIONKEY STRUCT

Table 6.231. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

creation_dat Date
e

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

usage_type OpenstackVolum
eAuthenticationKe
yUsageType

uuid String

value String

Table 6.232. Links summary

574
 CHAPTER 6. TYPES

Name Type Summary

openstack_vo OpenStackVolum
lume_provide eProvider
r

6.174. OPENSTACKVOLUMEAUTHENTICATIONKEYUSAGETYPE
ENUM

Table 6.233. Values summary

Name Summary

ceph

6.175. OPERATINGSYSTEM STRUCT

Information describing the operating system. Used for virtual machines and hosts.

Table 6.234. Attributes summary

Name Type Summary

boot Boot

cmdline String

custom_kerne String A custom part of the host kernel command line.

l_cmdline

initrd String

kernel String

575
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

reported_ker String Host kernel command line as reported by a running host.

nel_cmdline

type String

version Version

6.175.1. custom_kernel_cmdline

A custom part of the host kernel command line. This will be merged with the existing kernel
command line.

You must re-install and then reboot the host to apply the changes implemented by this attribute.

Parameters merging: During each host deploy procedure, kernel parameters that were added in the
previous host deploy procedure are removed using grubby --update-kernel DEFAULT --
remove-args <previous_custom_params> and the current kernel command line customization
is applied using grubby --update-kernel DEFAULT --args <custom_params>. The
Engine internally keeps track of the last applied kernel parameters customization.

Note

This attribute is currently only used for hosts.

6.175.2. reported_kernel_cmdline

Host kernel command line as reported by a running host.

Read-only attribute. Attempts to change this attribute are silently ignored.

Note

This attribute is currently only used for hosts.

6.176. OPERATINGSYSTEMINFO STRUCT

Table 6.235. Attributes summary

576
 CHAPTER 6. TYPES

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

large_icon Icon

name String A human-readable name in plain text.

small_icon Icon

6.177. OPTION STRUCT

Table 6.236. Attributes summary

Name Type Summary

name String

type String

value String

6.178. OSTYPE ENUM

Table 6.237. Values summary

Name Summary

other

577
Red Hat Virtualization 4.0 REST API Guide

Name Summary

other_linux

rhel_3

rhel_3x64

rhel_4

rhel_4x64

rhel_5

rhel_5x64

rhel_6

rhel_6x64

unassigned

windows_2003

windows_2003
x64

windows_2008

windows_2008
r2x64

578
 CHAPTER 6. TYPES

Name Summary

windows_2008
x64

windows_2012
x64

windows_7

windows_7x64

windows_8

windows_8x64

windows_xp

6.179. PACKAGE STRUCT

Type representing a package.

This is an example of the package element:

<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>

Table 6.238. Attributes summary

Name Type Summary

name String The name of the package.

6.180. PAYLOAD STRUCT

Table 6.239. Attributes summary

579
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

files File[]

type VmDeviceType

volume_id String

6.181. PAYLOADENCODING ENUM

Table 6.240. Values summary

Name Summary

base64

plaintext

6.182. PERMISSION STRUCT

Table 6.241. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.242. Links summary

580
 CHAPTER 6. TYPES

Name Type Summary

cluster Cluster

data_center DataCenter

disk Disk

group Group

host Host

role Role

storage_doma StorageDomain
in

template Template

user User

vm Vm

vm_pool VmPool

6.183. PERMIT STRUCT

Type represents a permit.

Table 6.243. Attributes summary

581
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

administrati Boolean Specifies whether permit is administrative or not.

ve

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.244. Links summary

Name Type Summary

role Role Reference to the role the permit belongs to.

6.184. PMPROXY STRUCT

Table 6.245. Attributes summary

Name Type Summary

type PmProxyType

6.185. PMPROXYTYPE ENUM

Table 6.246. Values summary

Name Summary

cluster Fence proxy is selected from the same cluster as fenced host.

582
 CHAPTER 6. TYPES

Name Summary

dc Fence proxy is selected from the same data center as fenced host.

other_dc Fence proxy is selected from a different data center than fenced host.

6.186. POLICYUNITTYPE ENUM

This enum holds the types of all internal policy units types

Table 6.247. Values summary

Name Summary

filter

load_balanci
ng

weight

6.187. PORTMIRRORING STRUCT

6.188. POWERMANAGEMENT STRUCT

Table 6.248. Attributes summary

Name Type Summary

address String The host name or IP address of the host.

agents Agent[] Specifies fence agent options when multiple fences are used.

automatic_pm Boolean Toggles the automated power control of the host in order to
_enabled save energy.

583
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

enabled Boolean Indicates whether power management configuration is

enabled or disabled.

kdump_detect Boolean Toggles whether to determine if kdump is running on the host

ion before it is shut down.

options Option[] Fencing options for the selected type= specified with the
option name="" and value="" strings.

password String A valid, robust password for power management.

pm_proxies PmProxy[] Determines the power management proxy.

status PowerManageme Determines the power status of the host.

ntStatus

type String Fencing device code.

username String A valid user name for power management.

6.188.1. agents

Specifies fence agent options when multiple fences are used.

Use the order sub-element to prioritize the fence agents. Agents are run sequentially according to
their order until the fence action succeeds. When two or more fence agents have the same order,
they are run concurrently. Other sub-elements include type, ip, user, password, and options.

6.188.2. automatic_pm_enabled

Toggles the automated power control of the host in order to save energy. When set to true, the host
will be automatically powered down if the cluster’s load is low, and powered on again when required.
This is set to true when a host is created, unless disabled by the user.

6.188.3. kdump_detection

Toggles whether to determine if kdump is running on the host before it is shut down. When set to
true, the host will not shut down during a kdump process. This is set to true when a host has
power management enabled, unless disabled by the user.

584
 CHAPTER 6. TYPES

6.188.4. type

Fencing device code.

A list of valid fencing device codes are available in the capabilities collection.

6.189. POWERMANAGEMENTSTATUS ENUM

Table 6.249. Values summary

Name Summary

off Host is OFF.

on Host is ON.

unknown Unknown status.

6.190. PRODUCT STRUCT

Table 6.250. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

6.191. PRODUCTINFO STRUCT

Product information.

585
Red Hat Virtualization 4.0 REST API Guide

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

Verify a genuine Red Hat Virtualization environment

The follow elements identify a genuine Red Hat Virtualization environment:

<api>
...
<product_info>
<name>oVirt Engine</name>
<vendor>ovirt.org</vendor>
<version>
<build>0</build>
<full_version>4.1.0_master</full_version>
<major>4</major>
<minor>1</minor>
<revision>0</revision>
</version>
</product_info>
...
</api>

Table 6.251. Attributes summary

Name Type Summary

name String The name of the product, for example oVirt Engine.

vendor String The name of the vendor, for example `ovirt.

version Version The version number of the product.

6.191.1. vendor

The name of the vendor, for example ovirt.org.

6.192. PROFILEDETAIL STRUCT

Table 6.252. Attributes summary

586
 CHAPTER 6. TYPES

Name Type Summary

block_statis BlockStatistic[]
tics

duration Integer

fop_statisti FopStatistic[]
cs

profile_type String

statistics Statistic[]

6.193. PROPERTY STRUCT

Table 6.253. Attributes summary

Name Type Summary

name String

value String

6.194. PROXYTICKET STRUCT

Table 6.254. Attributes summary

Name Type Summary

value String

6.195. QOS STRUCT

This type represents the attributes to define Quality of service (QoS).

587
Red Hat Virtualization 4.0 REST API Guide

For storage the type is storage, the attributes max_throughput, max_read_throughput,

max_write_throughput, max_iops, max_read_iops and max_write_iops are relevant.

For resources with computing capabilities the type is cpu, the attribute cpu_limit is relevant.

For virtual machines networks the type is network, the attributes inbound_average,
inbound_peak, inbound_burst, outbound_average, outbound_peak and
outbound_burst are relevant.

For host networks the type is hostnetwork, the attributes outbound_average_linkshare,

outbound_average_upperlimit and outbound_average_realtime are relevant.

Table 6.255. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

cpu_limit Integer The maximum processing capability in %.

description String A human-readable description in plain text.

id String A unique identifier.

inbound_aver Integer The desired average inbound bit rate in Mbps.

age

inbound_burs Integer The amount of data that can be delivered in a single burst in
t MiB.

inbound_peak Integer The maximum inbound rate in Mbps.

max_iops Integer Maximum permitted number of input and output operations per
second.

max_read_iop Integer Maximum permitted number of input operations per second.

s

588
 CHAPTER 6. TYPES

Name Type Summary

max_read_thr Integer Maximum permitted throughput for read operations.

oughput

max_throughp Integer Maximum permitted total throughput.

ut

max_write_io Integer Maximum permitted number of output operations per second.

ps

max_write_th Integer Maximum permitted throughput for write operations.

roughput

name String A human-readable name in plain text.

outbound_ave Integer The desired average outbound bit rate in Mbps.

rage

outbound_ave Integer Weighted share.

rage_linksha
re

outbound_ave Integer The committed rate in Mbps.

rage_realtim
e

outbound_ave Integer The maximum bandwidth to be used by a network in Mbps.

rage_upperli
mit

outbound_bur Integer The amount of data that can be sent in a single burst in MiB.
st

outbound_pea Integer The maximum outbound rate in Mbps.

k

589
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

type QosType The kind of resources this entry can be assigned.

6.195.1. cpu_limit

The maximum processing capability in %.

Used to configure computing resources.

6.195.2. inbound_average

The desired average inbound bit rate in Mbps.

Used to configure virtual machines networks. If defined, inbound_peak and inbound_burst also
has to be set.

See Libvirt-QOS for further details.

6.195.3. inbound_burst

The amount of data that can be delivered in a single burst in MiB.

Used to configure virtual machines networks. If defined, inbound_average and inbound_peak

also has to be set.

See Libvirt-QOS for further details.

6.195.4. inbound_peak

The maximum inbound rate in Mbps.

Used to configure virtual machines networks. If defined, inbound_average and inbound_burst

also has to be set.

See Libvirt-QOS for further details.

6.195.5. max_iops

Maximum permitted number of input and output operations per second.

Used to configure storage. Must not be set if max_read_iops or max_write_iops is set.

6.195.6. max_read_iops

Maximum permitted number of input operations per second.

Used to configure storage. Must not be set if max_iops is set.

6.195.7. max_read_throughput

590
 CHAPTER 6. TYPES

Maximum permitted throughput for read operations.

Used to configure storage. Must not be set if max_throughput is set.

6.195.8. max_throughput

Maximum permitted total throughput.

Used to configure storage. Must not be set if max_read_throughput or

max_write_throughput is set.

6.195.9. max_write_iops

Maximum permitted number of output operations per second.

Used to configure storage. Must not be set if max_iops is set.

6.195.10. max_write_throughput

Maximum permitted throughput for write operations.

Used to configure storage. Must not be set if max_throughput is set.

6.195.11. outbound_average

The desired average outbound bit rate in Mbps.

Used to configure virtual machines networks. If defined, outbound_peak and outbound_burst

also has to be set.

See Libvirt-QOS for further details.

6.195.12. outbound_average_linkshare

Weighted share.

Used to configure host networks. Signifies how much of the logical link’s capacity a specific network
should be allocated, relative to the other networks attached to the same logical link. The exact share
depends on the sum of shares of all networks on that link. By default this is a number in the range 1-
100.

6.195.13. outbound_average_realtime

The committed rate in Mbps.

Used to configure host networks. The minimum bandwidth required by a network. The committed
rate requested is not guaranteed and will vary depending on the network infrastructure and the
committed rate requested by other networks on the same logical link.

6.195.14. outbound_average_upperlimit

The maximum bandwidth to be used by a network in Mbps.

591
Red Hat Virtualization 4.0 REST API Guide

Used to configure host networks. If outboundAverageUpperlimit and

outbound_average_realtime are provided, the outbound_averageUpperlimit must not be
lower than the outbound_average_realtime.

See Libvirt-QOS for further details.

6.195.15. outbound_burst

The amount of data that can be sent in a single burst in MiB.

Used to configure virtual machines networks. If defined, outbound_average and

outbound_peak also has to be set.

See Libvirt-QOS for further details.

6.195.16. outbound_peak

The maximum outbound rate in Mbps.

Used to configure virtual machines networks. If defined, outbound_average and

outbound_burst also has to be set.

See Libvirt-QOS for further details.

Table 6.256. Links summary

Name Type Summary

data_center DataCenter The data center the QoS is assiciated to.

6.196. QOSTYPE ENUM

This type represents the kind of resource the Quality of service (QoS) can be assigned to.

Table 6.257. Values summary

Name Summary

cpu The Quality of service (QoS) can be assigned to resources with computing
capabilities.

hostnetwork The Quality of service (QoS) can be assigned to host networks.

network The Quality of service (QoS) can be assigned to virtual machines networks.

592
 CHAPTER 6. TYPES

Name Summary

storage The Quality of service (QoS) can be assigned to storage.

6.197. QUOTA STRUCT

Represents a quota object.

An example XML representation of a quota:

<quota href="/ovirt-engine/api/datacenters/7044934e/quotas/dcad5ddc"
id="dcad5ddc">
<name>My Quota</name>
<description>A quota for my oVirt environment</description>
<cluster_hard_limit_pct>0</cluster_hard_limit_pct>
<cluster_soft_limit_pct>0</cluster_soft_limit_pct>
<data_center href="/ovirt-engine/api/datacenters/7044934e"
id="7044934e"/>
<storage_hard_limit_pct>0</storage_hard_limit_pct>
<storage_soft_limit_pct>0</storage_soft_limit_pct>
</quota>

Table 6.258. Attributes summary

Name Type Summary

cluster_hard Integer
_limit_pct

cluster_soft Integer
_limit_pct

comment String Free text containing comments about this object.

data_center DataCenter

description String A human-readable description in plain text.

disks Disk[]

593
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

id String A unique identifier.

name String A human-readable name in plain text.

storage_hard Integer
_limit_pct

storage_soft Integer
_limit_pct

users User[]

vms Vm[]

Table 6.259. Links summary

Name Type Summary

permissions Permission[]

quota_cluste QuotaClusterLimit
r_limits []

quota_storag QuotaStorageLimi
e_limits t[]

6.198. QUOTACLUSTERLIMIT STRUCT

Table 6.260. Attributes summary

594
 CHAPTER 6. TYPES

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

memory_limit Decimal

memory_usage Decimal

name String A human-readable name in plain text.

vcpu_limit Integer

vcpu_usage Integer

Table 6.261. Links summary

Name Type Summary

cluster Cluster

quota Quota

6.199. QUOTAMODETYPE ENUM

Table 6.262. Values summary

Name Summary

audit

595
Red Hat Virtualization 4.0 REST API Guide

Name Summary

disabled

enabled

6.200. QUOTASTORAGELIMIT STRUCT

Table 6.263. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

limit Integer

name String A human-readable name in plain text.

usage Decimal

Table 6.264. Links summary

Name Type Summary

quota Quota

storage_doma StorageDomain
in

6.201. RANGE STRUCT

596
 CHAPTER 6. TYPES

6.201. RANGE STRUCT

Table 6.265. Attributes summary

Name Type Summary

from String

to String

6.202. RATE STRUCT

Determines maximum speed of consumption of bytes from random number generator device.

Table 6.266. Attributes summary

Name Type Summary

bytes Integer Number of bytes allowed to consume per period.

period Integer Duration of one period in milliseconds.

6.203. REPORTEDCONFIGURATION STRUCT

Table 6.267. Attributes summary

Name Type Summary

actual_value String

expected_val String
ue

in_sync Boolean false when the network attachment contains uncommitted

network configuration.

597
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

name String

6.204. REPORTEDDEVICE STRUCT

Table 6.268. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

ips Ip[]

mac Mac

name String A human-readable name in plain text.

type ReportedDeviceT
ype

Table 6.269. Links summary

Name Type Summary

vm Vm

6.205. REPORTEDDEVICETYPE ENUM

Table 6.270. Values summary

598
 CHAPTER 6. TYPES

Name Summary

network

6.206. RESOLUTIONTYPE ENUM

Table 6.271. Values summary

Name Summary

add

copy

6.207. RNGDEVICE STRUCT

Random number generator (RNG) device model.

Table 6.272. Attributes summary

Name Type Summary

rate Rate Determines maximum speed of consumption of bytes from

random number generator device.

source RngSource Backend of the random number generator device.

6.208. RNGSOURCE ENUM

Representing the random generator backend types.

Table 6.273. Values summary

Name Summary

599
Red Hat Virtualization 4.0 REST API Guide

Name Summary

hwrng Obtains random data from the /dev/hwrng (usually specialized HW generator)
device.

random Obtains random data from the /dev/random device.

6.209. ROLE STRUCT

Represents a system role.

Table 6.274. Attributes summary

Name Type Summary

administrati Boolean Defines the role as administrative-only or not.

ve

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

mutable Boolean Defines the ability to update or delete the role.

name String A human-readable name in plain text.

6.209.1. mutable

Defines the ability to update or delete the role.

Roles with mutable set to false are predefined roles.

Table 6.275. Links summary

600
 CHAPTER 6. TYPES

Name Type Summary

permits Permit[] A link to the permits sub-collection for role permits.

user User

6.210. ROLETYPE ENUM

Type representing whether a role is administrative or not. A user which was granted at least one
administrative role is considered an administrator.

Table 6.276. Values summary

Name Summary

admin Administrative role.

user User role.

6.211. SCHEDULINGPOLICY STRUCT

Table 6.277. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

default_poli Boolean
cy

description String A human-readable description in plain text.

id String A unique identifier.

locked Boolean

601
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

name String A human-readable name in plain text.

properties Property[]

Table 6.278. Links summary

Name Type Summary

balances Balance[]

filters Filter[]

weight Weight[]

6.212. SCHEDULINGPOLICYUNIT STRUCT

Table 6.279. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

enabled Boolean

id String A unique identifier.

internal Boolean

name String A human-readable name in plain text.

602
 CHAPTER 6. TYPES

Name Type Summary

properties Property[]

type PolicyUnitType

6.213. SCSIGENERICIO ENUM

Table 6.280. Values summary

Name Summary

filtered

unfiltered

6.214. SELINUX STRUCT

Table 6.281. Attributes summary

Name Type Summary

mode SeLinuxMode

6.215. SELINUXMODE ENUM

Table 6.282. Values summary

Name Summary

disabled

enforcing

603
Red Hat Virtualization 4.0 REST API Guide

Name Summary

permissive

6.216. SERIALNUMBER STRUCT

Table 6.283. Attributes summary

Name Type Summary

policy SerialNumberPoli
cy

value String

6.217. SERIALNUMBERPOLICY ENUM

Table 6.284. Values summary

Name Summary

custom

host

vm

6.218. SESSION STRUCT

Describes user session to a virtual machine.

Table 6.285. Attributes summary

604
 CHAPTER 6. TYPES

Name Type Summary

comment String Free text containing comments about this object.

console_user Boolean Indicates if this is a console session.

description String A human-readable description in plain text.

id String A unique identifier.

ip Ip IP address user is connected from.

name String A human-readable name in plain text.

protocol String Protocol used by the session.

6.218.1. console_user

Indicates if this is a console session.

The value will be true for console users: SPICE or VNC, false for others: e.g. RDP, SSH.

6.218.2. ip

IP address user is connected from.

Currently only available for console users.

6.218.3. protocol

Protocol used by the session.

Currently not used, intended for info about how is user connected: SPICE, VNC, SSH, RDP.

Table 6.286. Links summary

Name Type Summary

user User User related to this session.

605
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

vm Vm Link to virtual machine related to this session.

6.218.4. user

User related to this session.

If user is a console user, it is a link to real oVirt user. Otherwise only username is provided.

6.219. SKIPIFCONNECTIVITYBROKEN STRUCT

Table 6.287. Attributes summary

Name Type Summary

enabled Boolean If enabled, we will not fence a host in case more than a
configurable percentage of hosts in the cluster lost
connectivity as well.

threshold Integer Threshold for connectivity testing.

6.219.1. enabled

If enabled, we will not fence a host in case more than a configurable percentage of hosts in the
cluster lost connectivity as well. This comes to prevent fencing storm in cases where there is a
global networking issue in the cluster.

6.219.2. threshold

Threshold for connectivity testing. If at least the threshold percentage of hosts in the cluster lost
connectivity then fencing will not take place.

6.220. SKIPIFSDACTIVE STRUCT

This type represents the storage related configuration in the fencing policy.

Table 6.288. Attributes summary

606
 CHAPTER 6. TYPES

Name Type Summary

enabled Boolean If enabled, we will skip fencing in case the host maintains its
lease in the storage.

6.220.1. enabled

If enabled, we will skip fencing in case the host maintains its lease in the storage. It means that if the
host still has storage access then it won’t get fenced.

6.221. SNAPSHOT STRUCT

Represents a snapshot object.

<snapshot id="456" href="/ovirt-engine/api/vms/123/snapshots/456">

<actions>
<link rel="restore" href="/ovirt-
engine/api/vms/123/snapshots/456/restore"/>
</actions>
<vm id="123" href="/ovirt-engine/api/vms/123"/>
<description>Virtual Machine 1 - Snapshot A</description>
<type>active</type>
<date>2010-08-16T14:24:29</date>
<persist_memorystate>false</persist_memorystate>
</snapshot>

Table 6.289. Attributes summary

Name Type Summary

bios Bios Reference to virtual machine’s BIOS configuration.

comment String Free text containing comments about this object.

console Console Console configured for this virtual machine.

cpu Cpu The configuration of the virtual machine CPU.

cpu_shares Integer

607
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

creation_tim Date The virtual machine creation date.

e

custom_compa Version Virtual machine custom compatibility version.

tibility_ver
sion

custom_cpu_m String
odel

custom_emula String
ted_machine

custom_prope CustomProperty[] Properties sent to VDSM to configure various hooks.

rties

date Date

delete_prote Boolean If true, the virtual machine cannot be deleted.

cted

description String A human-readable description in plain text.

display Display The virtual machine display configuration.

domain Domain Domain configured for this virtual machine.

fqdn String Fully qualified domain name of the virtual machine.

guest_operat GuestOperatingS What operating system is installed on the virtual machine.

ing_system ystem

608
 CHAPTER 6. TYPES

Name Type Summary

guest_time_z TimeZone What time zone is used by the virtual machine (as returned by
one guest agent).

high_availab HighAvailability The virtual machine high availability configuration.

ility

id String A unique identifier.

initializati Initialization Reference to virtual machine’s initialization configuration.

on

io Io For performance tuning of IO threading.

large_icon Icon Virtual machine’s large icon.

memory Integer The virtual machine’s memory, in bytes.

memory_polic MemoryPolicy Reference to virtual machine’s memory management

y configuration.

migration MigrationOptions Reference to configuration of migration of running virtual

machine to another host.

migration_do Integer Maximum time the virtual machine can be non responsive
wntime during its live migration to another host in ms.

name String A human-readable name in plain text.

next_run_con Boolean Virtual machine configuration has been changed and requires
figuration_e restart of the virtual machine.
xists

numa_tune_mo NumaTuneMode How the NUMA topology is applied.

de

609
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

origin String The origin of this virtual machine.

os OperatingSystem Operating system type installed on the virtual machine.

payloads Payload[] Optional payloads of the virtual machine, used for ISOs to
configure it.

persist_memo Boolean
rystate

placement_po VmPlacementPoli The configuration of the virtual machine’s placement policy.

licy cy

rng_device RngDevice Random Number Generator device configuration for this

virtual machine.

run_once Boolean If true, the virtual machine has been started using the run
once command, meaning it’s configuration might differ from
the stored one for the purpose of this single run.

serial_numbe SerialNumber Virtual machine’s serial number in a cluster.

r

small_icon Icon Virtual machine’s small icon.

snapshot_sta SnapshotStatus
tus

snapshot_typ SnapshotType
e

610
 CHAPTER 6. TYPES

Name Type Summary

soundcard_en Boolean If true, the sound card is added to the virtual machine.
abled

sso Sso Reference to the Single Sign On configuration this virtual

machine is configured for.

start_paused Boolean If true, the virtual machine will be initially in 'paused' state
after start.

start_time Date The date in which the virtual machine was started.

stateless Boolean If true, the virtual machine is stateless - it’s state (disks) are
rolled-back after shutdown.

status VmStatus The current status of the virtual machine.

status_detai String Human readable detail of current status.

l

stop_reason String The reason the virtual machine was stopped.

stop_time Date The date in which the virtual machine was stopped.

time_zone TimeZone The virtual machine’s time zone set by oVirt.

tunnel_migra Boolean If true, the network data transfer will be encrypted during
tion virtual machine live migration.

type VmType Determines whether the virtual machine is optimized for

desktop or server.

611
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

usb Usb Configuration of USB devices for this virtual machine (count,
type).

use_latest_t Boolean If true, the virtual machine is reconfigured to the latest

emplate_vers version of it’s template when it is started.
ion

virtio_scsi VirtioScsi Reference to VirtIO SCSI configuration.

6.221.1. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the
threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and
threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>

6.221.2. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If

custom_compatibility_version is set, it overrides the cluster’s compatibility version for this
particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine
resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

6.221.3. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically

612
 CHAPTER 6. TYPES

restarted when it unexpectedly goes down.

6.221.4. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

6.221.5. memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following
request:

PUT /ovirt-engine/api/vms/123

With the following request body:

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

Note

Memory in the example is converted to bytes using the following formula:

1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the
example above to increase memory while the virtual machine is running.

6.221.6. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in
ms.

Set either explicitly for the virtual machine or by engine-config -s

DefaultMaximumMigrationDowntime=[value]

6.221.7. next_run_configuration_exists

Virtual machine configuration has been changed and requires restart of the virtual machine.
Changed configuration is applied at processing the virtual machine’s shut down.

6.221.8. origin

The origin of this virtual machine.

Possible values:

613
Red Hat Virtualization 4.0 REST API Guide

ovirt

rhev

vmware

xen

external

hosted_engine

managed_hosted_engine

kvm

physical_machine

hyperv

6.221.9. placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event
of a host failure, any virtual machine configured to be highly available is automatically
restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
<high_availability>
<enabled>true</enabled>
<priority>1</priority>
</high_availability>
<placement_policy>
<hosts>
<host>
<name>Host1</name>
</host>
<host>
<name>Host2</name>
</host>
</hosts>
<affinity>pinned</affinity>
</placement_policy>
</vm>

614
 CHAPTER 6. TYPES

6.221.10. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating
system.

6.221.11. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be
automatically signed in the virtual machine’s operating system when console is opened.

6.221.12. stop_reason

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual
machine.

Table 6.290. Links summary

Name Type Summary

affinity_lab AffinityLabel[] Optional.

els

applications Application[] List of applications installed on the virtual machine.

cdroms Cdrom[] Reference to the ISO mounted to the CDROM.

cluster Cluster Reference to cluster the virtual machine belongs to.

cpu_profile CpuProfile Reference to CPU profile used by this virtual machine.

disk_attachm DiskAttachment[] References the disks attached to the virtual machine.

ents

external_hos ExternalHostProvi
t_provider der

floppies Floppy[] Reference to the ISO mounted to the floppy.

615
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

graphics_con GraphicsConsole[ List of graphics consoles configured for this virtual machine.
soles ]

host Host Reference to the host the virtual machine is running on.

host_devices HostDevice[] References devices associated to this virtual machine.

instance_typ InstanceType The virtual machine configuration can be optionally predefined

e via one of the instance types.

katello_erra KatelloErratum[] Lists all the Katello errata assigned to the virtual machine.
ta

nics Nic[] References the list of network interface devices on the virtual
machine.

numa_nodes NumaNode[] Refers to the NUMA Nodes configuration used by this virtual
machine.

permissions Permission[] Permissions set for this virtual machine.

quota Quota Reference to quota configuration set for this virtual machine.

reported_dev ReportedDevice[]
ices

sessions Session[] List of user sessions opened for this virtual machine.

snapshots Snapshot[] Refers to all snapshots taken from the virtual machine.

statistics Statistic[] Statistics data collected from this virtual machine.

616
 CHAPTER 6. TYPES

Name Type Summary

storage_doma StorageDomain Reference to storage domain the virtual machine belongs to.
in

tags Tag[]

template Template Reference to the template the virtual machine is based on.

vm Vm

vm_pool VmPool Reference to the pool the virtual machine is optionally

member of.

watchdogs Watchdog[] Refers to the Watchdog configuration.

6.221.13. affinity_labels

Optional. Used for labeling of sub-clusters.

6.221.14. katello_errata

Lists all the Katello errata assigned to the virtual machine.

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

You will receive response in XML like this one:

<katello_errata>
<katello_erratum href="/ovirt-engine/api/katelloerrata/456" id="456">
<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for
XYZ</summary>
<packages>
<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...

617
Red Hat Virtualization 4.0 REST API Guide

</packages>
</katello_erratum>
...
</katello_errata>

6.222. SNAPSHOTSTATUS ENUM

Table 6.291. Values summary

Name Summary

in_preview

locked

ok

6.223. SNAPSHOTTYPE ENUM

Table 6.292. Values summary

Name Summary

active

preview

regular

stateless

6.224. SPECIALOBJECTS STRUCT

This type contains references to special objects, like the blank template and the root of the hierarchy
of tags.

Table 6.293. Links summary

618
 CHAPTER 6. TYPES

Name Type Summary

blank_templa Template Reference to the blank template.

te

root_tag Tag Reference to the root of the hierarchy of tags.

6.225. SPM STRUCT

Table 6.294. Attributes summary

Name Type Summary

priority Integer

status SpmStatus

6.226. SPMSTATUS ENUM

Table 6.295. Values summary

Name Summary

contending

none

spm

6.227. SSH STRUCT

Table 6.296. Attributes summary

619
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

authenticati SshAuthentication
on_method Method

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

fingerprint String

id String A unique identifier.

name String A human-readable name in plain text.

port Integer

user User

6.228. SSHAUTHENTICATIONMETHOD ENUM

Table 6.297. Values summary

Name Summary

password

publickey

6.229. SSHPUBLICKEY STRUCT

Table 6.298. Attributes summary

620
 CHAPTER 6. TYPES

Name Type Summary

comment String Free text containing comments about this object.

content String

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.299. Links summary

Name Type Summary

user User

6.230. SSO STRUCT

Table 6.300. Attributes summary

Name Type Summary

methods Method[]

6.231. SSOMETHOD ENUM

Table 6.301. Values summary

Name Summary

guest_agent

621
Red Hat Virtualization 4.0 REST API Guide

6.232. STATISTIC STRUCT

A generic type used for all kinds of statistics.

Statistic contains the statistics values for various entities. The following object contain statistics:

Disk

Host

HostNic

NumaNode

Nic

Vm

GlusterBrick

Step

GlusterVolume

An example of a XML representation:

<statistics>
<statistic id="1234" href="/ovirt-
engine/api/hosts/1234/nics/1234/statistics/1234">
<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="1234" href="/ovirt-engine/api/hosts/1234/nics/1234"/>
</statistic>
...
</statistics>

Note

This statistics sub-collection is read-only.

Table 6.302. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

622
 CHAPTER 6. TYPES

Name Type Summary

description String A human-readable description in plain text.

id String A unique identifier.

kind StatisticKind The type of statistic measures.

name String A human-readable name in plain text.

type ValueType The data type for the statistical values that follow.

unit StatisticUnit The unit or rate to measure of the statistical values.

values Value[] A data set that contains datum.

Table 6.303. Links summary

Name Type Summary

brick GlusterBrick

disk Disk A relationship to the containing disk resource.

gluster_volu GlusterVolume
me

host Host

host_nic HostNic A reference to the host NIC.

host_numa_no NumaNode
de

623
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

nic Nic

step Step

vm Vm

6.233. STATISTICKIND ENUM

Table 6.304. Values summary

Name Summary

counter

gauge

6.234. STATISTICUNIT ENUM

Table 6.305. Values summary

Name Summary

bits_per_sec
ond

bytes

bytes_per_se
cond

count_per_se
cond

624
 CHAPTER 6. TYPES

Name Summary

none

percent

seconds

6.235. STEP STRUCT

Represents a step, which is part of job execution. Step is used to describe and track a specific
execution unit which is part of a wider sequence. Some steps support reporting their progress.

Table 6.306. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

end_time Date The end time of the step.

external Boolean Indicates if the step is originated by an external system.

external_typ ExternalSystemTy The external system which is referenced by the step.

e pe

id String A unique identifier.

name String A human-readable name in plain text.

number Integer The order of the step in current hierarchy level.

625
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

start_time Date The start time of the step.

status StepStatus The status of the step.

type StepEnum The type of the step.

6.235.1. external

Indicates if the step is originated by an external system. External steps are managed externally, by
the creator of the step.

Table 6.307. Links summary

Name Type Summary

job Job References the job which is the top of the current step
hierarchy.

parent_step Step References the parent step of the current step in the
hierarchy.

statistics Statistic[]

6.236. STEPENUM ENUM

Type representing a step type.

Table 6.308. Values summary

Name Summary

executing The executing step type.

finalizing The finalizing step type.

626
 CHAPTER 6. TYPES

Name Summary

rebalancing_ The rebalancing volume step type.

volume

removing_bri The removing bricks step type.

cks

unknown The unknown step type.

validating The validation step type.

6.236.1. executing

The executing step type. Used to track the main execution block of the job. Usually it will be a parent
step of several sub-steps which describe portions of the execution step.

6.236.2. finalizing

The finalizing step type. Describes the post-execution steps requires to complete the job.

6.236.3. rebalancing_volume

The rebalancing volume step type. Describes a step type which is part of Gluster flow.

6.236.4. removing_bricks

The removing bricks step type. Describes a step type which is part of Gluster flow.

6.236.5. unknown

The unknown step type. Describes a step type which its origin is unknown.

6.236.6. validating

The validation step type. Used to verify the correctness of parameters and the validity of the
parameters prior to the execution.

6.237. STEPSTATUS ENUM

Represents the status of the step.

Table 6.309. Values summary

627
Red Hat Virtualization 4.0 REST API Guide

Name Summary

aborted The aborted step status.

failed The failed step status.

finished The finished step status.

started The started step status.

unknown The unknown step status.

6.237.1. aborted

The aborted step status. This status is applicable for an external step that was forcibly aborted.

6.237.2. finished

The finished step status. This status describes a completed step execution.

6.237.3. started

The started step status. This status represents a step which is currently being executed.

6.237.4. unknown

The unknown step status. This status represents steps which their resolution is not known, i.e. steps
that were executed before the system was unexpectedly restarted.

6.238. STORAGECONNECTION STRUCT

Represents a storage server connection.

Example:

<storage_connection id="123">
<address>mynfs.example.com</address>
<type>nfs</type>
<path>/exports/mydata</path>
</storage_connection>

Table 6.310. Attributes summary

628
 CHAPTER 6. TYPES

Name Type Summary

address String

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

mount_option String
s

name String A human-readable name in plain text.

nfs_retrans Integer

nfs_timeo Integer

nfs_version NfsVersion

password String

path String

port Integer

portal String

target String

type StorageType

629
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

username String

vfs_type String

Table 6.311. Links summary

Name Type Summary

host Host

6.239. STORAGECONNECTIONEXTENSION STRUCT

Table 6.312. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

password String

target String

username String

Table 6.313. Links summary

630
 CHAPTER 6. TYPES

Name Type Summary

host Host

6.240. STORAGEDOMAIN STRUCT

Storage domain.

An XML representation of a NFS storage domain with identifier 123:

<storage_domain href="/ovirt-engine/api/storagedomains/123" id="123">

<name>mydata</name>
<description>My data</description>
<available>38654705664</available>
<committed>1073741824</committed>
<critical_space_action_blocker>5</critical_space_action_blocker>
<external_status>ok</external_status>
<master>true</master>
<storage>
<address>mynfs.example.com</address>
<nfs_version>v3</nfs_version>
<path>/exports/mydata</path>
<type>nfs</type>
</storage>
<storage_format>v3</storage_format>
<type>data</type>
<used>13958643712</used>
<warning_low_space_indicator>10</warning_low_space_indicator>
<wipe_after_delete>false</wipe_after_delete>
<data_centers>
<data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
</data_centers>
</storage_domain>

Table 6.314. Attributes summary

Name Type Summary

available Integer

comment String Free text containing comments about this object.

committed Integer

631
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

critical_spa Integer
ce_action_bl
ocker

description String A human-readable description in plain text.

external_sta ExternalStatus
tus

id String A unique identifier.

import Boolean

master Boolean

name String A human-readable name in plain text.

status StorageDomainSt
atus

storage HostStorage

storage_form StorageFormat
at

type StorageDomainTy
pe

used Integer

632
 CHAPTER 6. TYPES

Name Type Summary

warning_low_ Integer
space_indica
tor

wipe_after_d Boolean Serves as the default value of wipe_after_delete for

elete disks on this storage domain.

6.240.1. wipe_after_delete

Serves as the default value of wipe_after_delete for disks on this storage domain.

That is, newly created disks will get their wipe_after_delete value from their storage domains
by default. Note that the configuration value SANWipeAfterDelete serves as the default value of
block storage domains' wipe_after_delete value.

Table 6.315. Links summary

Name Type Summary

data_center DataCenter This is used to link to the data center that the storage domain
is attached to.

data_centers DataCenter[] This is a set of links to the data centers that the storage
domain is attached to.

disk_profile DiskProfile[]
s

disk_snapsho DiskSnapshot[]
ts

disks Disk[]

files File[]

host Host Host is only relevant at creation time.

633
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

images Image[]

permissions Permission[]

storage_conn StorageConnectio
ections n[]

templates Template[]

vms Vm[]

6.240.2. data_center

This is used to link to the data center that the storage domain is attached to. It is preserved for
backwards compatibility, as the storage domain may be attached to multiple data centers (if it is an
ISO domain). Use the dataCenters element instead.

6.241. STORAGEDOMAINSTATUS ENUM

Table 6.316. Values summary

Name Summary

activating

active

detaching

inactive

locked

634
 CHAPTER 6. TYPES

Name Summary

maintenance

mixed

preparing_fo
r_maintenanc
e

unattached

unknown

6.242. STORAGEDOMAINTYPE ENUM

Table 6.317. Values summary

Name Summary

data

export

image

iso

volume

6.243. STORAGEFORMAT ENUM

Table 6.318. Values summary

635
Red Hat Virtualization 4.0 REST API Guide

Name Summary

v1

v2

v3

6.244. STORAGETYPE ENUM

Type representing a storage domain type.

Table 6.319. Values summary

Name Summary

cinder Cinder storage domain.

fcp Fibre-Channel storage domain.

glance Glance storage domain.

glusterfs Gluster-FS storage domain.

iscsi iSCSI storage domain.

localfs Storage domain on Local storage.

nfs NFS storage domain.

posixfs POSIX-FS storage domain.

6.244.1. cinder

636
 CHAPTER 6. TYPES

Cinder storage domain. For more details on Cinder please go to Cinder.

6.244.2. glance

Glance storage domain. For more details on Glance please go to Glance.

6.244.3. glusterfs

Gluster-FS storage domain. For more details on Gluster please go to Gluster.

6.245. SWITCHTYPE ENUM

Describes all switch types supported by the Manager.

Table 6.320. Values summary

Name Summary

legacy The native switch type.

ovs The Open vSwitch type.

6.246. TAG STRUCT

Represents a tag in the system.

Table 6.321. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.322. Links summary

637
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

group Group Reference to the group which has this tag assigned.

host Host Reference to the host which has this tag assigned.

parent Tag Reference to the parent tag of this tag.

template Template Reference to the template which has this tag assigned.

user User Reference to the user who has this tag assigned.

vm Vm Reference to the virtual machine which has this tag assigned.

6.247. TEMPLATE STRUCT

Type representing a virtual machine template. This allows a rapid instanstiation of virtual machines
with common configuration and disk states.

Table 6.323. Attributes summary

Name Type Summary

bios Bios Reference to virtual machine’s BIOS configuration.

comment String Free text containing comments about this object.

console Console Console configured for this virtual machine.

cpu Cpu The configuration of the virtual machine CPU.

cpu_shares Integer

638
 CHAPTER 6. TYPES

Name Type Summary

creation_tim Date The virtual machine creation date.

e

custom_compa Version Virtual machine custom compatibility version.

tibility_ver
sion

custom_cpu_m String
odel

custom_emula String
ted_machine

custom_prope CustomProperty[] Properties sent to VDSM to configure various hooks.

rties

delete_prote Boolean If true, the virtual machine cannot be deleted.

cted

description String A human-readable description in plain text.

display Display The virtual machine display configuration.

domain Domain Domain configured for this virtual machine.

high_availab HighAvailability The virtual machine high availability configuration.

ility

id String A unique identifier.

initializati Initialization Reference to virtual machine’s initialization configuration.

on

io Io For performance tuning of IO threading.

639
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

large_icon Icon Virtual machine’s large icon.

memory Integer The virtual machine’s memory, in bytes.

memory_polic MemoryPolicy Reference to virtual machine’s memory management

y configuration.

migration MigrationOptions Reference to configuration of migration of running virtual

machine to another host.

migration_do Integer Maximum time the virtual machine can be non responsive
wntime during its live migration to another host in ms.

name String A human-readable name in plain text.

origin String The origin of this virtual machine.

os OperatingSystem Operating system type installed on the virtual machine.

rng_device RngDevice Random Number Generator device configuration for this

virtual machine.

serial_numbe SerialNumber Virtual machine’s serial number in a cluster.

r

small_icon Icon Virtual machine’s small icon.

soundcard_en Boolean If true, the sound card is added to the virtual machine.
abled

640
 CHAPTER 6. TYPES

Name Type Summary

sso Sso Reference to the Single Sign On configuration this virtual

machine is configured for.

start_paused Boolean If true, the virtual machine will be initially in 'paused' state
after start.

stateless Boolean If true, the virtual machine is stateless - it’s state (disks) are
rolled-back after shutdown.

status TemplateStatus The status of the template.

time_zone TimeZone The virtual machine’s time zone set by oVirt.

tunnel_migra Boolean If true, the network data transfer will be encrypted during
tion virtual machine live migration.

type VmType Determines whether the virtual machine is optimized for

desktop or server.

usb Usb Configuration of USB devices for this virtual machine (count,
type).

version TemplateVersion Indicates whether this is a base version or a sub version of

another template.

virtio_scsi VirtioScsi Reference to VirtIO SCSI configuration.

vm Vm The virtual machine configuration associated with this

template.

6.247.1. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the
threads require a reboot.

641
Red Hat Virtualization 4.0 REST API Guide

For example, to change the number of sockets to 4 immediately, and the number of cores and
threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>

6.247.2. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If

custom_compatibility_version is set, it overrides the cluster’s compatibility version for this
particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine
resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

6.247.3. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically
restarted when it unexpectedly goes down.

6.247.4. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

6.247.5. memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following
request:

PUT /ovirt-engine/api/vms/123

With the following request body:

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

642
 CHAPTER 6. TYPES

Note

Memory in the example is converted to bytes using the following formula:

1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the
example above to increase memory while the virtual machine is running.

6.247.6. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in
ms.

Set either explicitly for the virtual machine or by engine-config -s

DefaultMaximumMigrationDowntime=[value]

6.247.7. origin

The origin of this virtual machine.

Possible values:

ovirt

rhev

vmware

xen

external

hosted_engine

managed_hosted_engine

kvm

physical_machine

hyperv

6.247.8. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating
system.

6.247.9. sso

643
Red Hat Virtualization 4.0 REST API Guide

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be
automatically signed in the virtual machine’s operating system when console is opened.

Table 6.324. Links summary

Name Type Summary

cdroms Cdrom[] References to the CD-ROM devices attached to the template.

cluster Cluster Reference to cluster the virtual machine belongs to.

cpu_profile CpuProfile Reference to CPU profile used by this virtual machine.

disk_attachm DiskAttachment[] References to the disks attached to the template.

ents

graphics_con GraphicsConsole[ References to the graphic consoles attached to the template.

soles ]

nics Nic[] References to the network interfaces attached to the

template.

permissions Permission[] References to the user permissions attached to the template.

quota Quota Reference to quota configuration set for this virtual machine.

storage_doma StorageDomain Reference to storage domain the virtual machine belongs to.
in

tags Tag[] References to the tags attached to the template.

watchdogs Watchdog[] References to the watchdog devices attached to the template.

6.248. TEMPLATESTATUS ENUM

Type representing a status of a virtual machine template.

644
 CHAPTER 6. TYPES

Table 6.325. Values summary

Name Summary

illegal This status indicates that at least one of the disks of the template is illegal.

locked This status indicates that some operation that prevents other operations with the
template is being executed.

ok This status indicates that the template is valid and ready for use.

6.249. TEMPLATEVERSION STRUCT

Type representing a version of a virtual machine template.

Table 6.326. Attributes summary

Name Type Summary

version_name String The name of this version.

version_numb Integer The index of this version in the versions hierarchy of the
er template.

6.249.1. version_number

The index of this version in the versions hierarchy of the template. The index 1 represents the
original version of a template that is also called base version.

Table 6.327. Links summary

Name Type Summary

base_templat Template References the template that this version is associated with.
e

6.250. TICKET STRUCT

645
Red Hat Virtualization 4.0 REST API Guide

Type representing a ticket that allows virtual machine access.

Table 6.328. Attributes summary

Name Type Summary

expiry Integer Time to live for the ticket in seconds.

value String The virtual machine access ticket.

6.251. TIMEZONE STRUCT

Time zone representation.

Table 6.329. Attributes summary

Name Type Summary

name String Name of the time zone.

utc_offset String Offset from https://en.

6.251.1. utc_offset

Offset from UTC.

6.252. TRANSPARENTHUGEPAGES STRUCT

Type representing a transparent huge pages (THP) support.

Table 6.330. Attributes summary

Name Type Summary

enabled Boolean Enable THP support.

6.253. TRANSPORTTYPE ENUM

646
 CHAPTER 6. TYPES

Protocol used to access a Gluster volume.

Table 6.331. Values summary

Name Summary

rdma Remote direct memory access.

tcp TCP.

6.254. UNMANAGEDNETWORK STRUCT

Table 6.332. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.333. Links summary

Name Type Summary

host Host

host_nic HostNic

6.255. USB STRUCT

Table 6.334. Attributes summary

647
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

enabled Boolean

type UsbType

6.256. USBTYPE ENUM

Table 6.335. Values summary

Name Summary

legacy

native

6.257. USER STRUCT

Represents a user in the system.

Table 6.336. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

department String

description String A human-readable description in plain text.

domain_entry String
_id

email String

648
 CHAPTER 6. TYPES

Name Type Summary

id String A unique identifier.

last_name String

logged_in Boolean

name String A human-readable name in plain text.

namespace String Namespace where user resides.

password String

principal String Same as user_name principal has different formats based

on LDAP provider.

user_name String Username of the user.

6.257.1. namespace

Namespace where user resides. When using the authorization provider that stores users in the
LDAP (see here for details) this attribute equals to naming context of the LDAP. When using the
built-in authorization provider that stores users in the database (see here for details) this attribute is
ignored.

6.257.2. principal

Same as user_name principal has different formats based on LDAP provider. In case of most
LDAP providers it is value of the uid LDAP attribute. In case of Active Directory it is the user
principal name (UPN).

6.257.3. user_name

Username of the user. The format depends on authorization provider type. In case of most LDAP
providers it is value of the uid LDAP attribute. In case of Active Directory it is the user principal
name (UPN). UPN or uid must be followed by authorization provider name. For example in case of
LDAP using uid attribute it is: myuser@myextension-authz. In case of Active Directory using
UPN it is: myuser@mysubdomain.mydomain.com@myextension-authz. This attribute is
required parameter when adding new user.

649
Red Hat Virtualization 4.0 REST API Guide

Table 6.337. Links summary

Name Type Summary

domain Domain

groups Group[]

permissions Permission[]

roles Role[] A link to the roles sub-collection for user resources.

ssh_public_k SshPublicKey[]
eys

tags Tag[] A link to the tags sub-collection for user resources.

6.258. VALUE STRUCT

Table 6.338. Attributes summary

Name Type Summary

datum Decimal

detail String

6.259. VALUETYPE ENUM

Table 6.339. Values summary

Name Summary

decimal

650
 CHAPTER 6. TYPES

Name Summary

integer

string

6.260. VCPUPIN STRUCT

Table 6.340. Attributes summary

Name Type Summary

cpu_set String

vcpu Integer

6.261. VENDOR STRUCT

Table 6.341. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

6.262. VERSION STRUCT

Table 6.342. Attributes summary

651
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

build Integer

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

full_version String

id String A unique identifier.

major Integer

minor Integer

name String A human-readable name in plain text.

revision Integer

6.263. VIRTIOSCSI STRUCT

Type representing the support of virtio-SCSI. If it supported we use virtio driver for SCSI guest
device.

Table 6.343. Attributes summary

Name Type Summary

enabled Boolean Enable Virtio SCSI support.

6.264. VIRTUALNUMANODE STRUCT

Represents the virtual NUMA node.

An example XML representation:

652
 CHAPTER 6. TYPES

<vm_numa_node href="/ovirt-engine/api/vms/123/numanodes/456" id="456">

<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>1024</memory>
<numa_node_pins>
<numa_node_pin>
<index>0</index>
</numa_node_pin>
</numa_node_pins>
<vm href="/ovirt-engine/api/vms/123" id="123" />
</vm_numa_node>

Table 6.344. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

cpu Cpu

description String A human-readable description in plain text.

id String A unique identifier.

index Integer

memory Integer Memory of the NUMA node in MB.

name String A human-readable name in plain text.

node_distanc String
e

653
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

numa_node_pi NumaNodePin[]
ns

Table 6.345. Links summary

Name Type Summary

host Host

statistics Statistic[]

vm Vm

6.265. VLAN STRUCT

Type representing a Virtual LAN (VLAN) type.

Table 6.346. Attributes summary

Name Type Summary

id Integer Virtual LAN ID.

6.266. VM STRUCT
Represents a virtual machine.

Table 6.347. Attributes summary

Name Type Summary

bios Bios Reference to virtual machine’s BIOS configuration.

654
 CHAPTER 6. TYPES

Name Type Summary

comment String Free text containing comments about this object.

console Console Console configured for this virtual machine.

cpu Cpu The configuration of the virtual machine CPU.

cpu_shares Integer

creation_tim Date The virtual machine creation date.

e

custom_compa Version Virtual machine custom compatibility version.

tibility_ver
sion

custom_cpu_m String
odel

custom_emula String
ted_machine

custom_prope CustomProperty[] Properties sent to VDSM to configure various hooks.

rties

delete_prote Boolean If true, the virtual machine cannot be deleted.

cted

description String A human-readable description in plain text.

display Display The virtual machine display configuration.

domain Domain Domain configured for this virtual machine.

655
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

fqdn String Fully qualified domain name of the virtual machine.

guest_operat GuestOperatingS What operating system is installed on the virtual machine.

ing_system ystem

guest_time_z TimeZone What time zone is used by the virtual machine (as returned by
one guest agent).

high_availab HighAvailability The virtual machine high availability configuration.

ility

id String A unique identifier.

initializati Initialization Reference to virtual machine’s initialization configuration.

on

io Io For performance tuning of IO threading.

large_icon Icon Virtual machine’s large icon.

memory Integer The virtual machine’s memory, in bytes.

memory_polic MemoryPolicy Reference to virtual machine’s memory management

y configuration.

migration MigrationOptions Reference to configuration of migration of running virtual

machine to another host.

migration_do Integer Maximum time the virtual machine can be non responsive
wntime during its live migration to another host in ms.

name String A human-readable name in plain text.

656
 CHAPTER 6. TYPES

Name Type Summary

next_run_con Boolean Virtual machine configuration has been changed and requires
figuration_e restart of the virtual machine.
xists

numa_tune_mo NumaTuneMode How the NUMA topology is applied.

de

origin String The origin of this virtual machine.

os OperatingSystem Operating system type installed on the virtual machine.

payloads Payload[] Optional payloads of the virtual machine, used for ISOs to
configure it.

placement_po VmPlacementPoli The configuration of the virtual machine’s placement policy.

licy cy

rng_device RngDevice Random Number Generator device configuration for this

virtual machine.

run_once Boolean If true, the virtual machine has been started using the run
once command, meaning it’s configuration might differ from
the stored one for the purpose of this single run.

serial_numbe SerialNumber Virtual machine’s serial number in a cluster.

r

small_icon Icon Virtual machine’s small icon.

soundcard_en Boolean If true, the sound card is added to the virtual machine.
abled

sso Sso Reference to the Single Sign On configuration this virtual

machine is configured for.

657
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

start_paused Boolean If true, the virtual machine will be initially in 'paused' state
after start.

start_time Date The date in which the virtual machine was started.

stateless Boolean If true, the virtual machine is stateless - it’s state (disks) are
rolled-back after shutdown.

status VmStatus The current status of the virtual machine.

status_detai String Human readable detail of current status.

l

stop_reason String The reason the virtual machine was stopped.

stop_time Date The date in which the virtual machine was stopped.

time_zone TimeZone The virtual machine’s time zone set by oVirt.

tunnel_migra Boolean If true, the network data transfer will be encrypted during
tion virtual machine live migration.

type VmType Determines whether the virtual machine is optimized for

desktop or server.

usb Usb Configuration of USB devices for this virtual machine (count,
type).

use_latest_t Boolean If true, the virtual machine is reconfigured to the latest

emplate_vers version of it’s template when it is started.
ion

virtio_scsi VirtioScsi Reference to VirtIO SCSI configuration.

658
 CHAPTER 6. TYPES

6.266.1. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the
threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and
threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>

6.266.2. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If

custom_compatibility_version is set, it overrides the cluster’s compatibility version for this
particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine
resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

6.266.3. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically
restarted when it unexpectedly goes down.

6.266.4. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

6.266.5. memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following
request:

PUT /ovirt-engine/api/vms/123

With the following request body:

659
Red Hat Virtualization 4.0 REST API Guide

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

Note

Memory in the example is converted to bytes using the following formula:

1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the
example above to increase memory while the virtual machine is running.

6.266.6. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in
ms.

Set either explicitly for the virtual machine or by engine-config -s

DefaultMaximumMigrationDowntime=[value]

6.266.7. next_run_configuration_exists

Virtual machine configuration has been changed and requires restart of the virtual machine.
Changed configuration is applied at processing the virtual machine’s shut down.

6.266.8. origin

The origin of this virtual machine.

Possible values:

ovirt

rhev

vmware

xen

external

hosted_engine

managed_hosted_engine

kvm

physical_machine

hyperv

660
 CHAPTER 6. TYPES

6.266.9. placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event
of a host failure, any virtual machine configured to be highly available is automatically
restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
<high_availability>
<enabled>true</enabled>
<priority>1</priority>
</high_availability>
<placement_policy>
<hosts>
<host>
<name>Host1</name>
</host>
<host>
<name>Host2</name>
</host>
</hosts>
<affinity>pinned</affinity>
</placement_policy>
</vm>

6.266.10. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating
system.

6.266.11. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be
automatically signed in the virtual machine’s operating system when console is opened.

6.266.12. stop_reason

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual
machine.

661
Red Hat Virtualization 4.0 REST API Guide

Table 6.348. Links summary

Name Type Summary

affinity_lab AffinityLabel[] Optional.

els

applications Application[] List of applications installed on the virtual machine.

cdroms Cdrom[] Reference to the ISO mounted to the CDROM.

cluster Cluster Reference to cluster the virtual machine belongs to.

cpu_profile CpuProfile Reference to CPU profile used by this virtual machine.

disk_attachm DiskAttachment[] References the disks attached to the virtual machine.

ents

external_hos ExternalHostProvi
t_provider der

floppies Floppy[] Reference to the ISO mounted to the floppy.

graphics_con GraphicsConsole[ List of graphics consoles configured for this virtual machine.
soles ]

host Host Reference to the host the virtual machine is running on.

host_devices HostDevice[] References devices associated to this virtual machine.

instance_typ InstanceType The virtual machine configuration can be optionally predefined

e via one of the instance types.

katello_erra KatelloErratum[] Lists all the Katello errata assigned to the virtual machine.
ta

662
 CHAPTER 6. TYPES

Name Type Summary

nics Nic[] References the list of network interface devices on the virtual
machine.

numa_nodes NumaNode[] Refers to the NUMA Nodes configuration used by this virtual
machine.

permissions Permission[] Permissions set for this virtual machine.

quota Quota Reference to quota configuration set for this virtual machine.

reported_dev ReportedDevice[]
ices

sessions Session[] List of user sessions opened for this virtual machine.

snapshots Snapshot[] Refers to all snapshots taken from the virtual machine.

statistics Statistic[] Statistics data collected from this virtual machine.

storage_doma StorageDomain Reference to storage domain the virtual machine belongs to.
in

tags Tag[]

template Template Reference to the template the virtual machine is based on.

vm_pool VmPool Reference to the pool the virtual machine is optionally

member of.

watchdogs Watchdog[] Refers to the Watchdog configuration.

663
Red Hat Virtualization 4.0 REST API Guide

6.266.13. affinity_labels

Optional. Used for labeling of sub-clusters.

6.266.14. katello_errata

Lists all the Katello errata assigned to the virtual machine.

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

You will receive response in XML like this one:

<katello_errata>
<katello_erratum href="/ovirt-engine/api/katelloerrata/456" id="456">
<name>RHBA-2013:XYZ</name>
<description>The description of the erratum</description>
<title>some bug fix update</title>
<type>bugfix</type>
<issued>2013-11-20T02:00:00.000+02:00</issued>
<solution>Few guidelines regarding the solution</solution>
<summary>Updated packages that fix one bug are now available for
XYZ</summary>
<packages>
<package>
<name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
...
</packages>
</katello_erratum>
...
</katello_errata>

6.267. VMAFFINITY ENUM

Table 6.349. Values summary

Name Summary

migratable

pinned

user_migrata
ble

6.268. VMBASE STRUCT

664
 CHAPTER 6. TYPES

Represents basic virtual machine configuration. This is used by virtual machines, templates and
instance types.

Table 6.350. Attributes summary

Name Type Summary

bios Bios Reference to virtual machine’s BIOS configuration.

comment String Free text containing comments about this object.

console Console Console configured for this virtual machine.

cpu Cpu The configuration of the virtual machine CPU.

cpu_shares Integer

creation_tim Date The virtual machine creation date.

e

custom_compa Version Virtual machine custom compatibility version.

tibility_ver
sion

custom_cpu_m String
odel

custom_emula String
ted_machine

custom_prope CustomProperty[] Properties sent to VDSM to configure various hooks.

rties

delete_prote Boolean If true, the virtual machine cannot be deleted.

cted

665
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

description String A human-readable description in plain text.

display Display The virtual machine display configuration.

domain Domain Domain configured for this virtual machine.

high_availab HighAvailability The virtual machine high availability configuration.

ility

id String A unique identifier.

initializati Initialization Reference to virtual machine’s initialization configuration.

on

io Io For performance tuning of IO threading.

large_icon Icon Virtual machine’s large icon.

memory Integer The virtual machine’s memory, in bytes.

memory_polic MemoryPolicy Reference to virtual machine’s memory management

y configuration.

migration MigrationOptions Reference to configuration of migration of running virtual

machine to another host.

migration_do Integer Maximum time the virtual machine can be non responsive
wntime during its live migration to another host in ms.

name String A human-readable name in plain text.

origin String The origin of this virtual machine.

666
 CHAPTER 6. TYPES

Name Type Summary

os OperatingSystem Operating system type installed on the virtual machine.

rng_device RngDevice Random Number Generator device configuration for this

virtual machine.

serial_numbe SerialNumber Virtual machine’s serial number in a cluster.

r

small_icon Icon Virtual machine’s small icon.

soundcard_en Boolean If true, the sound card is added to the virtual machine.
abled

sso Sso Reference to the Single Sign On configuration this virtual

machine is configured for.

start_paused Boolean If true, the virtual machine will be initially in 'paused' state
after start.

stateless Boolean If true, the virtual machine is stateless - it’s state (disks) are
rolled-back after shutdown.

time_zone TimeZone The virtual machine’s time zone set by oVirt.

tunnel_migra Boolean If true, the network data transfer will be encrypted during
tion virtual machine live migration.

type VmType Determines whether the virtual machine is optimized for

desktop or server.

usb Usb Configuration of USB devices for this virtual machine (count,
type).

667
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

virtio_scsi VirtioScsi Reference to VirtIO SCSI configuration.

6.268.1. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the
threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and
threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>

6.268.2. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If

custom_compatibility_version is set, it overrides the cluster’s compatibility version for this
particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine
resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

6.268.3. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically
restarted when it unexpectedly goes down.

6.268.4. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

6.268.5. memory

668
 CHAPTER 6. TYPES

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following
request:

PUT /ovirt-engine/api/vms/123

With the following request body:

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

Note

Memory in the example is converted to bytes using the following formula:

1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the
example above to increase memory while the virtual machine is running.

6.268.6. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in
ms.

Set either explicitly for the virtual machine or by engine-config -s

DefaultMaximumMigrationDowntime=[value]

6.268.7. origin

The origin of this virtual machine.

Possible values:

ovirt

rhev

vmware

xen

external

hosted_engine

managed_hosted_engine

kvm

669
Red Hat Virtualization 4.0 REST API Guide

physical_machine

hyperv

6.268.8. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating
system.

6.268.9. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be
automatically signed in the virtual machine’s operating system when console is opened.

Table 6.351. Links summary

Name Type Summary

cluster Cluster Reference to cluster the virtual machine belongs to.

cpu_profile CpuProfile Reference to CPU profile used by this virtual machine.

quota Quota Reference to quota configuration set for this virtual machine.

storage_doma StorageDomain Reference to storage domain the virtual machine belongs to.
in

6.269. VMDEVICETYPE ENUM

Table 6.352. Values summary

Name Summary

cdrom

floppy

6.270. VMPLACEMENTPOLICY STRUCT

670
 CHAPTER 6. TYPES

Table 6.353. Attributes summary

Name Type Summary

affinity VmAffinity

Table 6.354. Links summary

Name Type Summary

hosts Host[]

6.271. VMPOOL STRUCT

Table 6.355. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

display Display

id String A unique identifier.

max_user_vms Integer

name String A human-readable name in plain text.

prestarted_v Integer
ms

rng_device RngDevice

671
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

size Integer

soundcard_en Boolean
abled

stateful Boolean Virtual machine pool’s stateful flag.

type VmPoolType

use_latest_t Boolean
emplate_vers
ion

6.271.1. stateful

Virtual machine pool’s stateful flag.

Virtual machines from a stateful virtual machine pool are always started in stateful mode (stateless
snapshot is not created). The state of the virtual machine is preserved even when the virtual
machine is passed to a different user.

Table 6.356. Links summary

Name Type Summary

cluster Cluster

instance_typ InstanceType Reference to the instance type on which this pool is based.
e

permissions Permission[]

template Template

vm Vm

672
 CHAPTER 6. TYPES

6.271.2. instance_type

Reference to the instance type on which this pool is based. It can be set only on pool creation and
cannot be edited.

6.272. VMPOOLTYPE ENUM

Table 6.357. Values summary

Name Summary

automatic

manual

6.273. VMSTATUS ENUM

Type represeting a status of a virtual machine.

Table 6.358. Values summary

Name Summary

down This status indicates that the virtual machine process is not running.

image_locked This status indicates that the virtual machine process is not running and there is
some operation on the disks of the virtual machine that prevents it from being
started.

migrating This status indicates that the virtual machine process is running and the virtual
machine is being migrated from one host to another.

not_respondi This status indicates that the hypervisor detected that the virtual machine is not
ng responding.

paused This status indicates that the virtual machine process is running and the virtual
machine is paused.

673
Red Hat Virtualization 4.0 REST API Guide

Name Summary

powering_dow This status indicates that the virtual machine process is running and it is about to
n stop running.

powering_up This status indicates that the virtual machine process is running and the guest
operating system is being loaded.

reboot_in_pr This status indicates that the virtual machine process is running and the guest
ogress operating system is being rebooted.

restoring_st This status indicates that the virtual machine process is about to run and the virtual
ate machine is going to awake from hibernation.

saving_state This status indicates that the virtual machine process is running and the virtual
machine is being hibernated.

suspended This status indicates that the virtual machine process is not running and a running
state of the virtual machine was saved.

unassigned This status is set when an invalid status is received.

unknown This status indicates that the system failed to determine the status of the virtual
machine.

up This status indicates that the virtual machine process is running and the guest
operating system is loaded.

wait_for_lau This status indicates that the virtual machine process is about to run.
nch

6.273.1. paused

This status indicates that the virtual machine process is running and the virtual machine is paused.
This may happen in two cases: when running a virtual machine is paused mode and when the
virtual machine is being automatically paused due to an error.

6.273.2. powering_up

674
 CHAPTER 6. TYPES

6.273.2. powering_up

This status indicates that the virtual machine process is running and the guest operating system is
being loaded. Note that if no guest-agent is installed, this status is set for a predefined period of
time, that is by default 60 seconds, when running a virtual machine.

6.273.3. restoring_state

This status indicates that the virtual machine process is about to run and the virtual machine is going
to awake from hibernation. In this status, the running state of the virtual machine is being restored.

6.273.4. saving_state

This status indicates that the virtual machine process is running and the virtual machine is being
hibernated. In this status, the running state of the virtual machine is being saved. Note that this
status does not mean that the guest operating system is being hibernated.

6.273.5. suspended

This status indicates that the virtual machine process is not running and a running state of the virtual
machine was saved. This status is similar to Down, but when the VM is started in this status its
saved running state is restored instead of being booted using the normal procedue.

6.273.6. unknown

This status indicates that the system failed to determine the status of the virtual machine. The virtual
machine process may be running or not running in this status. For instance, when host becomes
non-responsive the virtual machines that ran on it are set with this status.

6.273.7. up

This status indicates that the virtual machine process is running and the guest operating system is
loaded. Note that if no guest-agent is installed, this status is set after a predefined period of time,
that is by default 60 seconds, when running a virtual machine.

6.273.8. wait_for_launch

This status indicates that the virtual machine process is about to run. This status is set when a
request to run a virtual machine arrives to the host. It is possible that the virtual machine process will
fail to run.

6.274. VMSUMMARY STRUCT

Table 6.359. Attributes summary

Name Type Summary

active Integer

675
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

migrating Integer

total Integer

6.275. VMTYPE ENUM

Type representing what the virtual machine is optimized for.

Table 6.360. Values summary

Name Summary

desktop The virtual machine is intended to be used as a desktop.

server The virtual machine is intended to be used as a server.

6.275.1. desktop

The virtual machine is intended to be used as a desktop. Currently, its implication is that a sound
device will be automatically added to the virtual machine.

6.275.2. server

The virtual machine is intended to be used as a server. Currently, its implication is that a sound
device will not be automatically added to the virtual machine.

6.276. VNICPASSTHROUGH STRUCT

Table 6.361. Attributes summary

Name Type Summary

mode VnicPassThrough Defines whether the vNIC will be implemented as a virtual

Mode device, or as a pass-through to a host device.

6.277. VNICPASSTHROUGHMODE ENUM

676
 CHAPTER 6. TYPES

The enum describes whether vNIC to be implemented as a pass-through device or a virtual one.
Currently it supports only 2 option, but there is a plan to add more in the future.

Table 6.362. Values summary

Name Summary

disabled To be implemented as a virtual device

enabled To be implemented as a pass-through device

6.278. VNICPROFILE STRUCT

Table 6.363. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

custom_prope CustomProperty[]
rties

description String A human-readable description in plain text.

id String A unique identifier.

name String A human-readable name in plain text.

pass_through VnicPassThrough

port_mirrori Boolean
ng

Table 6.364. Links summary

677
Red Hat Virtualization 4.0 REST API Guide

Name Type Summary

network Network

network_filt NetworkFilter Network filter will enhance the admin ability to manage the
er network packets traffic from/to the participated VMs.

permissions Permission[]

qos Qos

6.279. VOLUMEGROUP STRUCT

Table 6.365. Attributes summary

Name Type Summary

id String

logical_unit LogicalUnit[]
s

name String

6.280. WATCHDOG STRUCT

This type represents a watchdog configuration.

Table 6.366. Attributes summary

Name Type Summary

action WatchdogAction Watchdog action to be performed when watchdog is triggered.

comment String Free text containing comments about this object.

678
 CHAPTER 6. TYPES

Name Type Summary

description String A human-readable description in plain text.

id String A unique identifier.

model WatchdogModel Model of watchdog device.

name String A human-readable name in plain text.

6.280.1. model

Model of watchdog device. Currently supported only I6300ESB.

Table 6.367. Links summary

Name Type Summary

instance_typ InstanceType Optionally references to an instance type the device is used

e by.

template Template Optionally references to a template the device is used by.

vm Vm Don’t use this element, use vms instead.

vms Vm[] References to the virtual machines that are using this device.

6.280.2. vms

References to the virtual machines that are using this device. A device may be used by several
virtual machines; for example, a shared disk my be used simultaneously by two or more virtual
machines.

6.281. WATCHDOGACTION ENUM

This type describes available watchdog actions.

Table 6.368. Values summary

679
Red Hat Virtualization 4.0 REST API Guide

Name Summary

dump Virtual machine process will get core dumped to the default path on the host.

none No action will be performed when watchdog action is triggered.

pause Virtual machine will be paused when watchdog action is triggered.

poweroff Virtual machine will be powered off when watchdog action is triggered.

reset Virtual machine will be rebooted when watchdog action is triggered.

6.281.1. none

No action will be performed when watchdog action is triggered. However log message will still be
generated.

6.282. WATCHDOGMODEL ENUM

This type represents the watchdog model.

Table 6.369. Values summary

Name Summary

i6300esb Currently only model supported is model I6300ESB.

6.283. WEIGHT STRUCT

Table 6.370. Attributes summary

Name Type Summary

comment String Free text containing comments about this object.

description String A human-readable description in plain text.

680
 CHAPTER 6. TYPES

Name Type Summary

factor Integer

id String A unique identifier.

name String A human-readable name in plain text.

Table 6.371. Links summary

Name Type Summary

scheduling_p SchedulingPolicy
olicy

scheduling_p SchedulingPolicy
olicy_unit Unit

681
Red Hat Virtualization 4.0 REST API Guide

APPENDIX A. PRIMITIVE TYPES

This section describes the primitive data types supported by the API.

A.1. STRING PRIMITIVE

A finite sequence of Unicode characters.

A.2. BOOLEAN PRIMITIVE

Represents the false and true concepts used in mathematical logic.

The valid values are the strings false and true.

Case is ignored by the engine, so for example False and FALSE also valid values. However the
server will always return lower case values.

For backwards compatibility with older versions of the engine, the values 0 and 1 are also accepted.
The value 0 has the same meaning than false, and 1 has the same meaning than true. Try to
avoid using these values, as support for them may be removed in the future.

A.3. INTEGER PRIMITIVE

Represents the mathematical concept of integer number.

The valid values are finite sequences of decimal digits.

Currently the engine implements this type using a signed 32 bit integer, so the minimum value is -
231 (-2147483648) and the maximum value is 231-1 (2147483647).

However, there are some attributes in the system where the range of values possible with 32 bit isn’t
enough. In those exceptional cases the engine uses 64 bit integers, in particular for the following
attributes:

Disk.actual_size

Disk.provisioned_size

GlusterClient.bytes_read

GlusterClient.bytes_written

Host.max_scheduling_memory

Host.memory

HostNic.speed

LogicalUnit.size

MemoryPolicy.guaranteed

NumaNode.memory

QuotaStorageLimit.limit

682
 APPENDIX A. PRIMITIVE TYPES

StorageDomain.available

StorageDomain.used

StorageDomain.committed

VmBase.memory

For these exception cases the minimum value is -263 (-9223372036854775808) and the maximum
value is 263-1 (9223372036854775807).

Note

In the future the integer type will be implemented using unlimited precission integers, so
the above limitations and exceptions will eventually disappear.

A.4. DECIMAL PRIMITIVE

Represents the mathematical concept of real number.

Currently the engine implements this type using 32 bit IEEE 754 single precision floating point
numbers.

For some attributes this isn’t enough precision. In those exceptional cases the engine uses 64 bit
double precision floating point numbers, in particular for the following attributes:

QuotaStorageLimit.usage

QuotaStorageLimit.memory_limit

QuotaStorageLimit.memory_usage

Note

In the future the decimal type will be implemented using unlimited precision decimal
numbers, so the above limitations and exceptions will eventually disappear.

A.5. DATE PRIMITIVE

Represents a date and time.

The format returned by the engine is the one described in the XML Schema specification when
requesting XML. For example, if you send a request like this to retrieve the XML representation of a
virtual machine:

GET /ovirt-engine/api/vms/123
Accept: application/xml

The response body will contain the following XML document:

<vm id="123" href="/ovirt-engine/api/vms/123">

...

683
Red Hat Virtualization 4.0 REST API Guide

<creation_time>2016-09-08T09:53:35.138+02:00</creation_time>
...
</vm>

When requesting the JSON representation the engine uses a different, format: an integer containing
the number of seconds since Jan 1st 1970, also know as epoch time. For example, if you send a
request like this to retrieve the JSON representation of a virtual machine:

GET /ovirt-engine/api/vms/123
Accept: application/json

The response body will contain the following JSON document:

{
"id": "123",
"href="/ovirt-engine/api/vms/123",
...
"creation_time": 1472564909990,
...
}

Note

In both cases, the dates returned by the engine use the time zone configured in the server
where it is running, in the above examples it is UTC+2.

684