Red Hat 4.0 Virtualization REST API Guide
Below you will find brief information for Red Hat Virtualization 4.0. This guide helps you to access and manage the Red Hat Virtualization environment from your applications through a RESTful API. This API allows you to create and manage virtual machines, data centers, storage domains, and other components of your Red Hat Virtualization environment.
Advertisement
Advertisement
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 [email protected]
Legal Notice
Copyright © 2017 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative 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
1.1. REPRESENTATIONAL STATE TRANSFER
3.1. EXAMPLE: ACCESS API ENTRY POINT
3.2. EXAMPLE: LIST DATA CENTERS
3.3. EXAMPLE: LIST HOST CLUSTERS
3.4. EXAMPLE: LIST LOGICAL NETWORKS
3.6. EXAMPLE: CREATE NFS DATA STORAGE
3.7. EXAMPLE: CREATE NFS ISO STORAGE
3.8. EXAMPLE: ATTACH STORAGE DOMAINS TO DATA CENTER
3.9. EXAMPLE: CREATE VIRTUAL MACHINE
3.10. EXAMPLE: CREATE A VIRTUAL MACHINE NIC
3.11. EXAMPLE: CREATE VIRTUAL DISK
3.12. EXAMPLE: ATTACH ISO IMAGE TO VIRTUAL MACHINE
3.13. EXAMPLE: START THE VIRTUAL MACHINE
Table of Contents
13
13
15
17
27
28
30
31
32
22
24
25
26
34
35
36
37
75
76
77
78
78
71
72
72
73
74
68
69
70
65
66
67
85
87
87
88
79
80
81
83
84
90
91
1
Red Hat Virtualization 4.0 REST API Guide
5.27. BALANCE
5.58. EXTERNALCOMPUTERESOURCES
5.68. EXTERNALPROVIDERCERTIFICATE
5.69. EXTERNALPROVIDERCERTIFICATES
2
136
137
137
138
138
128
130
131
135
136
124
124
125
126
127
119
120
120
121
123
108
111
114
116
117
102
103
104
105
106
91
92
93
95
96
100
101
148
149
150
151
153
159
161
144
144
145
147
147
139
141
142
142
143
5.80. GLUSTERHOOKS
5.130. OPENSTACKIMAGEPROVIDERS
5.133. OPENSTACKNETWORKPROVIDER
Table of Contents
220
222
223
224
226
211
212
215
217
218
206
206
208
209
210
198
199
200
201
205
192
193
194
194
196
189
190
190
191
191
161
161
169
171
172
173
174
175
238
240
242
243
244
245
232
233
234
235
236
227
227
227
230
231
3
Red Hat Virtualization 4.0 REST API Guide
5.133. OPENSTACKNETWORKPROVIDER
5.134. OPENSTACKNETWORKPROVIDERS
5.138. OPENSTACKVOLUMEAUTHENTICATIONKEY
5.139. OPENSTACKVOLUMEAUTHENTICATIONKEYS
5.140. OPENSTACKVOLUMEPROVIDER
5.141. OPENSTACKVOLUMEPROVIDERS
5.179. STORAGEDOMAINCONTENTDISK
5.180. STORAGEDOMAINCONTENTDISKS
5.181. STORAGEDOMAINSERVERCONNECTION
5.182. STORAGEDOMAINSERVERCONNECTIONS
5.186. STORAGEDOMAINVMDISKATTACHMENT
4
281
281
282
282
284
277
278
279
280
280
271
272
274
275
276
266
267
268
268
269
259
260
262
263
264
256
257
257
258
258
250
251
252
253
255
245
247
248
249
291
293
297
298
299
285
286
286
288
289
299
300
303
303
306
5.186. STORAGEDOMAINVMDISKATTACHMENT
5.187. STORAGEDOMAINVMDISKATTACHMENTS
5.190. STORAGESERVERCONNECTION
5.191. STORAGESERVERCONNECTIONEXTENSION
5.192. STORAGESERVERCONNECTIONEXTENSIONS
5.193. STORAGESERVERCONNECTIONS
5.203. TEMPLATEDISKATTACHMENTS
5.214. VIRTUALFUNCTIONALLOWEDNETWORK
5.215. VIRTUALFUNCTIONALLOWEDNETWORKS
5.239. VNICPROFILE
Table of Contents
367
369
370
372
373
347
361
362
364
366
341
342
343
345
346
335
336
337
338
340
330
331
332
333
334
321
323
325
328
329
313
315
316
317
319
306
307
307
309
311
385
387
387
388
388
375
378
380
381
382
389
392
393
399
5
Red Hat Virtualization 4.0 REST API Guide
6
6.6. AGENTCONFIGURATION STRUCT
6.23. BRICKPROFILEDETAIL STRUCT
435
436
436
437
437
432
433
434
435
435
422
423
424
424
425
420
421
421
421
421
442
443
448
449
438
438
438
439
441
449
450
418
418
419
419
419
415
416
416
417
417
405
405
410
411
412
413
414
399
400
402
403
6.48. DISKPROFILE STRUCT
6.57. ENTITYEXTERNALSTATUS ENUM
6.58. ENTITYPROFILEDETAIL STRUCT
6.61. EXTERNALCOMPUTERESOURCE STRUCT
6.62. EXTERNALDISCOVEREDHOST STRUCT
6.64. EXTERNALHOSTGROUP STRUCT
6.65. EXTERNALHOSTPROVIDER STRUCT
6.70. EXTERNALVMPROVIDERTYPE ENUM
6.79. GLUSTERBRICKADVANCEDDETAILS STRUCT
6.80. GLUSTERBRICKMEMORYINFO STRUCT
6.85. GLUSTERMEMORYPOOL STRUCT
6.86. GLUSTERSERVERHOOK STRUCT
6.89. GLUSTERVOLUMEPROFILEDETAILS STRUCT
6.90. GLUSTERVOLUMESTATUS ENUM
6.96. GUESTOPERATINGSYSTEM STRUCT
6.97. HARDWAREINFORMATION STRUCT
Table of Contents
480
480
480
481
482
474
475
476
476
478
472
472
472
473
473
466
468
469
470
470
461
463
464
465
465
458
459
459
460
460
450
451
456
456
456
457
458
491
492
493
493
494
494
495
487
487
489
490
491
482
483
484
485
486
7
Red Hat Virtualization 4.0 REST API Guide
6.101. HOOKSTAGE ENUM
6.105. HOSTDEVICEPASSTHROUGH STRUCT
6.107. HOSTNICVIRTUALFUNCTIONSCONFIGURATION STRUCT
6.117. IMAGETRANSFERPHASE ENUM
6.118. INHERITABLEBOOLEAN ENUM
6.123. IPADDRESSASSIGNMENT STRUCT
6.138. MEMORYOVERCOMMIT STRUCT
6.143. MIGRATIONBANDWIDTH STRUCT
6.144. MIGRATIONBANDWIDTHASSIGNMENTMETHOD ENUM
6.145. MIGRATIONOPTIONS STRUCT
6.148. NETWORKATTACHMENT STRUCT
6.149. NETWORKCONFIGURATION STRUCT
6.154. NETWORKUSAGE ENUM
8
539
541
541
541
543
536
538
538
538
539
532
532
533
534
535
521
523
530
530
531
517
517
518
519
521
510
513
515
515
516
495
495
495
504
505
505
509
510
554
554
555
556
556
556
545
545
546
546
549
543
543
544
544
544
6.155. NFSPROFILEDETAIL STRUCT
6.158. NICCONFIGURATION STRUCT
6.165. OPENSTACKIMAGEPROVIDER STRUCT
6.166. OPENSTACKNETWORK STRUCT
6.167. OPENSTACKNETWORKPROVIDER STRUCT
6.168. OPENSTACKNETWORKPROVIDERTYPE ENUM
6.169. OPENSTACKPROVIDER STRUCT
6.171. OPENSTACKVOLUMEPROVIDER STRUCT
6.172. OPENSTACKVOLUMETYPE STRUCT
6.173. OPENSTACKVOLUMEAUTHENTICATIONKEY STRUCT
6.174. OPENSTACKVOLUMEAUTHENTICATIONKEYUSAGETYPE ENUM
6.176. OPERATINGSYSTEMINFO STRUCT
6.189. POWERMANAGEMENTSTATUS ENUM
6.198. QUOTACLUSTERLIMIT STRUCT
6.200. QUOTASTORAGELIMIT STRUCT
6.203. REPORTEDCONFIGURATION STRUCT
6.205. REPORTEDDEVICETYPE ENUM
6.207. RNGDEVICE STRUCT
Table of Contents
583
584
584
585
586
581
582
582
582
582
577
579
579
579
580
573
574
575
576
576
568
569
570
571
573
563
564
564
566
566
560
561
561
562
563
556
557
557
558
594
595
595
596
596
586
587
587
591
592
597
597
598
598
598
9
Red Hat Virtualization 4.0 REST API Guide
10
6.211. SCHEDULINGPOLICY STRUCT
6.212. SCHEDULINGPOLICYUNIT STRUCT
6.217. SERIALNUMBERPOLICY ENUM
6.219. SKIPIFCONNECTIVITYBROKEN STRUCT
6.228. SSHAUTHENTICATIONMETHOD ENUM
6.238. STORAGECONNECTION STRUCT
6.239. STORAGECONNECTIONEXTENSION STRUCT
6.241. STORAGEDOMAINSTATUS ENUM
6.252. TRANSPARENTHUGEPAGES STRUCT
6.254. UNMANAGEDNETWORK STRUCT
6.260. VCPUPIN STRUCT
634
634
635
636
636
626
627
629
630
633
621
623
623
624
625
618
619
619
620
620
617
617
617
618
618
603
604
605
606
606
601
602
602
603
603
598
599
599
600
600
645
645
646
646
647
637
643
644
644
645
647
649
649
650
6.270. VMPLACEMENTPOLICY STRUCT
6.277. VNICPASSTHROUGHMODE ENUM
Table of Contents
670
672
672
675
675
653
663
664
669
670
650
650
650
651
651
653
676
676
676
677
678
679
680
680
682
682
682
683
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)
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 [email protected]:/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 grant_type scope username
Value password ovirt-app-api 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-appapi&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
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
User name
Value admin
Domain
internal
Password
Unencoded credentials
Base64 encoded credentials
mypassword admin@internal:mypassword
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 transportlevel 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=/ovirtengine/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
...
RFC 2818 HTTP Over TLS.
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>
<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
,
. 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
):
<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
):
<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/ovirtengine/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/ovirtengine/api/datacenters/001/storagedomains
32
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>
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
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
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
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
This section enumerates all the requests that are available in the API.
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
CHAPTER 4. REQUESTS
39
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
40
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
CHAPTER 4. REQUESTS
41
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
{volume:id} / getprofilestatistics
42
CHAPTER 4. REQUESTS
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
43
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
44
CHAPTER 4. REQUESTS
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
45
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
46
CHAPTER 4. REQUESTS
/
/
/
/
/
/
/ {storagedomain:id} / activate
/
/
/ {storagedomain:id} / deactivate
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
47
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
48
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
CHAPTER 4. REQUESTS
49
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
50
CHAPTER 4. REQUESTS
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
{nic:id} / updatevirtualfunctionsconfiguration
/
/
/
/ virtualfunctionallowedlabels
/
/
/ virtualfunctionallowedlabels
/
/
/ virtualfunctionallowedlabels
/
/
/
/
/ virtualfunctionallowednetworks
/
/
/ virtualfunctionallowednetworks
/
/
/ virtualfunctionallowednetworks /
virtualfunctionallowednetworks /
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
51
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/ storageconnectionextensions /
{storageconnectionextension:id}
/
{storageconnectionextension:id}
{storageconnectionextension:id}
/
/
/
/
/
/
/
/
/
/
{host:id} / unregisteredstoragedomainsdiscover
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
52
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
CHAPTER 4. REQUESTS
53
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
54
CHAPTER 4. REQUESTS
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
PUT / openstackvolumeproviders /
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
55
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
operatingsystems / {operatingsystem:id}
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
56
CHAPTER 4. REQUESTS
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
57
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/ {storagedomain:id} / isattached
/
/
/
/
/ {storagedomain:id} / refreshluns
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/ {storagedomain:id} / updateovfstore
/
/
/
/
/
/
/
/
/
58
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
CHAPTER 4. REQUESTS
59
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
60
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
CHAPTER 4. REQUESTS
61
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
62
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
CHAPTER 4. REQUESTS
63
Red Hat Virtualization 4.0 REST API Guide
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
/
64
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 get
Summary
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 group
Type Direction
Out
Summary
The affinity group.
CHAPTER 5. SERVICES
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.1.3. update PUT
Update the affinity group.
Table 5.4. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
The affinity group.
group
In/Out
5.2. AFFINITYGROUPVM
This service manages a single virtual machine to affinity group assignment.
Table 5.5. Methods summary
Name remove
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
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 add
Summary
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 vm
Type
Direction
In/Out
Summary
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 max
Type
Direction
In
Summary
Sets the maximum number of virtual machines to return.
vms
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 add
Summary
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
Name group
Type Direction
In/Out
5.4.2. list GET
List existing affinity groups.
Table 5.12. Parameters summary
Name groups
Type Direction
Out
max
In
CHAPTER 5. SERVICES
Summary
The affinity group object to create.
Summary
The list of existing affinity groups.
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 get
Summary
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 label
Type Direction
Out
Summary
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 label
Type Direction
In/Out
Summary
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 get
Summary
Retrieves details about a host that has this label assigned.
remove
Remove a label from a host.
70
5.6.1. get GET
CHAPTER 5. SERVICES
Retrieves details about a host that has this label assigned.
Table 5.17. Parameters summary
Name host
Type
Direction
Out
Summary
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 add
Summary
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 host
Type
Direction
In/Out
5.7.2. list GET
List all hosts with the label.
Table 5.20. Parameters summary
Summary
71
Red Hat Virtualization 4.0 REST API Guide
72
Name hosts
Type
Direction
Out
Summary
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 get
Summary
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 vm
Type
Direction
Out
Summary
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
Name add list
Summary
Add a label to a vm.
List all vms with the label.
5.9.1. add POST
Add a label to a vm.
Table 5.24. Parameters summary
Name vm
Type
Direction
In/Out
5.9.2. list GET
List all vms with the label.
Table 5.25. Parameters summary
Name vms
Type
Direction
Out
Summary
Summary
5.10. AFFINITYLABELS
Manages the affinity labels available in the system.
Table 5.26. Methods summary
Name add
Summary
Creates a new label.
CHAPTER 5. SERVICES
73
Red Hat Virtualization 4.0 REST API Guide
Name list
Summary
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 label
Type Direction
In/Out
Summary
5.10.2. list GET
Lists all labels present in the system.
Table 5.28. Parameters summary
Name labels
Type Direction
Out
max
In
Summary
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 get remove
Summary
Retrieves details about the attached label.
Removes the label from an entity.
5.11.1. get GET
Retrieves details about the attached label.
Table 5.30. Parameters summary
Name label
Type Direction
Out
Summary
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 add
Summary
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 label
Type Direction
In/Out
Summary
5.12.2. list GET
Lists all labels that are attached to an entity.
Table 5.33. Parameters summary
Name label
Type Direction
Out
Summary
5.13. ASSIGNEDCPUPROFILE
Table 5.34. Methods summary
Name get
Summary remove
5.13.1. get GET
Table 5.35. Parameters summary
Name Type Direction profile
Out
76
5.13.2. remove DELETE
Table 5.36. Parameters summary
Summary
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the remove should be performed asynchronously.
5.14. ASSIGNEDCPUPROFILES
Table 5.37. Methods summary
Name add
Summary list
5.14.1. add POST
Table 5.38. Parameters summary
Name Type Direction profile
In/Out
Summary
5.14.2. list GET
Table 5.39. Parameters summary
Name max
Type
Direction
In
profiles
Out
Summary
Sets the maximum number of profiles to return.
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 get
Summary remove
5.15.1. get GET
Table 5.41. Parameters summary
Name Type Direction disk_pro file
Out
5.15.2. remove DELETE
Table 5.42. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.16. ASSIGNEDDISKPROFILES
Table 5.43. Methods summary
Name add
Summary
78
CHAPTER 5. SERVICES
Name list
Summary
5.16.1. add POST
Table 5.44. Parameters summary
Name Type Direction profile
In/Out
Summary
5.16.2. list GET
Table 5.45. Parameters summary
Name max
Type
Direction
In
profiles
Out
Summary
Sets the maximum number of profiles to return.
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 get
Summary remove
79
Red Hat Virtualization 4.0 REST API Guide
Name update
Summary
5.17.1. get GET
Table 5.47. Parameters summary
Name Type network
Direction
Out
5.17.2. remove DELETE
Table 5.48. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.17.3. update PUT
Table 5.49. Parameters summary
Name async
Type
Direction
In
network
In/Out
80
5.18. ASSIGNEDNETWORKS
Table 5.50. Methods summary
Summary
Indicates if the update should be performed asynchronously.
CHAPTER 5. SERVICES
Name add list
Summary
5.18.1. add POST
Table 5.51. Parameters summary
Name Type network
Direction
In/Out
5.18.2. list GET
Table 5.52. Parameters summary
Name max
Type
Direction
In
networks
Out
Summary
Summary
Sets the maximum number of networks to return.
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 add
Summary
Assign a new permission to a user or group for specific entity.
list
List all the permissions of the specific entity.
82
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" />
CHAPTER 5. SERVICES
</permission>
Table 5.54. Parameters summary
Name Type Direction permissi on
In/Out
Summary
The permission.
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 permissi ons
Out
Summary
The list of permissions.
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 list
Summary
5.20.1. list GET
Table 5.57. Parameters summary
Name max
Type
Direction
In
roles
Out
Summary
Sets the maximum number of roles to return.
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 get
Summary
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 tag
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
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 add
Summary
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 tag
Type
Direction
In/Out
Summary
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 max
Type
Direction
In
Summary
Sets the maximum number of tags to return.
tags
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 get
Summary remove
5.23.1. get GET
Table 5.65. Parameters summary
Name Type Direction profile
Out
5.23.2. remove DELETE
Table 5.66. Parameters summary
Name async
Type
Direction
In
Summary
Summary
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 add
Summary list
5.24.1. add POST
Table 5.68. Parameters summary
Name Type Direction profile
In/Out
5.24.2. list GET
Table 5.69. Parameters summary
Name max
Type
Direction
In
profiles
Out
Summary
Summary
Sets the maximum number of profiles to return.
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 activate
Summary
This operation activates an attached storage domain.
88
CHAPTER 5. SERVICES
Name deactivate
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the deactivation should be performed asynchronously.
5.25.3. get GET
Table 5.73. Parameters summary
Name Type Direction storage_ domain
Out
5.25.4. remove DELETE
Table 5.74. Parameters summary
Name async
Type
Direction
In
Summary
5.26. ATTACHEDSTORAGEDOMAINS
Table 5.75. Methods summary
Name add
Summary list
90
5.26.1. add POST
Table 5.76. Parameters summary
Summary
Indicates if the remove should be performed asynchronously.
CHAPTER 5. SERVICES
Name Type Direction storage_ domain
In/Out
5.26.2. list GET
Table 5.77. Parameters summary
Name max
Type
Direction
In
Summary
Summary
Sets the maximum number of storage domains to return.
storage_ domains
Out
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 get
Summary remove
5.27.1. get GET
Table 5.79. Parameters summary
91
Red Hat Virtualization 4.0 REST API Guide
Name Type balance
Direction
Out
filter
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.28. BALANCES
Table 5.81. Methods summary
Name add
Summary list
5.28.1. add POST
Table 5.82. Parameters summary
Name Type balance
Direction
In/Out
92
5.28.2. list GET
Summary
CHAPTER 5. SERVICES
Table 5.83. Parameters summary
Name Type balances
Direction
Out
filter
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of balances to return.
max
In
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 get
Summary
Get a bookmark.
Remove a bookmark.
remove 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 bookmark
Out
Summary
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 async
Type
Direction
In
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the update should be performed asynchronously.
The updated bookmark.
bookmark
In/Out
5.30. BOOKMARKS
A service to manage bookmarks.
Table 5.88. Methods summary
Name add
Summary
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 bookmark
In/Out
Summary
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 bookmark s
Out
Summary
The list of available bookmarks.
max
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 get
Summary
Get information about the cluster.
remove
Removes cluster from the system.
96
CHAPTER 5. SERVICES
Name resetemulate dmachine
Summary 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 cluster
Direction
Out
Summary filter
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.31.3. resetemulatedmachine POST
Table 5.94. Parameters summary
Name async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
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 get
Summary
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 level
Type Direction
Out
Summary
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 list
Summary
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 levels
Type Direction
Out
Summary
Retrieved cluster levels.
5.34. CLUSTERS
A service to manage clusters.
Table 5.100. Methods summary
Name add
Summary
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 cluster
Direction
In/Out
Summary
102
CHAPTER 5. SERVICES
5.34.2. list GET
Table 5.102. Parameters summary
Name Type case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
clusters
Out
filter
In
max
search
In
In
Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of clusters to return.
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 copy
Summary
5.35.1. copy POST
103
Red Hat Virtualization 4.0 REST API Guide
Table 5.104. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the copy should be performed asynchronously.
5.36. CPUPROFILE
Table 5.105. Methods summary
Name get
Summary remove update
5.36.1. get GET
Table 5.106. Parameters summary
Name Type Direction profile
Out
5.36.2. remove DELETE
Table 5.107. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
104
CHAPTER 5. SERVICES
5.36.3. update PUT
Table 5.108. Parameters summary
Name async
Type
Direction
In
profile
In/Out
5.37. CPUPROFILES
Table 5.109. Methods summary
Name add
Summary list
5.37.1. add POST
Table 5.110. Parameters summary
Name Type Direction profile
In/Out
5.37.2. list GET
Table 5.111. Parameters summary
Summary
Indicates if the update should be performed asynchronously.
Summary
105
Red Hat Virtualization 4.0 REST API Guide
Name max
Type
Direction
In
profile
Out
Summary
Sets the maximum number of profiles to return.
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 get
Summary
Get a data center.
remove
Removes the data center.
update
Updates the data center.
106
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" />
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 data_cen ter
Out
Summary filter
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 async
Type
Direction
In
force
In
Summary
Indicates if the remove should be performed asynchronously.
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
data_cen ter
In/Out The data center that is being updated.
108
5.39. DATACENTERS
CHAPTER 5. SERVICES
A service to manage data centers.
Table 5.116. Methods summary
Name add
Summary
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 data_cen ter
In/Out
Summary
The data center that is being added.
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 case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
110
CHAPTER 5. SERVICES
Name Type Direction data_cen ters
Out
filter
In
max
In
search
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of data centers to return.
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 copy export
Summary
This operation copies a disk to the specified storage domain.
get
111
Red Hat Virtualization 4.0 REST API Guide
Name move
Summary
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 async
Type
Direction
In
Summary
Indicates if the copy should be performed asynchronously.
disk
In
filter
In
storage_ domain
In
Indicates if the results should be filtered according to the permissions of the user.
112
5.40.2. export POST
Table 5.121. Parameters summary
Name async
Type
Direction
In
filter
In
CHAPTER 5. SERVICES
Summary
Indicates if the export should be performed asynchronously.
Indicates if the results should be filtered according to the permissions of the user.
storage_ domain
In
5.40.3. get GET
Table 5.122. Parameters summary
Name disk
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
Indicates if the move should be performed asynchronously.
113
Red Hat Virtualization 4.0 REST API Guide
Name filter
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
storage_ domain
In
5.40.5. remove DELETE
Table 5.124. Parameters summary
Name async
Type
Direction
In
Summary
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 get
Summary
Returns the details of the attachment, including the bootable flag and link to the disk.
remove update
Removes the disk attachment.
Update the disk attachment and the disk properties within it.
114
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
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 attachme nt
Out
Summary
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 detach_o nly
Direction
In
Summary
Indicates if the disk should only be detached from 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 disk_att achment
In/Out
Summary
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 add
Summary
Adds a new disk attachment to the virtual machine.
list
List the disk that are attached to the virtual machine.
116
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>
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 attachme nt
In/Out
Summary
5.42.2. list GET
List the disk that are attached to the virtual machine.
Table 5.131. Parameters summary
Name Type Direction attachme nts
Out
Summary
5.43. DISKPROFILE
117
Red Hat Virtualization 4.0 REST API Guide
Table 5.132. Methods summary
Name get
Summary remove update
5.43.1. get GET
Table 5.133. Parameters summary
Name Type Direction profile
Out
5.43.2. remove DELETE
Table 5.134. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.43.3. update PUT
Table 5.135. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
118
CHAPTER 5. SERVICES
Name Type Direction profile
In/Out
Summary
5.44. DISKPROFILES
Table 5.136. Methods summary
Name add
Summary list
5.44.1. add POST
Table 5.137. Parameters summary
Name Type Direction profile
In/Out
Summary
5.44.2. list GET
Table 5.138. Parameters summary
Name max
Type
Direction
In
profile
Out
Summary
Sets the maximum number of profiles to return.
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 get
Summary remove
5.45.1. get GET
Table 5.140. Parameters summary
Name Type Direction snapshot
Out
5.45.2. remove DELETE
Table 5.141. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.46. DISKSNAPSHOTS
Table 5.142. Methods summary
Name list
Summary
120
CHAPTER 5. SERVICES
5.46.1. list GET
Table 5.143. Parameters summary
Name max
Type
Direction
In
snapshot s
Out
Summary
Sets the maximum number of snapshots to return.
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 add
Summary
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 disk
Type
Direction
In/Out
Summary
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
Name Type case_sen sitive
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
disks
max
search
Out
In
In
List of retrieved disks.
Sets the maximum number of disks to return.
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 get
Summary
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 domain
Type
Direction
Out
Summary
The authentication domain.
5.49. DOMAINGROUP
Table 5.149. Methods summary
Name get
Summary
5.49.1. get GET
Table 5.150. Parameters summary
Name get
Type
Direction
Out
5.50. DOMAINGROUPS
Table 5.151. Methods summary
Summary
124
CHAPTER 5. SERVICES
Name list
Summary
5.50.1. list GET
Table 5.152. Parameters summary
Name Type case_sen sitive
Direction
In
groups
max
search
Out
In
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
Sets the maximum number of groups to return.
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 get
Summary
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 user
Type
Direction
Out
Summary
The domain user.
5.52. DOMAINUSERS
A service to list all domain users in the system.
Table 5.155. Methods summary
Name list
Summary
List all the users in the domain.
126
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:
<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
CHAPTER 5. SERVICES
Name Type case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
In Sets the maximum number of users to return.
max
search
users
In
Out
A query string used to restrict the returned users.
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 list
Summary
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 domains
Direction
Out
Summary
The list of domains.
max
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 list
Summary
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 errata
Type Direction
Out
Summary
A representation of Katello errata.
max
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 get
Summary
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@internalauthz.
</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 event
Type
Direction
Out
Summary
130
5.55.2. remove DELETE
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 async
Type
Direction
In
Summary
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 add
Summary
Adds an external event to the internal audit log.
list undelete
Get list of events.
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 event
Type
Direction
In/Out
Summary
132
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>
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 case_sen sitive
events
Type
Direction
In
Out
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
from
In Indicates the identifier of the the first event that should be returned.
In Sets the maximum number of events to return.
max
search
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 async
Type
Direction
In
Summary
Indicates if the un-delete should be performed asynchronously.
5.57. EXTERNALCOMPUTERESOURCE
Table 5.168. Methods summary
Name get
Summary
5.57.1. get GET
Table 5.169. Parameters summary
Name Type Direction resource
Out
Summary
5.58. EXTERNALCOMPUTERESOURCES
Table 5.170. Methods summary
135
Red Hat Virtualization 4.0 REST API Guide
Name list
Summary
5.58.1. list GET
Table 5.171. Parameters summary
Name max
Type
Direction
In
resource s
Out
Summary
Sets the maximum number of resources to return.
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 get
Summary
5.59.1. get GET
Table 5.173. Parameters summary
Name host
Type Direction
Out
Summary
136
CHAPTER 5. SERVICES
5.60. EXTERNALDISCOVEREDHOSTS
Table 5.174. Methods summary
Name list
Summary
5.60.1. list GET
Table 5.175. Parameters summary
Name hosts
Type Direction
Out
max
In
Summary
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 get
Summary
5.61.1. get GET
Table 5.177. Parameters summary
137
Red Hat Virtualization 4.0 REST API Guide
Name host
Type Direction
Out
Summary
5.62. EXTERNALHOSTGROUP
Table 5.178. Methods summary
Name get
Summary
5.62.1. get GET
Table 5.179. Parameters summary
Name group
Type Direction
Out
Summary
5.63. EXTERNALHOSTGROUPS
Table 5.180. Methods summary
Name list
Summary
5.63.1. list GET
Table 5.181. Parameters summary
138
CHAPTER 5. SERVICES
Name groups
Type Direction
Out
max
In
Summary
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 get importcertif icates remove
Summary 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 provider
Out
5.64.2. importcertificates POST
Table 5.184. Parameters summary
Name Type Direction certific ates
In
5.64.3. remove DELETE
Table 5.185. Parameters summary
Name async
Type
Direction
In
Summary
Summary
5.64.4. testconnectivity POST
Table 5.186. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the test should be performed asynchronously.
5.64.5. update PUT
Table 5.187. Parameters summary
Summary
Indicates if the remove should be performed asynchronously.
140
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the update should be performed asynchronously.
provider
In/Out
5.65. EXTERNALHOSTPROVIDERS
Table 5.188. Methods summary
Name add
Summary list
5.65.1. add POST
Table 5.189. Parameters summary
Name Type Direction provider
In/Out
Summary
5.65.2. list GET
Table 5.190. Parameters summary
Name max
Type
Direction
In
Summary
Sets the maximum number of providers to return.
141
Red Hat Virtualization 4.0 REST API Guide
Name Type Direction provider s
Out
Summary
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 list
Summary
5.66.1. list GET
Table 5.192. Parameters summary
Name hosts
Type Direction
Out
max
In
Summary
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 importcertif icates
Summary testconnecti vity
5.67.1. importcertificates POST
Table 5.194. Parameters summary
Name Type Direction certific ates
In
5.67.2. testconnectivity POST
Table 5.195. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the test should be performed asynchronously.
5.68. EXTERNALPROVIDERCERTIFICATE
Table 5.196. Methods summary
Name get
Summary
5.68.1. get GET
143
Red Hat Virtualization 4.0 REST API Guide
Table 5.197. Parameters summary
Name Type Direction certific ate
Out
Summary
5.69. EXTERNALPROVIDERCERTIFICATES
Table 5.198. Methods summary
Name list
Summary
5.69.1. list GET
Table 5.199. Parameters summary
Name Type Direction certific ates
Out
max
In
Summary
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
Name add
CHAPTER 5. SERVICES
Summary
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 import
Type Direction
In/Out
Summary
5.71. FENCEAGENT
Table 5.202. Methods summary
145
Red Hat Virtualization 4.0 REST API Guide
Name get
Summary remove update
5.71.1. get GET
Table 5.203. Parameters summary
Name agent
Type
Direction
Out
5.71.2. remove DELETE
Table 5.204. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
146
5.71.3. update PUT
Table 5.205. Parameters summary
Name agent
Type
Direction
In/Out
async
In
Summary
Indicates if the update should be performed asynchronously.
CHAPTER 5. SERVICES
Name Type Direction Summary
5.72. FENCEAGENTS
Table 5.206. Methods summary
Name add
Summary list
5.72.1. add POST
Table 5.207. Parameters summary
Name agent
Type
Direction
In/Out
Summary
5.72.2. list GET
Table 5.208. Parameters summary
Name agents
Type
Direction
Out
max
In
Summary
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 get
Summary
5.73.1. get GET
Table 5.210. Parameters summary
Name file
Type
Direction
Out
Summary
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 list
Summary
5.74.1. list GET
Table 5.212. Parameters summary
148
Name Type case_sen sitive
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
file max
search
Out
In
In
Sets the maximum number of files to return.
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 get
Summary remove
5.75.1. get GET
Table 5.214. Parameters summary
149
Red Hat Virtualization 4.0 REST API Guide
Name filter
Type
Direction
In
result
Out
5.75.2. remove DELETE
Table 5.215. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
Summary
Indicates if the remove should be performed asynchronously.
5.76. FILTERS
Table 5.216. Methods summary
Name add
Summary list
5.76.1. add POST
Table 5.217. Parameters summary
Name filter
Type
Direction
In/Out
150
5.76.2. list GET
Summary
CHAPTER 5. SERVICES
Table 5.218. Parameters summary
Name filter
Type
Direction
In
Out
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
filters
max
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 get
Summary
Get details of a brick.
Removes a brick.
remove 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 brick
Type Direction
Out
Summary
152
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
instead.
For example, to delete brick 234 from gluster volume 123, send a request like this:
CHAPTER 5. SERVICES
DELETE /ovirtengine/api/clusters/567/glustervolumes/123/glusterbricks/234
Table 5.221. Parameters summary
Name async
Type
Direction
In
Summary
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
instead.
Table 5.222. Parameters summary
Name async force
Type
Direction
In
In
Summary
Indicates if the replacement should be performed asynchronously.
5.78. GLUSTERBRICKS
This service manages the gluster bricks in a gluster volume
Table 5.223. Methods summary
Name activate
Summary
Activate the bricks post data migration of remove brick operation.
153
Red Hat Virtualization 4.0 REST API Guide
Name add
Summary
Adds a list of bricks to gluster volume.
Lists the bricks of a gluster volume.
list 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 /ovirtengine/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 async
Type
Direction
In
Summary
Indicates if the activation should be performed asynchronously.
154
Name bricks
Type Direction
In
CHAPTER 5. SERVICES
Summary
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 bricks
Type Direction
In/Out
Summary
The list of bricks to be added to the volume
In Replica count of volume post add operation.
replica_ count
stripe_c ount
In Stripe count of volume post add operation.
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 bricks
Type Direction
Out
Summary max
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.
156
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
. 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 /ovirtengine/api/clusters/567/glustervolumes/123/glusterbricks/migrate
With a request body like this:
<action>
<bricks>
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
Table 5.227. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the migration should be performed asynchronously.
bricks
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
157
Red Hat Virtualization 4.0 REST API Guide
Name bricks
Type Direction
In
Summary
The list of bricks to be removed
replica_ count
In Replica count of volume post add operation.
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 /ovirtengine/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 async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
bricks
In List of bricks for which data migration needs to be stopped.
158
5.78.6.1. bricks
List of bricks for which data migration needs to be stopped. This list should match the arguments passed to
.
CHAPTER 5. SERVICES
5.79. GLUSTERHOOK
Table 5.230. Methods summary
Name disable
Summary
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 resolve
Removes the this Gluster hook from all servers in cluster and deletes it from the database.
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
5.79.3. get GET
Table 5.233. Parameters summary
Name hook
Type Direction
Out
Summary
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 async
Type
Direction
In
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the action should be performed asynchronously.
host
resoluti on_type
In
In
5.80. GLUSTERHOOKS
Table 5.236. Methods summary
Name list
Summary
5.80.1. list GET
Table 5.237. Parameters summary
Name hooks
Type Direction
Out
max
In
Summary
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 get
Summary
Get the gluster volume details.
getprofilest atistics
Get gluster volume profile statistics.
rebalance
Rebalance the gluster volume.
remove
Removes the gluster volume.
resetallopti ons
Resets all the options set in the gluster volume.
resetoption
Resets a particular option in the gluster volume.
setoption start
Sets a particular option in the gluster volume.
Starts the gluster volume.
startprofile
Start profiling the gluster volume.
stop
Stops the gluster volume.
stopprofile
Stop profiling the gluster volume.
stoprebalanc e
Stop rebalancing the gluster volume.
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= "/ovirtengine/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 volume
Type Direction
Out
Summary
Representation of the gluster volume.
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 /ovirtengine/api/clusters/456/glustervolumes/123/getprofilestatistics
Table 5.240. Parameters summary
Name Type Direction details
Out
Summary
Gluster volume profiling information returned from the action.
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 async
Type
Direction
In
Summary
Indicates if the rebalance should be performed asynchronously.
fix_layo ut
In
force
In
If set to true, rebalance will only fix the layout so that new data added to the volume is distributed across all the hosts.
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the reset should be performed asynchronously.
force
In
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 async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
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 async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
force
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
force
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 async
Type
Direction
In
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
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 add
Summary
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 volume
Type Direction
In/Out
Summary
The gluster volume definition from which to create 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 case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
In Sets the maximum number of volumes to return.
max
search
In A query string used to restrict the returned volumes.
volumes
Out
170
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.
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 get remove
Summary
Gets the configuration of the graphics console.
5.83.1. get GET
Gets the configuration of the graphics console.
Table 5.255. Parameters summary
Name Type Direction console
Out
Summary current
In Use the following query to obtain the current runtime 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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.84. GRAPHICSCONSOLES
Table 5.257. Methods summary
Name add
Summary list
Lists all the configured graphics consoles of the virtual machine.
5.84.1. add POST
Table 5.258. Parameters summary
Name Type Direction console
In/Out
Summary
5.84.2. list GET
Lists all the configured graphics consoles of the virtual machine.
Table 5.259. Parameters summary
Name Type Direction consoles
Out
Summary
172
Name Type current
Direction
In
CHAPTER 5. SERVICES
Summary
Use the following query to obtain the current runtime configuration of the graphics consoles.
max
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 get
Summary remove
5.85.1. get GET
Table 5.261. Parameters summary
Name get
Type
Direction
Out
5.85.2. remove DELETE
Summary
173
Red Hat Virtualization 4.0 REST API Guide
Table 5.262. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.86. GROUPS
Table 5.263. Methods summary
Name add
Summary
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 group
Type
Direction
In/Out
Summary
174
CHAPTER 5. SERVICES
5.86.2. list GET
Table 5.265. Parameters summary
Name Type case_sen sitive
Direction
In
groups
max
search
Out
In
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
Sets the maximum number of groups to return.
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 activate
Summary
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 fig
Marks the network configuration as good and persists it inside the host.
deactivate
Deactivate the host to perform maintenance tasks.
enrollcertif icate
Enroll certificate of the host.
fence
Controls host’s power management device.
forceselects pm
Manually set a host as the storage pool manager (SPM).
Get the host details.
get install
Install VDSM and related software on the host.
iscsidiscove r
Discover iSCSI targets on the host, using the initiator details.
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 s
This method is used to change the configuration of the network interfaces of a host.
unregistered storagedomai nsdiscover
176
CHAPTER 5. SERVICES
Name update upgrade
Summary
Update the host properties.
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 async
Type
Direction
In
Summary
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 async
Type
cluster
Direction
In
In
Summary
Indicates if the approval should be performed asynchronously.
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the deactivation should be performed asynchronously.
reason
In
stop_glu ster_ser vice
In Indicates if the gluster service should be stopped as part of deactivating the host.
5.87.4.1. stop_gluster_service
178
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
CHAPTER 5. SERVICES
Name async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the fencing should be performed asynchronously.
fence_ty pe
In
power_ma nagement
Out
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 async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
5.87.8. get GET
Get the host details.
Table 5.274. Parameters summary
Name filter
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
180
CHAPTER 5. SERVICES
Name host
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
Indicates if the installation should be performed asynchronously.
deploy_h osted_en gine
In
host
In
image
In
root_pas sword
ssh
In
In
undeploy
_hosted_ engine
In
When set to
true
it means this host should deploy also hosted engine components.
This
override_iptables
property is used to indicate if the firewall configuration should be replaced by the default one.
When installing an oVirt node a image ISO file is needed.
The password of of the
root
user, used to connect to the host via SSH.
The SSH details used to connect to the host.
When set to
true
it means this host should undeploy hosted engine components and this host will not function as part of the High Availability cluster.
182
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.
CHAPTER 5. SERVICES
Table 5.276. Parameters summary
Name async
Type
Direction
In
iscsi
In
iscsi_ta rgets
Out
Summary
Indicates if the discovery should be performed asynchronously.
The target iSCSI device.
The iSCSI targets.
5.87.11. iscsilogin POST
Login to iSCSI targets on the host, using the target details.
Table 5.277. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the login should be performed asynchronously.
iscsi
In The target iSCSI device.
5.87.12. refresh POST
Refresh the host devices and capabilities.
Table 5.278. Parameters summary
Name async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
184
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>
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
Name async
Type
Direction
In
check_co nnectivi ty
In
connecti vity_tim eout
In
modified
_bonds
In
modified
_labels
In
modified
_network
_attachm ents
In
removed_ bonds
In
removed_ labels
In
removed_ network_ attachme nts
In
synchron ized_net work_att achments
In
CHAPTER 5. SERVICES
Summary
Indicates if the action should be performed asynchronously.
187
Red Hat Virtualization 4.0 REST API Guide
5.87.15. unregisteredstoragedomainsdiscover POST
Table 5.281. Parameters summary
Name async iscsi
Type
Direction
In
In
Summary
Indicates if the discovery should be performed asynchronously.
storage_ domains
Out
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
host
In/Out
188
5.87.17. upgrade POST
CHAPTER 5. SERVICES
Upgrade VDSM and selected software on the host.
Table 5.283. Parameters summary
Name async
Type
Direction
In
Summary
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 get
Summary
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 device
Type Direction
Out
Summary
189
Red Hat Virtualization 4.0 REST API Guide
5.89. HOSTDEVICES
A service to access host devices.
Table 5.286. Methods summary
Name list
Summary
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 devices
Out
max
In
Summary
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 get
Summary
5.90.1. get GET
Table 5.289. Parameters summary
190
CHAPTER 5. SERVICES
Name hook
Type
Direction
Out
Summary
5.91. HOSTHOOKS
Table 5.290. Methods summary
Name list
Summary
5.91.1. list GET
Table 5.291. Parameters summary
Name hooks
Type
Direction
Out
max
In
Summary
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 get
Summary
191
Red Hat Virtualization 4.0 REST API Guide
Name Summary updatevirtua lfunctionsco nfiguration
The action updates virtual function configuration in case the current resource represents an SR-IOV enabled NIC.
5.92.1. get GET
Table 5.293. Parameters summary
Name nic
Type
Direction
Out
Summary
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 async
Type
virtual_ function s_config uration
In
Direction
In
Summary
Indicates if the update should be performed asynchronously.
192
5.93. HOSTNICS
A service to manage the network interfaces of a host.
CHAPTER 5. SERVICES
Table 5.295. Methods summary
Name list
Summary
5.93.1. list GET
Table 5.296. Parameters summary
Name max
Type
Direction
In
nics
Out
Summary
Sets the maximum number of NICs to return.
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 get
Summary
5.94.1. get GET
Table 5.298. Parameters summary
Name node
Type Direction
Out
Summary
193
Red Hat Virtualization 4.0 REST API Guide
5.95. HOSTNUMANODES
Table 5.299. Methods summary
Name list
Summary
5.95.1. list GET
Table 5.300. Parameters summary
Name max
Type
Direction
In
nodes
Out
Summary
Sets the maximum number of nodes to return.
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 list
Summary
Get list of storages.
194
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:
CHAPTER 5. SERVICES
<host_storages>
<host_storage id= "123" >
...
</host_storage>
...
</host_storages>
Table 5.302. Parameters summary
Name Type report_s tatus
Direction
In
storages
Out
Summary
Indicates if the status of the LUNs in the storage should be checked.
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 add
Summary
Creates a new host.
list
Get a list of all available hosts.
196
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.
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 deploy_h osted_en gine
Direction
In
Summary
When set to
true
it means this host should deploy also hosted engine components.
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
_hosted_ engine
In When set to
true
it means this host should undeploy hosted engine components and this host 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 case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
filter
In Indicates if the results should be filtered according to the permissions of the user.
hosts max
search
Out
In
In
Sets the maximum number of hosts to return.
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
Name get
Summary
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 icon
Type
Direction
Out
Summary
Retrieved icon.
5.99. ICONS
A service to manage icons.
Table 5.308. Methods summary
Name list
Summary
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>
CHAPTER 5. SERVICES
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 icons
Type
Direction
Out
Summary
Retrieved list of icons.
max
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 get
Summary import
5.100.1. get GET
Table 5.311. Parameters summary
Name image
Type
Direction
Out
Summary
200
5.100.2. import POST
CHAPTER 5. SERVICES
Table 5.312. Parameters summary
Name async
Type
Direction
In
cluster
disk
In
In
import_a s_templa te
In
storage_ domain
In
template
In
Summary
Indicates if the import should be performed asynchronously.
Cluster where the image should be imported.
The disk which should be imported.
Specify if template should be created from the imported disk.
Storage domain where disk should be imported.
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
.
After adding a new transfer, its phase will be
, 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.
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
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
, 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
CHAPTER 5. SERVICES
Name extend
Summary
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 get
Summary
Get the image transfer entity.
Pause the image transfer session.
pause 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 image_tr ansfer
Out
Summary
204
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()
CHAPTER 5. SERVICES
while transfer.phase == types.ImageTransferPhase.RESUMING:
time.sleep( 1 )
transfer = transfer_service.get()
5.102. IMAGETRANSFERS
Table 5.315. Methods summary
Name add
Summary
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 image_tr ansfer
In/Out
Summary
5.102.2. list GET
Retrieves the list of image transfers that are currently being performed.
Table 5.317. Parameters summary
Name Type Direction image_tr ansfer
Out
Summary
205
Red Hat Virtualization 4.0 REST API Guide
5.103. IMAGES
Table 5.318. Methods summary
Name list
Summary
5.103.1. list GET
Table 5.319. Parameters summary
Name images
Type
Direction
Out
max
In
Summary
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 get
Summary
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.
206
5.104.1. get GET
Get a specific instance type and it’s attributes.
CHAPTER 5. SERVICES
GET /ovirt-engine/api/instancetypes/123
Table 5.321. Parameters summary
Name Type Direction instance
_type
Out
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
instance
_type
In/Out
5.105. INSTANCETYPENIC
Table 5.324. Methods summary
Name get
Summary
Gets network interface configuration of the instance type.
Remove the network interface from the instance type.
remove 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 nic
Type
Direction
Out
Summary
208
CHAPTER 5. SERVICES
5.105.2. remove DELETE
Remove the network interface from the instance type.
Table 5.326. Parameters summary
Name async
Type
Direction
In
Summary
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 async nic
Type
Direction
In
In/Out
Summary
Indicates if the update should be performed asynchronously.
5.106. INSTANCETYPENICS
Table 5.328. Methods summary
Name add
Summary
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 nic
Type
Direction
In/Out
Summary
5.106.2. list GET
Lists all the configured network interface of the instance type.
Table 5.330. Parameters summary
Name max
Type
Direction
In
Summary
Sets the maximum number of NICs to return.
nics
Out
search
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 get
Summary
Gets watchdog configuration of the instance type.
Remove a watchdog from the instance type.
remove update
Updates the watchdog configuration of the instance type.
210
5.107.1. get GET
CHAPTER 5. SERVICES
Gets watchdog configuration of the instance type.
Table 5.332. Parameters summary
Name Type Direction watchdog
Out
Summary
5.107.2. remove DELETE
Remove a watchdog from the instance type.
Table 5.333. Parameters summary
Name async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
watchdog
In/Out
5.108. INSTANCETYPEWATCHDOGS
Table 5.335. Methods summary
211
Red Hat Virtualization 4.0 REST API Guide
Name add
Summary
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 watchdog
In/Out
Summary
5.108.2. list GET
Lists all the configured watchdogs of the instance type.
Table 5.337. Parameters summary
Name max
Type
Direction
In
Summary
Sets the maximum number of watchdogs to return.
search
In A query string used to restrict the returned templates.
watchdog s
Out
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 add
Summary
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 instance
_type
In/Out
Summary
5.109.2. list GET
Lists all existing instance types in the system.
Table 5.340. Parameters summary
214
Name Type case_sen sitive
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
instance
_type
Out
max
In
search
In
Sets the maximum number of instance types to return.
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 get
Summary 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 bond
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
216
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
CHAPTER 5. SERVICES
Name bond
Type
Direction
In/Out
Summary
5.111. ISCSIBONDS
Table 5.345. Methods summary
Name add
Summary
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 bond
Type
Direction
In/Out
Summary
217
Red Hat Virtualization 4.0 REST API Guide
5.111.2. list GET
Table 5.347. Parameters summary
Name bonds
Type Direction
Out
max
In
Summary
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 clear
Summary
Set an external job execution to be cleared by the system.
Marks an external job execution as ended.
end 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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
force
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 job
Type
Direction
Out
Summary
Retrieves the representation of the job.
5.113. JOBS
A service to manage jobs.
Table 5.352. Methods summary
Name add
Summary
Add an external job.
list
Retrieves the representation of the jobs.
220
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:
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 job
Type
Direction
In/Out
Summary
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 jobs
Type
Direction
Out
max
In
Summary
A representation of jobs.
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 list
Summary
Retrieves the representation of the Katello errata.
222
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>
...
CHAPTER 5. SERVICES
</katello_errata>
Table 5.356. Parameters summary
Name errata
Type Direction
Out
max
In
Summary
A representation of Katello errata.
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 get
Summary
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 erratum
Out
Summary
Retrieves the representation of the Katello erratum.
5.116. MACPOOL
Table 5.359. Methods summary
Name get
Summary remove
Removes a MAC address pool.
update
Updates a MAC address pool.
5.116.1. get GET
Table 5.360. Parameters summary
Name pool
Type
Direction
Out
Summary
224
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:
CHAPTER 5. SERVICES
DELETE /ovirt-engine/api/macpools/123
Table 5.361. Parameters summary
Name async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
pool
In/Out
225
Red Hat Virtualization 4.0 REST API Guide
5.117. MACPOOLS
Table 5.363. Methods summary
Name add
Summary
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 pool
Type
Direction
In/Out
Summary
226
5.117.2. list GET
Table 5.365. Parameters summary
Name max pools
Type
Direction
In
Out
CHAPTER 5. SERVICES
Summary
Sets the maximum number of pools to return.
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 move
Summary
5.119.1. move POST
Table 5.367. Parameters summary
Name async
Type
Direction
In
Summary
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 get
Summary
Gets a logical network.
Removes a logical network, or the association of a logical network to a data center.
remove 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 network
Direction
Out
Summary
228
5.120.2. remove DELETE
Removes a logical network, or the association of a logical network to a data center.
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
network
In/Out
5.121. NETWORKATTACHMENT
Table 5.372. Methods summary
Name get
Summary remove update
5.121.1. get GET
Table 5.373. Parameters summary
Name Type Direction attachme nt
Out
5.121.2. remove DELETE
Table 5.374. Parameters summary
Name Type Direction
Summary
Summary
230
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the remove should be performed asynchronously.
5.121.3. update PUT
Table 5.375. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
attachme nt
In/Out
5.122. NETWORKATTACHMENTS
Table 5.376. Methods summary
Name add
Summary list
5.122.1. add POST
Table 5.377. Parameters summary
Name Type Direction attachme nt
In/Out
Summary
231
Red Hat Virtualization 4.0 REST API Guide
5.122.2. list GET
Table 5.378. Parameters summary
Name Type Direction attachme nts
Out
max
In
Summary
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 get
Summary
Retrieves a representation of the network filter.
232
5.123.1. get GET
Retrieves a representation of the network filter.
Table 5.380. Parameters summary
CHAPTER 5. SERVICES
Name Type Direction network_ filter
Out
Summary
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/ovirtengine/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 list
Summary
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 filters
Out
Summary
5.125. NETWORKLABEL
Table 5.383. Methods summary
Name get
Summary remove
Removes a label from a logical network.
5.125.1. get GET
234
Table 5.384. Parameters summary
CHAPTER 5. SERVICES
Name label
Type Direction
Out
Summary
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.126. NETWORKLABELS
Table 5.386. Methods summary
Name add list
Summary
Attaches label to logical network.
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 label
Type Direction
In/Out
Summary
5.126.2. list GET
Table 5.388. Parameters summary
Name labels
Type Direction
Out
max
In
Summary
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 add
Summary
Creates a new logical network, or associates an existing network with a data center.
236
CHAPTER 5. SERVICES
Name list
Summary
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 network
Direction
In/Out
Summary
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 case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
max
In
networks
Out
search
In
Sets the maximum number of networks to return.
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.
238
5.128. OPENSTACKIMAGE
5.128. OPENSTACKIMAGE
Table 5.392. Methods summary
Name get
Summary import
Imports a virtual machine from a Glance image storage domain.
CHAPTER 5. SERVICES
5.128.1. get GET
Table 5.393. Parameters summary
Name image
Type Direction
Out
Summary
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 async
Type
Direction
In
cluster
In
Summary
Indicates if the import should be performed asynchronously.
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
In
import_a s_templa te
In
storage_ domain
In
template
In
Indicates whether the image should be imported as a template.
5.129. OPENSTACKIMAGEPROVIDER
Table 5.395. Methods summary
Name get importcertif icates
Summary remove testconnecti vity
240
CHAPTER 5. SERVICES
Name update
Summary
5.129.1. get GET
Table 5.396. Parameters summary
Name Type Direction provider
Out
5.129.2. importcertificates POST
Table 5.397. Parameters summary
Name Type Direction certific ates
In
5.129.3. remove DELETE
Table 5.398. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Summary
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 async
Type
Direction
In
Summary
Indicates if the test should be performed asynchronously.
5.129.5. update PUT
Table 5.400. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
provider
In/Out
5.130. OPENSTACKIMAGEPROVIDERS
Table 5.401. Methods summary
Name add
Summary list
5.130.1. add POST
Table 5.402. Parameters summary
Name Type Direction Summary
242
CHAPTER 5. SERVICES
Name Type Direction provider
In/Out
5.130.2. list GET
Table 5.403. Parameters summary
Name max
Type
Direction
In
provider s
Out
Summary
Summary
Sets the maximum number of providers to return.
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 list
Summary
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 images
Type Direction
Out
max
In
Summary
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 get
Summary import
This operation imports an external network into oVirt.
5.132.1. get GET
Table 5.407. Parameters summary
Name Type Direction network
Out
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the import should be performed asynchronously.
The data center into which the network is to be imported.
data_cen ter
In
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 importcertif icates
Returns the representation of the object managed by this service.
remove testconnecti vity
Removes the provider.
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 provider
Out
Summary
5.133.2. importcertificates POST
Table 5.411. Parameters summary
Name Type Direction certific ates
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.133.4. testconnectivity POST
Table 5.413. Parameters summary
246
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
provider
In/Out The provider to update.
5.134. OPENSTACKNETWORKPROVIDERS
This service manages OpenStack network providers.
Table 5.415. Methods summary
247
Red Hat Virtualization 4.0 REST API Guide
Name add list
Summary
The operation adds a new network provider to the system.
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 provider
In/Out
Summary
5.134.2. list GET
Table 5.417. Parameters summary
Name max
Type
Direction
In
provider s
Out
Summary
Sets the maximum number of providers to return.
248
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
CHAPTER 5. SERVICES
Name list
Summary
5.135.1. list GET
Table 5.419. Parameters summary
Name max
Type
Direction
In
networks
Out
Summary
Sets the maximum number of networks to return.
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 get
Summary 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 subnet
Type Direction
Out
5.136.2. remove DELETE
Table 5.422. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.137. OPENSTACKSUBNETS
Table 5.423. Methods summary
Name add
Summary list
5.137.1. add POST
Table 5.424. Parameters summary
Name subnet
Type Direction
In/Out
Summary
250
5.137.2. list GET
Table 5.425. Parameters summary
Name max
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Sets the maximum number of sub-networks to return.
subnets
Out
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 get
Summary remove update
5.138.1. get GET
Table 5.427. Parameters summary
Name key
Type Direction
OpenstackV olumeAuthe nticationKey
Out
Summary
5.138.2. remove DELETE
Table 5.428. Parameters summary
251
Red Hat Virtualization 4.0 REST API Guide
Name async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.138.3. update PUT
Table 5.429. Parameters summary
Name key
Type Direction
OpenstackV olumeAuthe nticationKey
In/Out
Summary
5.139. OPENSTACKVOLUMEAUTHENTICATIONKEYS
Table 5.430. Methods summary
Name add
Summary list
5.139.1. add POST
Table 5.431. Parameters summary
Name key
Type Direction
OpenstackV olumeAuthe nticationKey
In/Out
Summary
252
5.139.2. list GET
CHAPTER 5. SERVICES
Table 5.432. Parameters summary
Name keys
Type Direction
Out
max
In
Summary
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 get importcertif icates remove
Summary 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 provider
Out
5.140.2. importcertificates POST
Table 5.435. Parameters summary
Name Type Direction certific ates
In
5.140.3. remove DELETE
Table 5.436. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.140.4. testconnectivity POST
Table 5.437. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the test should be performed asynchronously.
5.140.5. update PUT
Table 5.438. Parameters summary
254
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the update should be performed asynchronously.
provider
In/Out
5.141. OPENSTACKVOLUMEPROVIDERS
Table 5.439. Methods summary
Name add
Summary
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 provider
In/Out
5.141.2. list GET
Retrieves the list of volume providers.
Table 5.441. Parameters summary
Name max
Type
Direction
In
provider s
Out
Summary
Summary
Sets the maximum number of providers to return.
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 get
Summary
5.142.1. get GET
Table 5.443. Parameters summary
256
CHAPTER 5. SERVICES
Name type
Type Direction
Out
Summary
5.143. OPENSTACKVOLUMETYPES
Table 5.444. Methods summary
Name list
Summary
5.143.1. list GET
Table 5.445. Parameters summary
Name max
Type
Direction
In
Summary
Sets the maximum number of volume types to return.
types
Out
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 get
Summary
257
Red Hat Virtualization 4.0 REST API Guide
5.144.1. get GET
Table 5.447. Parameters summary
Name Type Direction operatin g_system
Out
Summary
5.145. OPERATINGSYSTEMS
Table 5.448. Methods summary
Name list
Summary
5.145.1. list GET
Table 5.449. Parameters summary
Name max
Type
Direction
In
operatin g_system
Out
Summary
Sets the maximum number of networks to return.
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 get
Summary remove
5.146.1. get GET
Table 5.451. Parameters summary
Name Type Direction permissi on
Out
5.146.2. remove DELETE
Table 5.452. Parameters summary
Name async
Type
Direction
In
Summary
Summary
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 get
Summary
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 permit
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
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 add list
Summary
Adds a permit to the role.
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
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 permit
Type
Direction
In/Out
Summary
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 max
Type
Direction
In
Summary
Sets the maximum number of permits to return.
permits
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 get
Summary remove update
5.149.1. get GET
Table 5.460. Parameters summary
Name qos
Type
Direction
Out
Summary
262
CHAPTER 5. SERVICES
5.149.2. remove DELETE
Table 5.461. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.149.3. update PUT
Table 5.462. Parameters summary
Name async
Type
Direction
In
qos
In/Out
5.150. QOSS
Table 5.463. Methods summary
Name add
Summary list
5.150.1. add POST
Table 5.464. Parameters summary
Summary
Indicates if the update should be performed asynchronously.
263
Red Hat Virtualization 4.0 REST API Guide
Name qos
Type
Direction
In/Out
5.150.2. list GET
Table 5.465. Parameters summary
Name max
Type
Direction
In
Summary
Summary
Sets the maximum number of QoS descriptors to return.
qoss
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 get
Summary
Retrieves a quota.
Delete a quota.
remove 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 quota
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
quota
In/Out
5.152. QUOTACLUSTERLIMIT
Table 5.470. Methods summary
Name get
Summary remove
5.152.1. get GET
Table 5.471. Parameters summary
Name limit
Type Direction
Out
Summary
5.152.2. remove DELETE
Table 5.472. Parameters summary
266
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the remove should be performed asynchronously.
5.153. QUOTACLUSTERLIMITS
Table 5.473. Methods summary
Name add
Summary list
5.153.1. add POST
Table 5.474. Parameters summary
Name limit
Type Direction
In/Out
Summary
5.153.2. list GET
Table 5.475. Parameters summary
Name limits
Type Direction
Out
max
In
5.153.2.1. max
Summary
Sets the maximum number of limits to return.
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 get
Summary remove
5.154.1. get GET
Table 5.477. Parameters summary
Name limit
Type Direction
Out
Summary
5.154.2. remove DELETE
Table 5.478. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
5.155. QUOTASTORAGELIMITS
Table 5.479. Methods summary
268
CHAPTER 5. SERVICES
Name add list
Summary
5.155.1. add POST
Table 5.480. Parameters summary
Name limit
Type Direction
In/Out
Summary
5.155.2. list GET
Table 5.481. Parameters summary
Name limits
Type Direction
Out
max
In
Summary
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 add
Summary
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 quota
Type
Direction
In/Out
Summary
5.156.2. list GET
Lists quotas of a data center
Table 5.484. Parameters summary
Name max
Type
Direction
In
Summary
Sets the maximum number of quota descriptors to return.
quotas
Out
270
5.156.2.1. max
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 get
Summary
Get the role.
Removes the role.
remove 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 role
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
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 add list
Summary
Create a new role.
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 role
Type
Direction
In/Out
Summary
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 max
Type
Direction
In
Summary
Sets the maximum number of roles to return.
roles
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 add
Summary list
5.159.1. add POST
Table 5.493. Parameters summary
Name policy
Type Direction
In/Out
Summary
274
CHAPTER 5. SERVICES
5.159.2. list GET
Table 5.494. Parameters summary
Name filter
Type
Direction
In
max
In
policies
Out
Summary
Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of policies to return.
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 get
Summary remove update
5.160.1. get GET
Table 5.496. Parameters summary
275
Red Hat Virtualization 4.0 REST API Guide
Name filter
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
policy
Out
5.160.2. remove DELETE
Table 5.497. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.160.3. update PUT
Table 5.498. Parameters summary
Name async
Type
Direction
In
policy
In/Out
5.161. SCHEDULINGPOLICYUNIT
Table 5.499. Methods summary
Name get
Summary
Summary
Indicates if the update should be performed asynchronously.
276
CHAPTER 5. SERVICES
Name remove
Summary
5.161.1. get GET
Table 5.500. Parameters summary
Name filter
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
unit
Out
5.161.2. remove DELETE
Table 5.501. Parameters summary
Name async
Type
Direction
In
5.162. SCHEDULINGPOLICYUNITS
Table 5.502. Methods summary
Name list
Summary
5.162.1. list GET
Table 5.503. Parameters summary
Summary
Indicates if the remove should be performed asynchronously.
277
Red Hat Virtualization 4.0 REST API Guide
Name filter
Type
Direction
In
max units
In
Out
Summary
Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of policy units to return.
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 get
Summary remove restore
Restores a virtual machine snapshot.
5.163.1. get GET
Table 5.505. Parameters summary
Name Type snapshot
Direction
Out
5.163.2. remove DELETE
Summary
278
CHAPTER 5. SERVICES
Table 5.506. Parameters summary
Name async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the restore should be performed asynchronously.
disks
In
restore_ memory
In
5.164. SNAPSHOTCDROM
Table 5.508. Methods summary
Name get
Summary
279
Red Hat Virtualization 4.0 REST API Guide
5.164.1. get GET
Table 5.509. Parameters summary
Name cdrom
Type
Direction
Out
Summary
5.165. SNAPSHOTCDROMS
Table 5.510. Methods summary
Name list
Summary
5.165.1. list GET
Table 5.511. Parameters summary
Name cdroms
Type
Direction
Out
max
In
Summary
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 get
Summary
5.166.1. get GET
Table 5.513. Parameters summary
Name disk
Type
Direction
Out
Summary
5.167. SNAPSHOTDISKS
Table 5.514. Methods summary
Name list
Summary
5.167.1. list GET
Table 5.515. Parameters summary
Name disks
Type
Direction
Out
max
In
Summary
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 get
Summary
5.168.1. get GET
Table 5.517. Parameters summary
Name nic
Type
Direction
Out
Summary
5.169. SNAPSHOTNICS
Table 5.518. Methods summary
Name list
Summary
5.169.1. list GET
Table 5.519. Parameters summary
Name max
Type
Direction
In
nics
Out
Summary
Sets the maximum number of NICs to return.
5.169.1.1. max
Sets the maximum number of NICs to return. If not specified all the NICs are returned.
282
5.170. SNAPSHOTS
CHAPTER 5. SERVICES
5.170. SNAPSHOTS
Table 5.520. Methods summary
Name add
Summary
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 snapshot
Direction
In/Out
Summary
5.170.2. list GET
Table 5.522. Parameters summary
Name max
Type
Direction
In
snapshot s
Out
Summary
Sets the maximum number of snapshots to return.
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 get
Summary remove update
5.171.1. get GET
Table 5.524. Parameters summary
Name key
Type Direction
Out
Summary
5.171.2. remove DELETE
Table 5.525. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
284
5.171.3. update PUT
Table 5.526. Parameters summary
Name async
Type
Direction
In
key
In/Out
5.172. SSHPUBLICKEYS
Table 5.527. Methods summary
Name add
Summary list
5.172.1. add POST
Table 5.528. Parameters summary
Name key
Type Direction
In/Out
5.172.2. list GET
Table 5.529. Parameters summary
Name keys
Type Direction
Out
CHAPTER 5. SERVICES
Summary
Indicates if the update should be performed asynchronously.
Summary
Summary
285
Red Hat Virtualization 4.0 REST API Guide
Name max
Type
Direction
In
Summary
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 get
Summary
5.173.1. get GET
Table 5.531. Parameters summary
Name Type statisti c
Direction
In/Out
Summary
5.174. STATISTICS
Table 5.532. Methods summary
Name list
Summary
Retrieves a list of statistics.
286
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:
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
CHAPTER 5. SERVICES
Name max
Type
Direction
In
Summary
Sets the maximum number of statistics to return.
287
Red Hat Virtualization 4.0 REST API Guide
Name Type statisti cs
Direction
Out
Summary
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 end
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the action should be performed asynchronously.
Indicates if the step should be forcibly terminated.
Indicates the resolution of the step execution.
force
In
succeede d
In
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 step
Type
Direction
Out
Summary
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 add
Summary
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 step
Type
Direction
In/Out
Summary
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 max
Type
Direction
In
Summary
Sets the maximum number of steps to return.
steps
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 get
Summary
291
Red Hat Virtualization 4.0 REST API Guide
5.177.1. get GET
Table 5.541. Parameters summary
Name Type report_s tatus
Direction
In
storage
Out
Summary
Indicates if the status of the LUNs in the storage should be checked.
292
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>
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 get isattached
Summary refreshluns
This operation refreshes the LUN size.
remove
Removes the storage domain.
update
Updates a storage domain.
updateovfsto re
This operation forces the update of the
OVF_STORE
of this storage domain.
5.178.1. get GET
Table 5.543. Parameters summary
Name filter
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
storage_ domain
Out
293
Red Hat Virtualization 4.0 REST API Guide
Name Type Direction Summary
294
5.178.2. isattached POST
Table 5.544. Parameters summary
Name async
Type
Direction
In
host
In
is_attac hed
Out
Summary
Indicates if the action should be performed asynchronously.
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-9666b883eff59d40/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
Name async
Type
Direction
In
logical_ units
In
CHAPTER 5. SERVICES
Summary
Indicates if the refresh should be performed asynchronously.
The LUNs that need to be refreshed.
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
destroy
In
format
In
Indicates if the operation should succeed, and the storage domain removed from the database, even if the storage isn’t accessible.
Indicates if the actual storage should be formatted, removing all the metadata from the underlying LUN or directory:
[source] ---- DELETE /ovirtengine/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 host
Type
Direction
In
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the update should be performed asynchronously.
storage_ domain
In/Out
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 async
Type
Direction
In
Summary
Indicates if the
OVF_STORE
update should be performed asynchronously.
5.179. STORAGEDOMAINCONTENTDISK
Table 5.549. Methods summary
Name get
Summary
5.179.1. get GET
Table 5.550. Parameters summary
297
Red Hat Virtualization 4.0 REST API Guide
Name disk
Type
Direction
Out
filter
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
5.180. STORAGEDOMAINCONTENTDISKS
Table 5.551. Methods summary
Name list
Summary
5.180.1. list GET
Table 5.552. Parameters summary
Name Type case_sen sitive
Direction
In
disks
max
search
Out
In
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
Sets the maximum number of disks to return.
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.
298
5.180.1.2. max
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 get
Summary remove
Detaches a storage connection from storage.
5.181.1. get GET
Table 5.554. Parameters summary
Name Type Direction connecti on
Out
Summary
5.181.2. remove DELETE
Detaches a storage connection from storage.
Table 5.555. Parameters summary
Name async
Type
Direction
In
Summary
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 add
Summary list
5.182.1. add POST
Table 5.557. Parameters summary
Name Type Direction connecti on
In/Out
5.182.2. list GET
Table 5.558. Parameters summary
Name Type Direction connecti ons
Out
max
In
Summary
Summary
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 get import register remove
Summary
5.183.1. get GET
Table 5.560. Parameters summary
Name Type template
Direction
Out
5.183.2. import POST
Table 5.561. Parameters summary
Name async
Type
Direction
In
clone
In
cluster
In
exclusiv e
In
Summary
Summary
Indicates if the import should be performed asynchronously.
301
Red Hat Virtualization 4.0 REST API Guide
Name Type Direction storage_ domain
In
Summary template
In
vm
In
5.183.3. register POST
Table 5.562. Parameters summary
Name async
Type
Direction
In
clone
In
cluster
In
exclusiv e
In
template
In
5.183.4. remove DELETE
Table 5.563. Parameters summary
Name Type Direction Summary
Summary
Indicates if the registration should be performed asynchronously.
302
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the remove should be performed asynchronously.
5.184. STORAGEDOMAINTEMPLATES
Table 5.564. Methods summary
Name list
Summary
5.184.1. list GET
Table 5.565. Parameters summary
Name max
Type
Direction
In
template s
Out
Summary
Sets the maximum number of templates to return.
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 get
Summary
303
Red Hat Virtualization 4.0 REST API Guide
Name import register
Summary
Imports a virtual machine from an export storage domain.
remove
Deletes a virtual machine from an export storage domain.
5.185.1. get GET
Table 5.567. Parameters summary
Name vm
Type
Direction
Out
Summary
304
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>
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 async
Type
Direction
In
Summary
Indicates if the import should be performed asynchronously.
clone
In Indicates if the identifiers of the imported virtual machine should be regenerated.
cluster
In
collapse
_snapsho ts
In
storage_ domain
In
vm
In
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.
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 async clone
Type
Direction
In
In
Summary
Indicates if the registration should be performed asynchronously.
cluster
In
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
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 get
Summary
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 attachme nt
Out
Summary
The disk attachment.
5.187. STORAGEDOMAINVMDISKATTACHMENTS
Returns the details of a disk attached to a virtual machine in the export domain.
Table 5.573. Methods summary
Name list
Summary
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 attachme nts
Out
Summary
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
collections, except they also contain a
action.
Table 5.575. Methods summary
Name list
Summary
5.188.1. list GET
Table 5.576. Parameters summary
308
Name max
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Sets the maximum number of virtual machines to return.
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 add
Summary
Adds a new storage domain.
list
5.189.1. add POST
Adds a new storage domain.
Creation of a new
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 storage_ domain
In/Out
Summary
310
5.189.2. list GET
Table 5.579. Parameters summary
Name Type case_sen sitive
Direction
In
filter
In
max
search
In
In
CHAPTER 5. SERVICES
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of storage domains to return.
A query string used to restrict the returned storage domains.
storage_ domains
Out
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 get
Summary remove
Removes a storage connection.
311
Red Hat Virtualization 4.0 REST API Guide
Name update
Summary
Updates the storage connection.
5.190.1. get GET
Table 5.581. Parameters summary
Name Type Direction conectio n
Out
Summary
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
host
In The name or identifier of the host from which the connection would be unmounted (disconnected).
312
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
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>
CHAPTER 5. SERVICES
Table 5.583. Parameters summary
Name async
Type
Direction
In
connecti on
In/Out
Summary
Indicates if the update should be performed asynchronously.
force
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 get
Summary
313
Red Hat Virtualization 4.0 REST API Guide
Name remove
Summary
314 update
Update a storage server connection extension for the given host.
5.191.1. get GET
Table 5.585. Parameters summary
Name Type Direction extensio n
Out
Summary
5.191.2. remove DELETE
Table 5.586. Parameters summary
Name async
Type
Direction
In
Summary
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>
CHAPTER 5. SERVICES
Table 5.587. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
extensio n
In/Out
5.192. STORAGESERVERCONNECTIONEXTENSIONS
Table 5.588. Methods summary
Name add
Summary
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 extensio n
In/Out
Summary
5.192.2. list GET
Table 5.590. Parameters summary
Name Type Direction extensio ns
StorageCon nectionExte nsion[]
Out
max
In
Summary
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 add
Summary
Creates a new storage connection.
list
316
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
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 connecti on
In/Out
Summary
5.193.2. list GET
Table 5.593. Parameters summary
Name Type Direction connecti ons
Out
max
In
Summary
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 get reloadconfig urations
Summary
Returns basic information describing the API, like the product name, the version number and a summary of the number of relevant objects.
318
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>
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 api
Type
Direction
Out
Summary
5.194.2. reloadconfigurations POST
Table 5.596. Parameters summary
Name Type Direction Summary
319
Red Hat Virtualization 4.0 REST API Guide
Name async
Type
Direction
In
Summary
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 add
Summary
Assign a new permission to a user or group for specific entity.
list
List all the permissions of the specific entity.
320
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>
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 permissi on
In/Out
Summary
The permission.
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 permissi ons
Out
Summary
The list of permissions.
5.196. TAG
A service to manage a specific tag in the system.
Table 5.600. Methods summary
Name get
Summary
Gets the information about the tag.
Removes the tag from the system.
remove 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 tag
Type
Direction
Out
Summary
The tag.
322
5.196.2. remove DELETE
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
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 add
Summary
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 tag
Type
Direction
In/Out
Summary
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 max
Type
Direction
In
Summary
Sets the maximum number of tags to return.
tags
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 export
Summary
Exports a template to the data center export domain.
get
Returns the information about this template or template version.
Removes a virtual machine template.
remove 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 exclusiv e
Direction
In
Summary
Indicates if the existing templates with the same name should be overwritten.
storage_ domain
In Specifies the destination export storage domain.
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 filter
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
template
In/Out
5.199. TEMPLATECDROM
A service managing a CD-ROM device on templates.
Table 5.612. Methods summary
Name get
Summary
Returns the information about this CD-ROM device.
328
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
Name cdrom
Type
Direction
Out
CHAPTER 5. SERVICES
Summary
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 list
Summary
5.200.1. list GET
Table 5.615. Parameters summary
Name cdroms
Type
Direction
Out
Summary
The list of CD-ROM devices of the template.
329
Red Hat Virtualization 4.0 REST API Guide
Name max
Type
Direction
In
5.201.1. copy POST
Table 5.617. Parameters summary
Name async
Type
Direction
In
filter
In
Summary
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 copy
Summary export get remove
Summary
Indicates if the copy should be performed asynchronously.
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 async
Type
Direction
In
filter
In
Summary
Indicates if the export should be performed asynchronously.
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 disk
Type
Direction
Out
5.201.4. remove DELETE
Table 5.620. Parameters summary
Name async
Type
Direction
In
Summary
Summary
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 get
Summary
Returns the details of the attachment.
331
Red Hat Virtualization 4.0 REST API Guide
Name remove
Summary
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 attachme nt
Out
Summary
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 /ovirtengine/api/templates/{template:id}/diskattachments/{attachment:id}?
storage_domain=072fbaa1-08f3-4a40-9f34-a5ca22dd1d74
Table 5.623. Parameters summary
Name force
Type
Direction
In
Summary storage_ domain
In Specifies the identifier of the storage domain the image to be removed resides on.
332
5.203. TEMPLATEDISKATTACHMENTS
This service manages the set of disks attached to a template. Each attached disk is represented by
.
CHAPTER 5. SERVICES
Table 5.624. Methods summary
Name list
Summary
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 attachme nts
Out
Summary
5.204. TEMPLATEDISKS
Table 5.626. Methods summary
Name list
Summary
5.204.1. list GET
Table 5.627. Parameters summary
Name disks
Type
Direction
Out
max
In
5.204.1.1. max
Summary
Sets the maximum number of disks to return.
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 get
Summary remove update
5.205.1. get GET
Table 5.629. Parameters summary
Name nic
Type
Direction
Out
5.205.2. remove DELETE
Table 5.630. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.205.3. update PUT
Table 5.631. Parameters summary
334
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the update should be performed asynchronously.
nic
In/Out
5.206. TEMPLATENICS
Table 5.632. Methods summary
Name add
Summary list
5.206.1. add POST
Table 5.633. Parameters summary
Name nic
Type
Direction
In/Out
5.206.2. list GET
Table 5.634. Parameters summary
Name max
Type
Direction
In
nics
Out
Summary
Summary
Sets the maximum number of NICs to return.
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 get
Summary remove update
5.207.1. get GET
Table 5.636. Parameters summary
Name Type Direction watchdog
Out
5.207.2. remove DELETE
Table 5.637. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.207.3. update PUT
Table 5.638. Parameters summary
336
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the update should be performed asynchronously.
watchdog
In/Out
5.208. TEMPLATEWATCHDOGS
Table 5.639. Methods summary
Name add
Summary list
5.208.1. add POST
Table 5.640. Parameters summary
Name Type Direction watchdog
In/Out
5.208.2. list GET
Table 5.641. Parameters summary
Name max
Type
Direction
In
watchdog s
Out
Summary
Summary
Sets the maximum number of watchdogs to return.
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 add
Summary
Creates a new template.
list
Returns the list of virtual machine templates.
338
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
Name Type clone_pe rmission s
Direction
In
template
In/Out
CHAPTER 5. SERVICES
Summary
Specifies if the permissions of the virtual machine should be copied to the template.
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 case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
339
Red Hat Virtualization 4.0 REST API Guide
Name filter
Type
Direction
In
max
search
In
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of templates to return.
A query string used to restrict the returned templates.
The list of virtual machine templates.
template s
Out
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 get
Summary remove
5.210.1. get GET
Table 5.646. Parameters summary
340
CHAPTER 5. SERVICES
Name Type Direction network
Out
Summary
5.210.2. remove DELETE
Table 5.647. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.211. UNMANAGEDNETWORKS
Table 5.648. Methods summary
Name list
Summary
5.211.1. list GET
Table 5.649. Parameters summary
Name max
Type
Direction
In
networks
Out
Summary
Sets the maximum number of networks to return.
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
Table 5.650. Methods summary
Name get
Summary
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> [email protected]
</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 user
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
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 add
Summary
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 [email protected] from the
myextension-authz authorization provider send a request body like this:
<user>
<principal> [email protected]
</principal>
<user_name> [email protected]@myextensionauthz </user_name>
<domain>
<name> myextension-authz </name>
</domain>
</user>
Table 5.654. Parameters summary
Name user
Type
Direction
In/Out
Summary
344
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>
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 case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
max
search
users
In
In
Out
Sets the maximum number of users to return.
A query string used to restrict the returned users.
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 get
Summary
345
Red Hat Virtualization 4.0 REST API Guide
Name remove
Summary
5.214.1. get GET
Table 5.657. Parameters summary
Name Type network
Direction
Out
5.214.2. remove DELETE
Table 5.658. Parameters summary
Name async
Type
Direction
In
Summary
Summary
Indicates if the remove should be performed asynchronously.
5.215. VIRTUALFUNCTIONALLOWEDNETWORKS
Table 5.659. Methods summary
Name add
Summary list
5.215.1. add POST
Table 5.660. Parameters summary
346
CHAPTER 5. SERVICES
Name Type network
Direction
In/Out
Summary
5.215.2. list GET
Table 5.661. Parameters summary
Name max
Type
Direction
In
networks
Out
Summary
Sets the maximum number of networks to return.
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 ion
This operation stops any migration of a virtual machine to another physical host.
clone commitsnapsh ot
Detaches a virtual machine from a pool.
detach export
Export a virtual machine to an export domain.
347
Red Hat Virtualization 4.0 REST API Guide
Name Summary freezefilesy stems
Freeze virtual machine file systems.
get
Retrieves the description of the virtual machine.
logon maintenance
Initiates the automatic user logon to access a virtual machine from an external console.
migrate previewsnaps hot
This operation migrates a virtual machine to another physical host.
reboot
This operation sends a reboot request to a virtual machine.
remove reordermacad dresses
Removes the virtual machine, including the virtual disks attached to it.
shutdown
This operation sends a shutdown request to a virtual machine.
start stop
Starts the virtual machine.
This operation forces a virtual machine to power-off.
suspend
This operation saves the virtual machine state to disk and stops it.
thawfilesyst ems
Thaw virtual machine file systems.
348
CHAPTER 5. SERVICES
Name ticket undosnapshot update
Summary
Generates a time-sensitive authentication token for accessing a virtual machine’s display.
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 async
Type
Direction
In
Summary
Indicates if the migration should cancelled asynchronously.
5.216.2. clone POST
Table 5.664. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the clone should be performed asynchronously.
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
discard_ snapshot s
In
exclusiv e
In
Summary
Indicates if the export should be performed asynchronously.
The
discard_snapshots
parameter is to be used when the virtual machine should be exported with all its snapshots collapsed.
The
exclusive
parameter is to be used when the virtual machine should be exported even if another copy of it already exists in the export domain (override).
storage_ domain
In
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 async
Type
Direction
In
Summary
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 all_cont ent
Direction
In
Summary
Indicates if all the attributes of the virtual machine should be included in the response.
filter
In Indicates if the results should be filtered according to the permissions of the user.
next_run
In
vm
Out
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.
Description of the virtual machine.
352
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.
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
maintena nce_enab led
In
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 async
Type
Direction
In
Summary
Indicates if the migration should be performed asynchronously.
cluster
In Specifies the cluster the virtual machine should migrate to.
force
In
host
In
Specifies the virtual machine should migrate although it might be defined as non migratable.
Specifies a specific host the virtual machine should migrate to.
354
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.
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 async disks
Type
Direction
In
In
Summary
Indicates if the preview should be performed asynchronously.
restore_ memory
In
snapshot
In
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
detach_o nly
In
force
In
Indicates if the attached virtual disks should be detached first and preserved instead of being removed.
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
filter
In
pause
In
use_clou d_init
In
use_sysp rep
In
vm
In
Summary
Indicates if the action should be performed asynchronously.
Indicates if the results should be filtered according to the permissions of the user.
If set to
true
, start the virtual machine in paused mode.
If set to
true
, the initialization type is set to cloud-
init.
If set to
true
, the initialization type is set to
Sysprep.
The definition of the virtual machine for this specific run.
358
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>
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the generation of the ticket should be performed asynchronously.
ticket
In/Out
5.216.21. undosnapshot POST
Table 5.683. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the action should be performed asynchronously.
5.216.22. update PUT
Table 5.684. Parameters summary
Name async
Type
Direction
In
next_run
In
Summary
Indicates if the update should be performed asynchronously.
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
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 get
Summary
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 applicat ion
Out
Summary
The information about the application.
filter
In Indicates if the results should be filtered according to the permissions of the user.
362
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.
CHAPTER 5. SERVICES
Table 5.687. Methods summary
Name list
Summary
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 applicat ions
Out
Summary
A list of applications installed in the virtual machine.
filter
In Indicates if the results should be filtered according to the permissions of the user.
max
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 get
Summary
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
Name cdrom
Type
Direction
Out
CHAPTER 5. SERVICES
Summary
The information about the CDROM device.
current
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 cdrom
Type
Direction
In/Out
Summary
The information about the CDROM device.
current
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 list
Summary
Returns the list of CDROM devices of the virtual machine.
366
5.220.1. list GET
Returns the list of CDROM devices of the virtual machine.
CHAPTER 5. SERVICES
Table 5.693. Parameters summary
Name cdroms
Type
Direction
Out
max
In
Summary
The list of CDROM devices of the virtual machine.
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 activate deactivate
Summary 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 async
Type
Direction
In
Summary
Indicates if the activation should be performed asynchronously.
5.221.2. deactivate POST
Table 5.696. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the deactivation should be performed asynchronously.
5.221.3. export POST
Table 5.697. Parameters summary
Name async
Type
Direction
In
filter
In
Summary
Indicates if the export should be performed asynchronously.
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 disk
Type
Direction
Out
5.221.5. move POST
368
Table 5.699. Parameters summary
Summary
Name async
Type
Direction
In
filter
In
CHAPTER 5. SERVICES
Summary
Indicates if the move should be performed asynchronously.
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
Table 5.700. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
5.221.7. update PUT
Table 5.701. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
disk
In/Out
5.222. VMDISKS
369
Red Hat Virtualization 4.0 REST API Guide
Table 5.702. Methods summary
Name add
Summary list
5.222.1. add POST
Table 5.703. Parameters summary
Name disk
Type
Direction
In/Out
5.222.2. list GET
Table 5.704. Parameters summary
Name disks
Type
Direction
Out
max
In
Summary
Summary
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 proxyticket remove
Gets the configuration of the graphics console.
5.223.1. get GET
Gets the configuration of the graphics console.
Table 5.706. Parameters summary
Name Type Direction console
Out
Summary current
In Use the following query to obtain the current runtime 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 async
Type
Direction
In
Summary
Indicates if the generation of the ticket should be performed asynchronously.
371
Red Hat Virtualization 4.0 REST API Guide
Name Type Direction proxy_ti cket
Out
5.223.3. remove DELETE
Table 5.708. Parameters summary
Name async
Type
Direction
In
Summary
Summary
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 get
Summary
Retrieve information about particular host device attached to given virtual machine.
remove
Remove the attachment of this host device from given virtual machine.
372
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>
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 device
Type Direction
Out
Summary
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 async
Type
Direction
In
Summary
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 add
Summary
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
, 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 device
Type Direction
In/Out
Summary
The host device to be attached to given virtual machine.
374
5.225.2. list GET
CHAPTER 5. SERVICES
List the host devices assigned to given virtual machine.
Table 5.714. Parameters summary
Name device
Type Direction
Out
Summary
Retrieved list of host devices attached to given virtual machine.
max
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 activate deactivate get
Summary
Removes the NIC.
remove update
Updates the NIC.
5.226.1. activate POST
Table 5.716. Parameters summary
375
Red Hat Virtualization 4.0 REST API Guide
Name async
Type
Direction
In
Summary
Indicates if the activation should be performed asynchronously.
5.226.2. deactivate POST
Table 5.717. Parameters summary
Name async
Type
Direction
In
Summary
Indicates if the deactivation should be performed asynchronously.
5.226.3. get GET
Table 5.718. Parameters summary
Name nic
Type
Direction
Out
Summary
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 async
Type
Direction
In
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
nic
In/Out
5.227. VMNICS
Table 5.721. Methods summary
Name add
Summary
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
378
<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" \
--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
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.722. Parameters summary
Name nic
Type
Direction
In/Out
Summary
5.227.2. list GET
Table 5.723. Parameters summary
Name max
Type
Direction
In
nics
Out
Summary
Sets the maximum number of NICs to return.
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 get
Summary
Removes a virtual NUMA node.
remove update
Updates a virtual NUMA node.
5.228.1. get GET
Table 5.725. Parameters summary
Name node
Type Direction
Out
Summary
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
380
5.228.3. update PUT
Updates a virtual NUMA node.
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
node
In/Out
5.229. VMNUMANODES
Table 5.728. Methods summary
Name add
Summary
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 node
Type Direction
In/Out
Summary
5.229.2. list GET
Lists virtual NUMA nodes of a virtual machine.
Table 5.730. Parameters summary
Name max
Type
Direction
In
Summary
Sets the maximum number of nodes to return.
nodes
Out
382
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
CHAPTER 5. SERVICES
Name allocatevm
Summary
This operation allocates a virtual machine in the virtual machine pool.
Get the virtual machine pool.
get 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 async
Type
Direction
In
Summary
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 filter
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
pool
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 async
Type
Direction
In
Summary
Indicates if the remove should be performed asynchronously.
384
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>
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
pool
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 add
Summary
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 pool
Type
Direction
In/Out
Summary
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 case_sen sitive
Direction
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
filter
In Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of pools to return.
max
In
pools
Out
search
In
Retrieved pools.
A query string used to restrict the returned pools.
386
5.231.2.1. case_sensitive
Indicates if the search performed using the search parameter should be performed taking case into
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 get
Summary
5.232.1. get GET
Table 5.740. Parameters summary
Name Type Direction reported
_device
Out
Summary
5.233. VMREPORTEDDEVICES
Table 5.741. Methods summary
Name list
Summary
5.233.1. list GET
Table 5.742. Parameters summary
387
Red Hat Virtualization 4.0 REST API Guide
Name max
Type
Direction
In
reported
_device
Out
Summary
Sets the maximum number of devices to return.
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 get
Summary
5.234.1. get GET
Table 5.744. Parameters summary
Name Type session
Direction
Out
Summary
5.235. VMSESSIONS
Provides information about virtual machine user sessions.
Table 5.745. Methods summary
Name list
Summary
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 max
Type
Direction
In
Summary
Sets the maximum number of sessions to return.
sessions
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 get
Summary
Returns the information about the watchdog.
389
Red Hat Virtualization 4.0 REST API Guide
Name remove
Summary
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 watchdog
Out
Summary
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
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
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 add
Summary
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 watchdog
In/Out
Summary
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 max
Type
Direction
In
watchdog s
Out
Summary
Sets the maximum number of watchdogs to return.
The information about the watchdog.
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 add
Summary
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
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 clone
Type
Direction
In
Summary
Specifies if the virtual machine should be independent of the template.
Specifies if the permissions of the template should be copied to the virtual machine.
clone_pe rmission s
In
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 all_cont ent
Direction
In
Summary
Indicates if all the attributes of the virtual machines should be included in the response.
397
Red Hat Virtualization 4.0 REST API Guide
Name Type case_sen sitive
Direction
In
filter
In
max
search
In
In
Summary
Indicates if the search performed using the
search
parameter should be performed taking case into account.
Indicates if the results should be filtered according to the permissions of the user.
The maximum number of results to return.
A query string used to restrict the returned virtual machines.
vms
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.
398
5.238.2.2. case_sensitive
Indicates if the search performed using the search parameter should be performed taking case into
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 get
Summary
Retrieves details about a vNIC profile.
Removes the vNIC profile.
remove 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 profile
Out
5.239.2. remove DELETE
Removes the vNIC profile.
Table 5.759. Parameters summary
Name async
Type
Direction
In
Summary
Summary
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 async
Type
Direction
In
Summary
Indicates if the update should be performed asynchronously.
The vNIC profile that is being updated.
profile
In/Out
5.240. VNICPROFILES
This service manages the collection of all vNIC profiles.
Table 5.761. Methods summary
Name add
Summary
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 profile
In/Out
Summary
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 max
Type
Direction
In
profiles
Out
Summary
Sets the maximum number of profiles to return.
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 get
Summary remove
5.241.1. get GET
Table 5.765. Parameters summary
Name filter
Type
Direction
In
Summary
Indicates if the results should be filtered according to the permissions of the user.
weight
Out
5.241.2. remove DELETE
Table 5.766. Parameters summary
402
Name async
Type
Direction
In
CHAPTER 5. SERVICES
Summary
Indicates if the remove should be performed asynchronously.
5.242. WEIGHTS
Table 5.767. Methods summary
Name add
Summary list
5.242.1. add POST
Table 5.768. Parameters summary
Name weight
Type
Direction
In/Out
5.242.2. list GET
Table 5.769. Parameters summary
Name filter
Type
Direction
In
max
weights
In
Out
Summary
Summary
Indicates if the results should be filtered according to the permissions of the user.
Sets the maximum number of weights to return.
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
This section enumerates all the data types that are available in the API.
6.1. ACCESSPROTOCOL ENUM
Table 6.1. Values summary
Name cifs
Summary gluster nfs
6.2. ACTION STRUCT
Table 6.2. Attributes summary
Name async
Type
bricks clone cluster
certificates
check_connec tivity
Summary
CHAPTER 6. TYPES
405
Red Hat Virtualization 4.0 REST API Guide
Name Type collapse_sna pshots
Summary comment
connectivity
_timeout
Free text containing comments about this object.
data_center
deploy_hoste d_engine
description
details
A human-readable description in plain text.
discard_snap shots
disk
disks
exclusive
fault
fence_type
406
Name filter
Type
fix_layout
force
grace_period
host id
image
import_as_te mplate
is_attached
iscsi
iscsi_target s
job
logical_unit s
maintenance_ enabled
Summary
A unique identifier.
CHAPTER 6. TYPES
407
Red Hat Virtualization 4.0 REST API Guide
Name Type modified_bon ds
modified_lab els
modified_net work_attachm ents
Summary name
option
pause
power_manage ment
proxy_ticket
A human-readable name in plain text.
reason
removed_bond s
removed_labe ls
removed_netw ork_attachme nts
408
Name Type resolution_t ype
restore_memo ry
root_passwor d
snapshot
ssh
status
stop_gluster
_service
storage_doma in
storage_doma ins
succeeded
synchronized
_network_att achments
template
ticket
Summary
CHAPTER 6. TYPES
409
Red Hat Virtualization 4.0 REST API Guide
Name Type undeploy_hos ted_engine
use_cloud_in it
use_sysprep
virtual_func tions_config uration
HostNicVirtualFun ctionsConfiguratio n
vm
Summary
6.3. AFFINITYGROUP STRUCT
An affinity group represents a group of virtual machines with a defined relationship.
Table 6.3. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
enforcing
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 name
A unique identifier.
A human-readable name in plain text.
410
Name positive
Type
CHAPTER 6. TYPES
Summary
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 cluster
Type
vms
Summary
A reference to the cluster to which the affinity group applies.
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 comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id name
read_only
A unique identifier.
A human-readable name in plain text.
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 hosts
Type
Summary
A list of hosts that were labeled using this scheduling label.
vms
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 address
Type
comment
concurrent
description
encrypt_opti ons
id
name
Summary
Fence agent address.
Free text containing comments about this object.
Specifies whether the agent should be used concurrently or sequentially.
A human-readable description in plain text.
Specifies whether the options should be encrypted.
A unique identifier.
A human-readable name in plain text.
412
Name options
Type
CHAPTER 6. TYPES
Summary
Fence agent options (comma-delimited list of key-value pairs).
order password port type username
The order of this agent if used with other agents.
Fence agent password.
Fence agent port.
Fence agent type.
Fence agent user name.
Table 6.8. Links summary
Name host
Type
Summary
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 address
Type
Summary
413
Red Hat Virtualization 4.0 REST API Guide
Name broker_type
Type
Summary network_mapp ings
password
port
username
414
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>
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 product_info
Summary
Information about the product, such as its name, the name of the vendor, and the version.
special_obje cts
References to special objects, such as the blank template and the root of the hierarchy of tags.
summary
A summary containing the total number of relevant objects, such as virtual machines, hosts, and storage domains.
time
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 hosts
Type Summary
The summary of hosts.
415
Red Hat Virtualization 4.0 REST API Guide
Name Type Summary storage_doma ins
The summary of storage domains.
The summary of users.
users vms
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 active
Type
Summary
The total number of active objects.
total
The total number of objects.
416
6.10. APPLICATION STRUCT
Table 6.13. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id name
A unique identifier.
A human-readable name in plain text.
Table 6.14. Links summary
Name vm
Type
6.11. ARCHITECTURE ENUM
Table 6.15. Values summary
Name ppc64
Summary undefined x86_64
Summary
6.12. AUTHORIZEDKEY STRUCT
Table 6.16. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
id key name
A unique identifier.
A human-readable name in plain text.
CHAPTER 6. TYPES
417
Red Hat Virtualization 4.0 REST API Guide
Table 6.17. Links summary
Name user
Type
Summary
6.13. AUTONUMASTATUS ENUM
Table 6.18. Values summary
Name disable
Summary enable unknown
6.14. BALANCE STRUCT
Table 6.19. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name
A unique identifier.
A human-readable name in plain text.
Table 6.20. Links summary
418
CHAPTER 6. TYPES
Name Type scheduling_p olicy
Summary scheduling_p olicy_unit
6.15. BIOS STRUCT
Table 6.21. Attributes summary
Name boot_menu
Type
Summary
6.16. BLOCKSTATISTIC STRUCT
Table 6.22. Attributes summary
Name statistics
Type
Summary
6.17. BONDING STRUCT
Represents a network interfaces bond.
Table 6.23. Attributes summary
Name Type ad_partner_m ac
Summary
The
ad_partner_mac
property of the partner bond in mode 4.
options
A list of option elements for a bonded interface.
419
Red Hat Virtualization 4.0 REST API Guide
Name slaves
Type
Summary
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 comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name value
A unique identifier.
A human-readable name in plain text.
420
6.19. BOOT STRUCT
Table 6.25. Attributes summary
Name devices
Type
Summary
6.20. BOOTDEVICE ENUM
Table 6.26. Values summary
Name cdrom
Summary hd network
6.21. BOOTMENU STRUCT
Table 6.27. Attributes summary
Name enabled
Type
Summary
6.22. BOOTPROTOCOL ENUM
Defines the options of the IP address assignment method to a NIC.
Table 6.28. Values summary
Name autoconf
Summary
Stateless address auto-configuration.
CHAPTER 6. TYPES
421
Red Hat Virtualization 4.0 REST API Guide
Name dhcp
Summary
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 profile_deta ils
Summary
Table 6.30. Links summary
Name brick
Type
Summary
422
6.24. CDROM STRUCT
Table 6.31. Attributes summary
Name comment
Type
description
file
id name
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
CHAPTER 6. TYPES
Table 6.32. Links summary
Name Type instance_typ e
template
vm vms
Summary
Optionally references to an instance type the device is used by.
Optionally references to a template the device is used by.
Don’t use this element, use
vms
instead.
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 comment
Type
Summary
Free text containing comments about this object.
content
description
A human-readable description in plain text.
A unique identifier.
id name
organization
subject
A human-readable name in plain text.
6.26. CLOUDINIT STRUCT
Table 6.34. Attributes summary
Name Type authorized_k eys
Summary files
host
network_conf iguration
424
Name Type regenerate_s sh_keys
Summary timezone users
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",
CHAPTER 6. TYPES
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 ballooning_e nabled
Summary comment
Free text containing comments about this object.
cpu
Custom scheduling policy properties of the cluster.
custom_sched uling_policy
_properties
description
display
A human-readable description in plain text.
427
Red Hat Virtualization 4.0 REST API Guide
Name Type error_handli ng
Summary fencing_poli cy
Custom fencing policy can be defined for a cluster.
gluster_serv ice
ha_reservati on
id
ksm
maintenance_ reason_requi red
memory_polic y
migration
A unique identifier.
name
A human-readable name in plain text.
optional_rea son
required_rng
_sources
428
CHAPTER 6. TYPES
Name Type serial_numbe r
Summary supported_ve rsions
switch_type
threads_as_c ores
Type of switch to be used by all networks in given cluster.
trusted_serv ice
tunnel_migra tion
version
virt_service
The compatibility version of the cluster.
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>
430
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:
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 affinity_gro ups
cpu_profiles
data_center
gluster_hook s
gluster_volu mes
management_n etwork
network_filt ers
networks
Summary permissions
431
Red Hat Virtualization 4.0 REST API Guide
Name Type Summary scheduling_p olicy
Reference to the default scheduling policy used by this cluster.
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 comment
Type
Summary
Free text containing comments about this object.
The CPU types supported by this cluster level.
cpu_types
description
id name permits
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
The permits supported by this cluster level.
6.29. CONFIGURATION STRUCT
432
Table 6.38. Attributes summary
Name data type
Type
Summary
The document describing the virtual machine.
CHAPTER 6. TYPES
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/cimschema/2/CIM_ResourceAllocationSettingData"
xmlns:vssd= "http://schemas.dmtf.org/wbem/wscim/1/cimschema/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
Name ovf
Summary
6.31. CONSOLE STRUCT
Table 6.40. Attributes summary
Name enabled
Type
Summary
6.32. CORE STRUCT
Table 6.41. Attributes summary
Name index
Type
socket
Summary
6.33. CPU STRUCT
Table 6.42. Attributes summary
Name Type architecture
cores cpu_tune
Summary
CHAPTER 6. TYPES
435
Red Hat Virtualization 4.0 REST API Guide
Name level
Type
Summary mode
name
speed
topology
type
6.34. CPUMODE ENUM
Table 6.43. Values summary
Name custom host_model host_passthr ough
Summary
6.35. CPUPROFILE STRUCT
Table 6.44. Attributes summary
436
Name comment
Type
description
id
name
Table 6.45. Links summary
Name cluster
Type
permissions
qos
CHAPTER 6. TYPES
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
Summary
6.36. CPUTOPOLOGY STRUCT
Table 6.46. Attributes summary
Name cores
Type
Summary sockets
threads
6.37. CPUTUNE STRUCT
437
Red Hat Virtualization 4.0 REST API Guide
Table 6.47. Attributes summary
Name vcpu_pins
Type
Summary
6.38. CPUTYPE STRUCT
Describes a supported CPU type.
Table 6.48. Attributes summary
Name Type architecture
Summary
The architecture of the CPU.
The level of the CPU type.
level name
The name of the CPU type, for example
Intel Conroe
Family
.
6.39. CREATIONSTATUS ENUM
Table 6.49. Values summary
Name complete failed in_progress pending
Summary
438
6.40. CUSTOMPROPERTY STRUCT
Table 6.50. Attributes summary
Name name
Type
Summary regexp
value
6.41. DATACENTER STRUCT
Table 6.51. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
id local
A human-readable description in plain text.
A unique identifier.
name
A human-readable name in plain text.
quota_mode status
storage_form at
CHAPTER 6. TYPES
439
Red Hat Virtualization 4.0 REST API Guide
Name Type supported_ve rsions
Summary 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 clusters
Type
Summary
Reference to clusters inside this data center.
440
Name Type iscsi_bonds
mac_pool networks
CHAPTER 6. TYPES
Summary
Reference to ISCSI bonds used by this data center.
Reference to the MAC pool used by this data center.
Reference to networks attached to this data center.
permissions
qoss quotas
Reference to permissions assigned to this data center.
Reference to quality of service used by this data center.
Reference to quotas assigned to this data center.
storage_doma ins
Reference to storage domains attached to this data center.
6.42. DATACENTERSTATUS ENUM
Table 6.53. Values summary
Name contend maintenance not_operatio nal problematic
Summary
441
Red Hat Virtualization 4.0 REST API Guide
Name uninitialize d
Summary up
6.43. DEVICE STRUCT
A device wraps links to potential parents of a device.
Table 6.54. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name
A unique identifier.
A human-readable name in plain text.
Table 6.55. Links summary
Name Type instance_typ e
template vm
Summary
Optionally references to an instance type the device is used by.
Optionally references to a template the device is used by.
Don’t use this element, use
vms
instead.
442
Name vms
Type
CHAPTER 6. TYPES
Summary
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 active
Type
Summary
Indicates if the disk is visible to the virtual machine.
The actual size of the disk, in bytes.
actual_size
alias
bootable comment
description
format id
image_id
Indicates if the disk is marked as bootable.
Free text containing comments about this object.
A human-readable description in plain text.
The underlying storage format.
A unique identifier.
443
Red Hat Virtualization 4.0 REST API Guide
Name interface
Type
Summary
The type of interface driver used to connect the disk device to the virtual machine.
logical_name
lun_storage
name
A human-readable name in plain text.
propagate_er rors
Indicates if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the the guest operating system.
provisioned_ size
read_only
The virtual size of the disk, in bytes.
Indicates if the disk is in read-only mode.
sgio shareable
Indicates if the disk can be attached to multiple virtual machines.
sparse
Indicates if the physical storage for the disk should not be preallocated.
status
storage_type
uses_scsi_re servation
The status of the disk device.
444
Name Type wipe_after_d elete
CHAPTER 6. TYPES
Summary
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.
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 disk_profile
Summary instance_typ e
openstack_vo lume_type
permissions
Optionally references to an instance type the device is used by.
quota
snapshot
446
CHAPTER 6. TYPES
Name Type Summary statistics
storage_doma in
Statistics exposed by the disk.
storage_doma ins
The storage domains associated with this disk.
template
Optionally references to a template the device is used by.
vm vms
Don’t use this element, use
vms
instead.
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 active
Type
Summary
This flag indicates if the disk is active in the virtual machine it’s attached to.
Defines whether the disk is bootable.
bootable id interface
comment
description
logical_name
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
The type of interface driver used to connect the disk device to the virtual machine.
The logical name of the virtual machine’s disk, as seen from inside the virtual machine.
name
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 disk
Type
Summary
The reference to the disk.
template
The reference to the template.
vm
The reference to the virtual machine.
6.46. DISKFORMAT ENUM
The underlying storage format of disks.
Table 6.60. Values summary
Name cow
Summary
The Copy On Write format allows snapshots, with a small performance overhead.
449
Red Hat Virtualization 4.0 REST API Guide
Name raw
Summary
The raw format does not allow snapshots, but offers improved performance.
6.47. DISKINTERFACE ENUM
Table 6.61. Values summary
Name ide spapr_vscsi
Summary virtio virtio_scsi
6.48. DISKPROFILE STRUCT
Table 6.62. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name
A unique identifier.
A human-readable name in plain text.
Table 6.63. Links summary
450
CHAPTER 6. TYPES
Name Type permissions
qos
storage_doma in
Summary
6.49. DISKSNAPSHOT STRUCT
Table 6.64. Attributes summary
Name active
Type
Summary
Indicates if the disk is visible to the virtual machine.
actual_size
The actual size of the disk, in bytes.
alias bootable
Indicates if the disk is marked as bootable.
Free text containing comments about this object.
comment id image_id
description
format
A human-readable description in plain text.
The underlying storage format.
A unique identifier.
451
Red Hat Virtualization 4.0 REST API Guide
Name interface
Type
Summary
The type of interface driver used to connect the disk device to the virtual machine.
452 logical_name
lun_storage
name
propagate_er rors
A human-readable name in plain text.
Indicates if disk errors should not cause virtual machine to be paused and, instead, disk errors should be propagated to the the guest operating system.
provisioned_ size
read_only sgio
The virtual size of the disk, in bytes.
Indicates if the disk is in read-only mode.
shareable
Indicates if the disk can be attached to multiple virtual machines.
sparse
Indicates if the physical storage for the disk should not be preallocated.
status
storage_type
uses_scsi_re servation
The status of the disk device.
Name Type wipe_after_d elete
CHAPTER 6. TYPES
Summary
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.
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 disk
Type
Summary disk_profile
instance_typ e
openstack_vo lume_type
permissions
quota
Optionally references to an instance type the device is used by.
454
CHAPTER 6. TYPES
Name snapshot
Type
Summary statistics
storage_doma in
Statistics exposed by the disk.
storage_doma ins
The storage domains associated with this disk.
Optionally references to a template the device is used by.
template vm vms
Don’t use this element, use
vms
instead.
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 illegal
Summary locked ok
6.51. DISKSTORAGETYPE ENUM
Table 6.67. Values summary
Name cinder
Summary image lun
456
6.52. DISKTYPE ENUM
Table 6.68. Values summary
Name data
Summary system
6.53. DISPLAY STRUCT
Table 6.69. Attributes summary
Name address
Type
allow_overri de
certificate
Summary copy_paste_e nabled
disconnect_a ction
file_transfe r_enabled
keyboard_lay out
CHAPTER 6. TYPES
457
Red Hat Virtualization 4.0 REST API Guide
Name monitors
Type
Summary port
proxy
secure_port
single_qxl_p ci
smartcard_en abled
type
6.54. DISPLAYTYPE ENUM
Table 6.70. Values summary
Name spice
Summary vnc
6.55. DNS STRUCT
Represents the DNS resolver configuration.
Table 6.71. Attributes summary
458
CHAPTER 6. TYPES
Name Type search_domai ns
servers
Summary
Array of hosts serving as search domains.
Array of hosts serving as DNS servers.
6.56. DOMAIN STRUCT
This type represents a directory service domain.
Table 6.72. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name user
A unique identifier.
A human-readable name in plain text.
Table 6.73. Links summary
Name groups
Type
users
6.56.1. users
Summary
A reference to all groups in the directory service.
A reference to a list of all users in the directory service.
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 error
Summary
The external entity status is erroneous.
failure
The external entity has an issue that causes failures.
There external entity status is okay but with some information that might be relevant.
info ok warning
The external entity status is okay.
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 profile_deta ils
Summary
460
6.59. ERRORHANDLING STRUCT
6.59. ERRORHANDLING STRUCT
Table 6.76. Attributes summary
Name on_error
Type
Summary
6.60. EVENT STRUCT
Type representing an event.
Table 6.77. Attributes summary
Name code
Type
comment
correlation_ id
custom_data
custom_id
description
flood_rate
id name
Summary
The event code.
Free text containing comments about this object.
The event correlation identifier.
Free text representing custom event data.
A custom event identifier.
A human-readable description in plain text.
Defines the flood rate.
A unique identifier.
A human-readable name in plain text.
CHAPTER 6. TYPES
461
Red Hat Virtualization 4.0 REST API Guide
Name origin
Type
Summary
Free text identifying the origin of the event.
The event severity.
severity time
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 cluster
Type
Summary
Reference to the cluster service.
data_center
Reference to the data center service.
host user vm
storage_doma in
Reference to the storage domain service.
template
Reference to the template service.
Reference to the host service.
Reference to the user service.
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 comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name
A unique identifier.
A human-readable name in plain text.
463
Red Hat Virtualization 4.0 REST API Guide
Name provider
Type
Summary url
user
Table 6.80. Links summary
Name Type external_hos t_provider
Summary
6.62. EXTERNALDISCOVEREDHOST STRUCT
Table 6.81. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
id
ip
last_report
mac
A unique identifier.
464
Name name
Type
subnet_name
Summary
A human-readable name in plain text.
Table 6.82. Links summary
Name Type external_hos t_provider
Summary
6.63. EXTERNALHOST STRUCT
Table 6.83. Attributes summary
Name address
Type
Summary
Free text containing comments about this object.
comment
description
id name
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
Table 6.84. Links summary
CHAPTER 6. TYPES
465
Red Hat Virtualization 4.0 REST API Guide
Name Type external_hos t_provider
Summary
6.64. EXTERNALHOSTGROUP STRUCT
Table 6.85. Attributes summary
Name Type architecture
_name
Summary comment
Free text containing comments about this object.
A human-readable description in plain text.
description
domain_name
id
name
operating_sy stem_name
subnet_name
A unique identifier.
A human-readable name in plain text.
Table 6.86. Links summary
466
CHAPTER 6. TYPES
Name Type external_hos t_provider
Summary
6.65. EXTERNALHOSTPROVIDER STRUCT
Table 6.87. Attributes summary
Name Type authenticati on_url
Summary
Defines the external provider authentication URL address.
comment
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name password
A unique identifier.
A human-readable name in plain text.
Defines password for the user during the authentication process.
properties
requires_aut hentication
url username
Array of provider name/value properties.
Defines whether provider authentication is required or not.
Defines URL address of the external provider.
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 certificates
compute_reso urces
Summary discovered_h osts
host_groups
hosts
6.66. EXTERNALPROVIDER STRUCT
Represents an external provider.
Table 6.89. Attributes summary
Name Type authenticati on_url
Summary
Defines the external provider authentication URL address.
Free text containing comments about this object.
comment
description
A human-readable description in plain text.
468
Name id name password
Type
CHAPTER 6. TYPES
Summary
A unique identifier.
A human-readable name in plain text.
Defines password for the user during the authentication process.
Array of provider name/value properties.
Defines whether provider authentication is required or not.
properties
requires_aut hentication
url
username
Defines URL address of the external provider.
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 error
Summary failure info
469
Red Hat Virtualization 4.0 REST API Guide
Name ok
Summary warning
6.68. EXTERNALSYSTEMTYPE ENUM
Represents the type of the external system that is associated with the step.
Table 6.91. Values summary
Name gluster
Summary
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
.
470
6.69. EXTERNALVMIMPORT STRUCT
Describes parameters of virtual machine import operation from external system.
Table 6.92. Attributes summary
Name name
Type
Summary
Name of the virtual machine to be imported as is defined within the external system.
Password to authenticate against external hypervisor system.
password provider
Type of external virtual machine provider.
sparse
Specifies the disk allocation policy of resulting virtual machine:
true
for sparse,
false
for preallocated.
Name url username
Type
CHAPTER 6. TYPES
Summary
URL to be passed to the
virt-v2v
tool for conversion.
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 cluster
Type
Summary
Specifies the target cluster of the resulting virtual machine.
cpu_profile
Optionally specifies the cpu profile of the resulting virtual machine.
drivers_iso host quota
Optional name of ISO carrying drivers that can be used during the virt-v2v conversion process.
Optional specification of host (using host’s ID) to be used for the conversion process.
Optionally specifies the quota that will be applied to the resulting virtual machine.
storage_doma in
Specifies the target storage domain for converted disks.
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 kvm
Summary vmware xen
6.71. FAULT STRUCT
Table 6.95. Attributes summary
Name detail
Type
reason
Summary
6.72. FENCETYPE ENUM
Type representing the type of the fence operation.
472
Table 6.96. Values summary
CHAPTER 6. TYPES
Name manual restart start status stop
Summary
Manual host fencing via power management.
Restart the host via power management.
Start the host via power management.
Check the host power status via power management.
Stop the host via power management.
6.73. FENCINGPOLICY STRUCT
Type representing a cluster fencing policy.
Table 6.97. Attributes summary
Name enabled
Type
Summary
Enable or disable fencing on this cluster.
skip_if_conn ectivity_bro ken
If enabled, we will not fence a host in case more than a configurable percentage of hosts in the cluster lost connectivity as well.
skip_if_sd_a ctive
If enabled, we will skip fencing in case the host maintains its 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 comment
Type
Summary
Free text containing comments about this object.
content
description
A human-readable description in plain text.
A unique identifier.
id name type
A human-readable name in plain text.
Table 6.99. Links summary
Name Type storage_doma in
Summary
6.75. FILTER STRUCT
Table 6.100. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
474
Name Type description
id
name position
Table 6.101. Links summary
Name Type scheduling_p olicy_unit
Summary
Summary
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
6.76. FLOPPY STRUCT
Table 6.102. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
file id
A unique identifier.
name
A human-readable name in plain text.
Table 6.103. Links summary
CHAPTER 6. TYPES
475
Red Hat Virtualization 4.0 REST API Guide
Name Type instance_typ e
Summary
Optionally references to an instance type the device is used by.
template
Optionally references to a template the device is used by.
vm vms
Don’t use this element, use
vms
instead.
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 name
Type
Summary statistics
476
6.78. GLUSTERBRICK STRUCT
Table 6.105. Attributes summary
Name brick_dir
Type
Summary comment
Free text containing comments about this object.
Name Type description
device
fs_name
gluster_clie nts
Summary
A human-readable description in plain text.
id
memory_pools
A unique identifier.
mnt_options
name pid port server_id status
A human-readable name in plain text.
Table 6.106. Links summary
CHAPTER 6. TYPES
477
Red Hat Virtualization 4.0 REST API Guide
Name Type gluster_volu me
Summary instance_typ e
statistics
template
vm vms
Optionally references to an instance type the device is used by.
Optionally references to a template the device is used by.
Don’t use this element, use
vms
instead.
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 comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
device
478
CHAPTER 6. TYPES
Name fs_name
Type
gluster_clie nts
Summary id
memory_pools
A unique identifier.
mnt_options
name
A human-readable name in plain text.
pid
port
Table 6.108. Links summary
Name Type instance_typ e
template
vm vms
Summary
Optionally references to an instance type the device is used by.
Optionally references to a template the device is used by.
Don’t use this element, use
vms
instead.
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 memory_pools
Summary
6.81. GLUSTERBRICKSTATUS ENUM
Table 6.110. Values summary
Name down
Summary
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 bytes_read
Type
Summary bytes_writte n
480
Name Type client_port
host_name
Summary
6.83. GLUSTERHOOK STRUCT
Table 6.112. Attributes summary
Name checksum
Type
Summary comment
conflict_sta tus
conflicts
content
content_type
Free text containing comments about this object.
description
gluster_comm and
A human-readable description in plain text.
id name
A unique identifier.
A human-readable name in plain text.
CHAPTER 6. TYPES
481
Red Hat Virtualization 4.0 REST API Guide
Name stage status
Type
Summary
Table 6.113. Links summary
Name Type cluster
server_hooks
Summary
6.84. GLUSTERHOOKSTATUS ENUM
Table 6.114. Values summary
Name disabled
Summary
Hook is disabled in the cluster.
Hook is enabled in the cluster.
enabled missing
Unknown/missing hook status.
6.85. GLUSTERMEMORYPOOL STRUCT
Table 6.115. Attributes summary
482
Name Type alloc_count
cold_count
comment
description
hot_count id
max_alloc
max_stdalloc
name
padded_size
pool_misses
type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
6.86. GLUSTERSERVERHOOK STRUCT
Table 6.116. Attributes summary
CHAPTER 6. TYPES
483
Red Hat Virtualization 4.0 REST API Guide
Name checksum
Type
Summary comment
content_type
Free text containing comments about this object.
description
id name status
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
Table 6.117. Links summary
Name host
Type
6.87. GLUSTERSTATE ENUM
Table 6.118. Values summary
Name down
Summary unknown
Summary
484
Name up
Summary
6.88. GLUSTERVOLUME STRUCT
Table 6.119. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
disperse_cou nt
id
A human-readable description in plain text.
A unique identifier.
name
options
redundancy_c ount
replica_coun t
status
A human-readable name in plain text.
stripe_count
CHAPTER 6. TYPES
485
Red Hat Virtualization 4.0 REST API Guide
Name Type transport_ty pes
Summary volume_type
Table 6.120. Links summary
Name bricks
Type
cluster
statistics
Summary
6.89. GLUSTERVOLUMEPROFILEDETAILS STRUCT
Table 6.121. Attributes summary
Name Type brick_profil e_details
Summary
Free text containing comments about this object.
comment
description
id
A human-readable description in plain text.
A unique identifier.
486
CHAPTER 6. TYPES
Name Type Summary name
nfs_profile_ details
A human-readable name in plain text.
6.90. GLUSTERVOLUMESTATUS ENUM
Table 6.122. Values summary
Name down
Summary
Volume needs to be started, for clients to be able to mount and use it.
When the status cannot be determined due to host being non-responsive.
unknown 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 disperse
Summary
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_ disperse
Distributed dispersed volumes distribute files across dispersed subvolumes.
487
Red Hat Virtualization 4.0 REST API Guide
Name Summary distributed_ replicate
Distributed replicated volumes distributes files across replicated bricks in the volume.
distributed_ stripe
Distributed striped volumes stripe data across two or more nodes in the cluster.
distributed_ striped_repl icate
Distributed striped replicated volumes distributes striped data across replicated bricks in the cluster.
Replicated volumes replicates files across bricks in the volume.
replicate stripe
Striped volumes stripes data across bricks in the volume.
striped_repl icate
Striped replicated volumes stripes data across replicated bricks in the cluster.
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.
488
6.91.4. distributed_replicate
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 expiry
Type
Summary
6.93. GRAPHICSCONSOLE STRUCT
Table 6.125. Attributes summary
Name address
Type
Summary comment
Free text containing comments about this object.
description
id
name port protocol tls_port
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
Table 6.126. Links summary
490
Name Type instance_typ e
Summary template vm
6.94. GRAPHICSTYPE ENUM
Table 6.127. Values summary
Name spice
Summary vnc
6.95. GROUP STRUCT
This type represents all groups in the directory service.
Table 6.128. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
domain_entry
_id
The containing directory service domain id.
CHAPTER 6. TYPES
491
Red Hat Virtualization 4.0 REST API Guide
Name id
Type
Summary
A unique identifier.
A human-readable name in plain text.
name namespace
Namespace where group resides.
Table 6.129. Links summary
Name domain
Type
permissions
roles tags
Summary
A link to the domain containing this group.
A link to the permissions sub-collection for permissions attached to this group.
A link to the roles sub-collection for roles attached to this group.
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 architecture
Summary
492
Name codename
Type
Summary distribution
family
kernel version
6.97. HARDWAREINFORMATION STRUCT
Table 6.131. Attributes summary
Name family
Type
Summary manufacturer
product_name
serial_numbe r
supported_rn g_sources
uuid
version
CHAPTER 6. TYPES
493
Red Hat Virtualization 4.0 REST API Guide
6.98. HIGHAVAILABILITY STRUCT
Table 6.132. Attributes summary
Name enabled
Type
Summary priority
6.99. HOOK STRUCT
Table 6.133. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
event_name
id md5 name
A unique identifier.
A human-readable name in plain text.
Table 6.134. Links summary
Name host
Type
Summary
494
6.100. HOOKCONTENTTYPE ENUM
Represents content type of hook script.
Table 6.135. Values summary
Name binary
Summary
Binary content type of the hook.
text
Text content type of the hook.
6.101. HOOKSTAGE ENUM
Table 6.136. Values summary
Name post
Summary pre
6.102. HOOKSTATUS ENUM
Type represents the status of a hook.
Table 6.137. Values summary
Name disabled
Summary
Hook is disabled.
enabled
Hook is enabled.
missing
Hook is missing.
CHAPTER 6. TYPES
495
Red Hat Virtualization 4.0 REST API Guide
6.103. HOST STRUCT
Type representing a host.
Table 6.138. Attributes summary
Name address
Type
Summary
The host address (FQDN/IP).
auto_numa_st atus
The host auto non uniform memory access (NUMA) status.
The host certificate.
certificate
comment
Free text containing comments about this object.
cpu
description
The CPU type of this host.
A human-readable description in plain text.
device_passt hrough
Specifies whether host device passthrough is enabled on this host.
display
Optionally specify the display address of this host explicitly.
external_sta tus
The host external status.
hardware_inf ormation
The host hardware information.
hosted_engin e
The hosted engine status on this host.
id
A unique identifier.
496
CHAPTER 6. TYPES
Name Type Summary iscsi
kdump_status
ksm
The host iSCSI details.
The host KDUMP status.
Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pages to a single page reference.
libvirt_vers ion
max_scheduli ng_memory
memory
The host libvirt version.
The max scheduling memory on this host in bytes.
The amount of physical memory on this host in bytes.
name
numa_support ed
os
A human-readable name in plain text.
Specifies whether non uniform memory access (NUMA) is supported on this host.
The operating system on this host.
override_ipt ables
port
Specifies whether we should override firewall definitions.
The host port.
power_manage ment
The host power management definitions.
497
Red Hat Virtualization 4.0 REST API Guide
Name protocol
Type
Summary
The protocol that the engine uses to communicate with the host.
root_passwor d
When creating a new host, a root password is required if the password authentication method is chosen, but this is not subsequently included in the representation.
se_linux spm ssh
status
status_detai l
summary
The host SElinux status.
The host storage pool manager (SPM) status and definition.
The SSH definitions.
The host status.
The host status details.
The virtual machine summary - how many are active, migrating and total.
transparent_ huge_pages
Transparent huge page support expands the size of memory pages beyond the standard 4 KiB limit.
type
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 able
version
Specifies whether there is an oVirt-related update on this host.
The version of VDSM.
498
6.103.1. external_status
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 affinity_lab els
Summary agents
500
Name Type cluster
devices
external_hos t_provider
hooks
Summary katello_erra ta
Lists all the Katello errata assigned to the host.
network_atta chments
nics
numa_nodes
permissions
CHAPTER 6. TYPES statistics
storage_conn ection_exten sions
storages
tags
Each host resource exposes a statistics sub-collection for host-specific statistics.
501
Red Hat Virtualization 4.0 REST API Guide
Name Type unmanaged_ne tworks
Summary
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>
502
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" />
</statistic>
...
</statistics>
Note
This statistics sub-collection is read-only.
The following list shows the statistic types for hosts:
Name memory.total
Description
Total memory in bytes on the host.
CHAPTER 6. TYPES
Memory in bytes used on the host.
memory.used
memory.free
Memory in bytes free on the host.
Memory in bytes shared on the host.
memory.shared
memory.buffers
memory.cached
swap.total
swap.free
I/O buffers in bytes.
OS caches in bytes.
Total swap memory in bytes on the host.
Swap memory in bytes free on the host.
swap.used
swap.cached
Swap memory in bytes used on the host.
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 cpu.current.user
cpu.current.system
cpu.current.idle
cpu.load.avg.5m
boot.time
Description
Percentage of CPU usage for user slice.
Percentage of CPU usage for system.
Percentage of idle CPU usage.
CPU load average per five minutes.
Boot time of the machine.
6.104. HOSTDEVICE STRUCT
Table 6.140. Attributes summary
Name capability
Type
Summary comment
Free text containing comments about this object.
A human-readable description in plain text.
description
id
iommu_group
name
physical_fun ction
A unique identifier.
A human-readable name in plain text.
504
Name Type placeholder
product vendor
virtual_func tions
Table 6.141. Links summary
Name host
Type
parent_devic e
vm
Summary
Summary
6.105. HOSTDEVICEPASSTHROUGH STRUCT
Table 6.142. Attributes summary
Name enabled
Type
Summary
6.106. HOSTNIC STRUCT
Represents a host NIC.
For example, the XML representation of a host NIC looks like this:
CHAPTER 6. TYPES
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 ad_aggregato r_id
Summary
The
ad_aggregator_id
property of a bond or bond slave, for bonds in mode 4.
base_interfa ce
The base interface of the NIC.
The bonding parameters of the NIC.
bonding
boot_protoco l
bridged
check_connec tivity
comment
The IPv4 boot protocol configuration of the NIC.
Defines the bridged network status.
Free text containing comments about this object.
id ip custom_confi guration
description
A human-readable description in plain text.
A unique identifier.
The IPv4 address of the NIC.
507
Red Hat Virtualization 4.0 REST API Guide
Name ipv6
Type
Summary
The IPv6 address of the NIC.
The IPv6 boot protocol configuration of the NIC.
ipv6_boot_pr otocol
mac mtu
The MAC address of the NIC.
The maximum transmission unit for the interface.
name
A human-readable name in plain text.
network_labe ls
The labels that are applied to this NIC.
override_con figuration
properties
speed
statistics status
A link to the statistics of the NIC.
virtual_func tions_config uration
HostNicVirtualFun ctionsConfiguratio n
For a SR-IOV physical function NIC describes its virtual functions configuration.
vlan
508
6.106.1. ad_aggregator_id
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
CHAPTER 6. TYPES
Name host
Type
Summary network
A reference to the network which the interface should be connected.
physical_fun ction
qos
For a SR-IOV virtual function NIC references to its physical function NIC.
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 all_networks
_allowed
Summary
Defines whether all networks are allowed to be defined on the related virtual functions or specified ones only.
Maximum number of virtual functions the NIC supports.
max_number_o f_virtual_fu nctions
number_of_vi rtual_functi ons
Number of currently defined virtual functions.
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 stomp
Summary
JSON-RPC protocol on top of STOMP.
510
CHAPTER 6. TYPES
Name xml
Summary
XML-RPC protocol.
6.109. HOSTSTATUS ENUM
Type representing a host status.
Table 6.147. Values summary
Name connecting
Summary
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 ed
The host installation failed.
installing
The host is being installed.
installing_o s
The host operating system is now installing.
kdumping
The host kernel has crashed and it is now going through memory dumping.
maintenance
The host is in maintenance status.
non_operatio nal
The host is non operational.
511
Red Hat Virtualization 4.0 REST API Guide
Name Summary non_responsi ve
The host is not responsive.
pending_appr oval
The host is pending administrator approval.
preparing_fo r_maintenanc e
The host is preparing for maintenance.
reboot
The host is being rebooted.
unassigned
The host is in activation process.
up
The host is up.
512
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
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 address
Type
Summary
Free text containing comments about this object.
comment
description
id
logical_unit s
mount_option s
name
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
513
Red Hat Virtualization 4.0 REST API Guide
Name Type nfs_retrans
Summary
The number of times to retry a request before attempting further recovery actions.
514 nfs_timeo
nfs_version
override_lun s
password
path
port
portal
target
type
username
vfs_type
volume_group
The time in tenths of a second to wait for a response before retrying NFS requests.
6.110.1. nfs_retrans
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
CHAPTER 6. TYPES
Name host
Type
Summary
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 ovirt_node
Summary
The host is NGN (Next Generation Node) - a new implementation of RHEV_H which is like RHEL, CentOS or Fedora installation.
rhel rhev_h
The host contains a full RHEL, CentOS or Fedora installation.
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 active
Type
Summary configured
global_maint enance
local_mainte nance
score
516
6.113. ICON STRUCT
Icon of virtual machine or template.
Table 6.152. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
data
Base64 encode content of the icon file.
A human-readable description in plain text.
description
id
media_type
name
A unique identifier.
Format of icon file.
A human-readable name in plain text.
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 comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name
A unique identifier.
A human-readable name in plain text.
6.115. IMAGE STRUCT
Table 6.154. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
CHAPTER 6. TYPES
517
Red Hat Virtualization 4.0 REST API Guide
Name Type description
Summary
A human-readable description in plain text.
id
A unique identifier.
name
A human-readable name in plain text.
Table 6.155. Links summary
Name Type storage_doma in
Summary
6.116. IMAGETRANSFER STRUCT
This type contains information regarding an image transfer being performed.
Table 6.156. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
id
name phase
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
The current phase of the image transfer in progress.
518
Name proxy_url
Type
signed_ticke t
CHAPTER 6. TYPES
Summary
The URL of the proxy server that the user inputs or outputs to.
The signed ticket that should be attached as an
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
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 host
Type
Summary
The host which will be used to write to the image which is targeted for input or output.
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 cancelled
Summary
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
520 finalizing_f ailure
This phase can only be set in the Administration Portal, and indicates that there was an error during the transfer, and it is being finalized with a failure.
finalizing_s uccess
This phase will be set when the user calls finalize .
finished_fai lure
Indicates that the targeted image failed the verification, and cannot be used.
finished_suc cess
Indicates that the transfer session was successfully closed, and the targeted image was verified and ready to be used.
initializing
The initial phase of an image transfer.
paused_syste m
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.
paused_user
This phase is a result of a pause call by the user, using
.
resuming
The phase where the transfer has been resumed by the client calling
.
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
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 false
Summary
Set the value to false on this level.
521
Red Hat Virtualization 4.0 REST API Guide
Name inherit
Summary
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 active_direc tory_ou
Summary authorized_s sh_keys
cloud_init
configuratio n
custom_scrip t
dns_search
dns_servers
domain
host_name
522
Name Type input_locale
nic_configur ations
org_name
Summary regenerate_i ds
regenerate_s sh_keys
root_passwor d
system_local e
timezone
ui_language
user_locale
user_name
windows_lice nse_key
6.120. INSTANCETYPE STRUCT
Describes the hardware configuration of virtual machines.
CHAPTER 6. TYPES
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 bios
Type
Summary
Reference to virtual machine’s BIOS configuration.
comment
Free text containing comments about this object.
524
CHAPTER 6. TYPES
Name console
Type
cpu
cpu_shares
creation_tim e
custom_compa tibility_ver sion
custom_cpu_m odel
custom_emula ted_machine
Summary
Console configured for this virtual machine.
The configuration of the virtual machine CPU.
The virtual machine creation date.
Virtual machine custom compatibility version.
custom_prope rties
Properties sent to VDSM to configure various hooks.
If
true
, the virtual machine cannot be deleted.
delete_prote cted
description
A human-readable description in plain text.
display
The virtual machine display configuration.
domain
Domain configured for this virtual machine.
high_availab ility
The virtual machine high availability configuration.
525
Red Hat Virtualization 4.0 REST API Guide
Name id
Type
Summary
A unique identifier.
initializati on
Reference to virtual machine’s initialization configuration.
io
large_icon
For performance tuning of IO threading.
Virtual machine’s large icon.
memory
The virtual machine’s memory, in bytes.
memory_polic y
Reference to virtual machine’s memory management configuration.
migration
Reference to configuration of migration of running virtual machine to another host.
migration_do wntime
name
Maximum time the virtual machine can be non responsive during its live migration to another host in ms.
A human-readable name in plain text.
origin os
rng_device
The origin of this virtual machine.
Operating system type installed on the virtual machine.
Random Number Generator device configuration for this virtual machine.
serial_numbe r
Virtual machine’s serial number in a cluster.
526
Name small_icon
Type
soundcard_en abled
sso
CHAPTER 6. TYPES
Summary
Virtual machine’s small icon.
If
true
, the sound card is added to the virtual machine.
Reference to the Single Sign On configuration this virtual machine is configured for.
start_paused stateless
If
true
, the virtual machine will be initially in 'paused' state after start.
If
true
, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.
status
The status of the template.
time_zone
tunnel_migra tion
type
The virtual machine’s time zone set by oVirt.
If
true
, the network data transfer will be encrypted during virtual machine live migration.
Determines whether the virtual machine is optimized for desktop or server.
usb version virtio_scsi
Configuration of USB devices for this virtual machine (count, type).
Indicates whether this is a base version or a sub version of another template.
Reference to VirtIO SCSI configuration.
527
Red Hat Virtualization 4.0 REST API Guide
Name vm
Type
Summary
The virtual machine configuration associated with this template.
528
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
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 = 2
30
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 cdroms
Type
Summary
References to the CD-ROM devices attached to the template.
cluster
cpu_profile
Reference to cluster the virtual machine belongs to.
Reference to CPU profile used by this virtual machine.
disk_attachm ents
References to the disks attached to the template.
graphics_con soles
References to the graphic consoles attached to the template.
nics
References to the network interfaces attached to the template.
permissions
References to the user permissions attached to the template.
quota
Reference to quota configuration set for this virtual machine.
storage_doma in
Reference to storage domain the virtual machine belongs to.
530
Name tags
Type
watchdogs
Summary
References to the tags attached to the template.
CHAPTER 6. TYPES
References to the watchdog devices attached to the template.
6.121. IO STRUCT
Table 6.163. Attributes summary
Name threads
Type
Summary
6.122. IP STRUCT
Represents the IP configuration of a network interface.
Table 6.164. Attributes summary
Name address
Type
Summary
The text representation of the IP address.
gateway
The address of the default gateway.
The network mask.
netmask version
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 assignment_m ethod
Summary ip
6.124. IPVERSION ENUM
Defines the values for the IP protocol version.
Table 6.166. Values summary
Name v4
Summary
IPv4.
532
Name v6
Summary
IPv6.
6.125. ISCSIBOND STRUCT
Table 6.167. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name
A unique identifier.
A human-readable name in plain text.
Table 6.168. Links summary
Name Type data_center
networks
storage_conn ections
Summary
6.126. ISCSIDETAILS STRUCT
Table 6.169. Attributes summary
CHAPTER 6. TYPES
533
Red Hat Virtualization 4.0 REST API Guide
Name address
Type
Summary disk_id
initiator
lun_mapping
password
paths
port
portal
product_id
serial
size
status
storage_doma in_id
target
username
534
CHAPTER 6. TYPES
Name vendor_id
Type
volume_group
_id
Summary
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 auto_cleared
Summary
Indicates if the job should be cleared automatically after it was completed by the system.
Free text containing comments about this object.
comment
description
end_time
external id
last_updated
name
start_time
A human-readable description in plain text.
The end time of the job.
Indicates if the job is originated by an external system.
A unique identifier.
The last update date of the job.
A human-readable name in plain text.
The start time of the job.
535
Red Hat Virtualization 4.0 REST API Guide
Name status
Type
Summary
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 owner
Type
Summary
The user who is the owner of the job.
steps
The steps of the job.
6.128. JOBSTATUS ENUM
Represents the status of the job.
Table 6.172. Values summary
Name aborted
Summary
The aborted job status.
failed
The failed job status.
The finished job status.
finished started unknown
The started job status.
The unknown job status.
536
6.128.1. aborted
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 comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
A unique identifier.
id issued name packages
The date when the Katello erratum was issued.
A human-readable name in plain text.
The list of packages which solve the issue reported by the
Katello erratum.
severity solution
The severity of the Katello erratum.
The solution for the issue described by the Katello erratum.
537
Red Hat Virtualization 4.0 REST API Guide
Name summary
Type
Summary
The summary of the Katello erratum.
title
The title of the Katello erratum.
type
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 host
Type
Summary
Reference to the host that the Katello erratum is assigned to.
vm
Reference to the virtual machine that the Katello erratum is assigned to.
538
6.130. KDUMPSTATUS ENUM
Table 6.175. Values summary
Name disabled
Summary enabled
Name unknown
Summary
6.131. KERNEL STRUCT
Table 6.176. Attributes summary
Name version
Type
Summary
6.132. KSM STRUCT
Table 6.177. Attributes summary
Name enabled
Type
Summary merge_across
_nodes
6.133. LOGSEVERITY ENUM
Enum representing a severity of an event.
Table 6.178. Values summary
Name alert
Summary
Alert severity.
error
Error severity.
CHAPTER 6. TYPES
539
Red Hat Virtualization 4.0 REST API Guide
Name normal
Summary
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 address
Type
Summary disk_id
id
lun_mapping
password
540
Name paths port portal
Type
product_id
serial size
status
storage_doma in_id
target username
vendor_id
volume_group
_id
6.135. LUNSTATUS ENUM
Table 6.180. Values summary
Summary
CHAPTER 6. TYPES
541
Red Hat Virtualization 4.0 REST API Guide
Name free
Summary unusable used
6.136. MAC STRUCT
Table 6.181. Attributes summary
Name address
Type
Summary
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
Name Type allow_duplic ates
comment
default_pool
description
id name ranges
CHAPTER 6. TYPES
Summary
Defines whether duplicate MAC addresses are permitted in the pool.
Free text containing comments about this object.
Defines whether this is the default pool.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
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 percent
Type
Summary
543
Red Hat Virtualization 4.0 REST API Guide
6.139. MEMORYPOLICY STRUCT
Table 6.184. Attributes summary
Name Type ballooning
guaranteed
over_commit
Summary transparent_ huge_pages
6.140. MESSAGEBROKERTYPE ENUM
Table 6.185. Values summary
Name qpid
Summary rabbit_mq
6.141. METHOD STRUCT
Table 6.186. Attributes summary
Name id
Type
Summary
544
6.142. MIGRATEONERROR ENUM
CHAPTER 6. TYPES
Table 6.187. Values summary
Name do_not_migra te
Summary 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 ethod
MigrationBandwid thAssignmentMet hod
The method used to assign the bandwidth.
custom_value
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 auto
Summary
Takes the bandwidth from QoS if QoS defined.
custom
Custom defined bandwidth in Mbit/s.
hypervisor_d efault
Takes the value as configured on the hypervisor.
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 auto_converg e
Summary bandwidth compressed
The bandwidth which is allowed to be used by the migrations.
Table 6.191. Links summary
Name policy
Type
Summary
Reference to the migration policy as defined using
engineconfig
.
546
6.146. MIGRATIONPOLICY STRUCT
A policy describing how the migration is going to be treated (convergence, how many parallel migrations allowed).
Table 6.192. Attributes summary
CHAPTER 6. TYPES
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
A unique identifier.
name
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 comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
display
id ip mtu name
A unique identifier.
Specifies the maximum transmission unit for the network.
A human-readable name in plain text.
548
CHAPTER 6. TYPES
Name Type profile_requ ired
required status
Summary stp
Specifies whether spanning tree protocol is enabled for the network.
usages vlan
Defines a set of usage elements for the network.
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 cluster
Type
Summary data_center
A reference to the data center of which the network is a member.
network_labe ls
A reference to the labels assigned to the network.
permissions
A reference to the permissions of the network.
549
Red Hat Virtualization 4.0 REST API Guide
Name qos
Type
Summary vnic_profile s
A reference to the profiles of the network.
550
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= "/ovirtengine/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:
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 comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
id
A unique identifier.
in_sync
ip_address_a ssignments
The IP configuration of the network.
name
A human-readable name in plain text.
properties
Defines custom properties for the network configuration.
reported_con figurations
A read-only list of configuration properties.
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
Name forward_delay gc_timer group_addr group_fwd_mask hash_elasticity hash_max hello_time hello_timer max_age multicast_last_member_count multicast_last_member_interval multicast_membership_interval multicast_querier multicast_querier_interval multicast_query_interval
2000
2
100
26000
0
25500
13000
4
512
200
70
Default value
1500
3765
1:80:c2:0:0:0
0x0
CHAPTER 6. TYPES
553
Red Hat Virtualization 4.0 REST API Guide
Name Default value multicast_query_response_interval 1000 multicast_query_use_ifaddr multicast_router multicast_snooping multicast_startup_query_count 2 multicast_startup_query_interval 3125
0
1
1
Table 6.196. Links summary
Name host
Type
host_nic
network qos
Summary
A reference to the host network interface.
A reference to the network to which the interface is attached.
6.149. NETWORKCONFIGURATION STRUCT
Table 6.197. Attributes summary
554
CHAPTER 6. TYPES
Name dns nics
Type
Summary
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 comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
A unique identifier.
id name
A human-readable name in plain text.
555
Red Hat Virtualization 4.0 REST API Guide
Name version
Type
Summary
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 comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id name
A unique identifier.
A human-readable name in plain text.
Table 6.200. Links summary
Name host_nic
Type
network
Summary
6.152. NETWORKPLUGINTYPE ENUM
Table 6.201. Values summary
556
Name open_vswitch
Summary
6.153. NETWORKSTATUS ENUM
Table 6.202. Values summary
Name non_operatio nal
Summary operational
6.154. NETWORKUSAGE ENUM
Table 6.203. Values summary
Name display
Summary gluster management
The network will be used for Gluster(bricks) data traffic.
migration vm
6.155. NFSPROFILEDETAIL STRUCT
Table 6.204. Attributes summary
CHAPTER 6. TYPES
557
Red Hat Virtualization 4.0 REST API Guide
Name Type nfs_server_i p
Summary profile_deta ils
6.156. NFSVERSION ENUM
Table 6.205. Values summary
Name auto
Summary 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>
558
Table 6.206. Attributes summary
CHAPTER 6. TYPES
Name Type boot_protoco l
comment
description
id
interface linked mac name
on_boot plugged
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
The type of driver used for the NIC.
Defines if the NIC is linked to the virtual machine.
The MAC address of the interface.
A human-readable name in plain text.
Defines if the NIC is plugged in to the virtual machine.
Table 6.207. Links summary
Name Type instance_typ e
network
Summary
Optionally references to an instance type the device is used by.
A reference to the network which the interface should be connected to.
559
Red Hat Virtualization 4.0 REST API Guide
Name Type network_atta chments
Summary network_labe ls
reported_dev ices
statistics
A link to the statistics for the NIC.
template
virtual_func tion_allowed
_labels
Optionally references to a template the device is used by.
virtual_func tion_allowed
_networks
vm
Don’t use this element, use
vms
instead.
vms
vnic_profile
References to the virtual machines that are using this device.
560
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.
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 boot_protoco l
Summary ip
name
on_boot
6.159. NICINTERFACE ENUM
Table 6.209. Values summary
Name e1000 pci_passthro ugh rtl8139
Summary rtl8139_virt io
561
Red Hat Virtualization 4.0 REST API Guide
Name spapr_vlan
Summary virtio
6.160. NICSTATUS ENUM
Table 6.210. Values summary
Name down
Summary up
6.161. NUMANODE STRUCT
Represents a physical NUMA node.
Example XML representation:
<host_numa_node href= "/ovirtengine/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
Name comment
Type
cpu
description
id index memory
name
node_distanc e
Table 6.212. Links summary
Name host
Type
statistics
CHAPTER 6. TYPES
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
Memory of the NUMA node in MB.
A human-readable name in plain text.
Summary
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 host_numa_no de
index
Summary
Deprecated - has no function.
Index of a physical NUMA node to which the virtual NUMA node is pinned.
pinned
Deprecated - should always be true.
6.163. NUMATUNEMODE ENUM
Table 6.214. Values summary
Name interleave
Summary preferred strict
6.164. OPENSTACKIMAGE STRUCT
Table 6.215. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
A unique identifier.
564
CHAPTER 6. TYPES
Name name
Type
Summary
A human-readable name in plain text.
Table 6.216. Links summary
Name Type openstack_im age_provider
Summary
6.165. OPENSTACKIMAGEPROVIDER STRUCT
Table 6.217. Attributes summary
Name Type authenticati on_url
Summary
Defines the external provider authentication URL address.
Free text containing comments about this object.
comment
description
id name password
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
Defines password for the user during the authentication process.
properties
Array of provider name/value properties.
565
Red Hat Virtualization 4.0 REST API Guide
Name Type requires_aut hentication
Summary
Defines whether provider authentication is required or not.
tenant_name
Defines URL address of the external provider.
url username
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 certificates
images
Summary
6.166. OPENSTACKNETWORK STRUCT
Table 6.219. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
566
CHAPTER 6. TYPES
Name id name
Type
Summary
A unique identifier.
A human-readable name in plain text.
Table 6.220. Links summary
Name Type openstack_ne twork_provid er
Summary
6.167. OPENSTACKNETWORKPROVIDER STRUCT
Table 6.221. Attributes summary
Name Type Summary agent_config uration
Agent configuration settings.
Defines the external provider authentication URL address.
authenticati on_url
comment
description
id name
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
567
Red Hat Virtualization 4.0 REST API Guide
Name password
Type
Summary
Defines password for the user during the authentication process.
plugin_type
Network plugin type.
properties
read_only
Array of provider name/value properties.
Indicates whether the provider is read-only.
requires_aut hentication
Defines whether provider authentication is required or not.
tenant_name
type
The type of provider.
url username
Defines URL address of the external provider.
Defines user name to be used during authentication process.
568
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. Portrelated 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
Name Type certificates
networks
Summary
Reference to the certificates list.
Reference to OpenStack networks list.
subnets
Reference to OpenStack networks subnets list.
CHAPTER 6. TYPES
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 external
Summary
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 authenticati on_url
Summary
Defines the external provider authentication URL address.
comment
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name password
A unique identifier.
A human-readable name in plain text.
Defines password for the user during the authentication process.
properties
requires_aut hentication
tenant_name
url username
Array of provider name/value properties.
Defines whether provider authentication is required or not.
Defines URL address of the external provider.
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
570
Table 6.225. Attributes summary
CHAPTER 6. TYPES
Name cidr comment
Type
description
dns_servers
gateway id
ip_version
name
Summary
Defines network CIDR.
Free text containing comments about this object.
A human-readable description in plain text.
Defines a list of DNS servers.
Defines IP gateway.
A unique identifier.
Defines IP version.
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 twork
Reference to the service managing the OpenStack network.
6.171. OPENSTACKVOLUMEPROVIDER STRUCT
Table 6.227. Attributes summary
571
Red Hat Virtualization 4.0 REST API Guide
Name Type authenticati on_url
Summary
Defines the external provider authentication URL address.
comment
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name password
A unique identifier.
A human-readable name in plain text.
Defines password for the user during the authentication process.
properties
requires_aut hentication
tenant_name
url username
Array of provider name/value properties.
Defines whether provider authentication is required or not.
Defines URL address of the external provider.
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
Name Type authenticati on_keys
OpenstackVolum eAuthenticationKe y[]
Summary certificates
data_center
volume_types
6.172. OPENSTACKVOLUMETYPE STRUCT
Table 6.229. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
A unique identifier.
id name
properties
A human-readable name in plain text.
Table 6.230. Links summary
CHAPTER 6. TYPES
573
Red Hat Virtualization 4.0 REST API Guide
Name Type openstack_vo lume_provide r
Summary
6.173. OPENSTACKVOLUMEAUTHENTICATIONKEY STRUCT
Table 6.231. Attributes summary
Name comment
Type
creation_dat e
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
id
A unique identifier.
name usage_type uuid value
OpenstackVolum eAuthenticationKe yUsageType
A human-readable name in plain text.
Table 6.232. Links summary
574
CHAPTER 6. TYPES
Name Type openstack_vo lume_provide r
Summary
6.174. OPENSTACKVOLUMEAUTHENTICATIONKEYUSAGETYPE
ENUM
Table 6.233. Values summary
Name ceph
Summary
6.175. OPERATINGSYSTEM STRUCT
Information describing the operating system. Used for virtual machines and hosts.
Table 6.234. Attributes summary
Name boot
Type
Summary cmdline
custom_kerne l_cmdline
A custom part of the host kernel command line.
initrd kernel
575
Red Hat Virtualization 4.0 REST API Guide
Name Type reported_ker nel_cmdline
Summary
Host kernel command line as reported by a running host.
type
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
Name comment
Type
description
id
large_icon
name
small_icon
CHAPTER 6. TYPES
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
6.177. OPTION STRUCT
Table 6.236. Attributes summary
Name name
Type
Summary type
value
6.178. OSTYPE ENUM
Table 6.237. Values summary
Name other
Summary
577
Red Hat Virtualization 4.0 REST API Guide
Name other_linux
Summary 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
Name windows_2008 x64
Summary 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 name
Type
Summary
The name of the package.
6.180. PAYLOAD STRUCT
Table 6.239. Attributes summary
CHAPTER 6. TYPES
579
Red Hat Virtualization 4.0 REST API Guide
Name files type volume_id
Type
Summary
6.181. PAYLOADENCODING ENUM
Table 6.240. Values summary
Name base64
Summary plaintext
6.182. PERMISSION STRUCT
Table 6.241. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name
A unique identifier.
A human-readable name in plain text.
580
Table 6.242. Links summary
Name Type cluster
data_center
disk
group
host
role
storage_doma in
template
user
vm
vm_pool
Summary
6.183. PERMIT STRUCT
Type represents a permit.
Table 6.243. Attributes summary
CHAPTER 6. TYPES
581
Red Hat Virtualization 4.0 REST API Guide
Name Type administrati ve
Summary
Specifies whether permit is administrative or not.
comment
Free text containing comments about this object.
A human-readable description in plain text.
description
id
name
A unique identifier.
A human-readable name in plain text.
Table 6.244. Links summary
Name role
Type
Summary
Reference to the role the permit belongs to.
6.184. PMPROXY STRUCT
Table 6.245. Attributes summary
Name type
Type
Summary
582
6.185. PMPROXYTYPE ENUM
Table 6.246. Values summary
Name cluster
Summary
Fence proxy is selected from the same cluster as fenced host.
Name dc other_dc
Summary
Fence proxy is selected from the same data center as fenced host.
Fence proxy is selected from a different data center than fenced host.
CHAPTER 6. TYPES
6.186. POLICYUNITTYPE ENUM
This enum holds the types of all internal policy units types
Table 6.247. Values summary
Name filter load_balanci ng weight
Summary
6.187. PORTMIRRORING STRUCT
6.188. POWERMANAGEMENT STRUCT
Table 6.248. Attributes summary
Name address
Type
Summary
The host name or IP address of the host.
agents
Specifies fence agent options when multiple fences are used.
automatic_pm
_enabled
Toggles the automated power control of the host in order to save energy.
583
Red Hat Virtualization 4.0 REST API Guide
Name enabled
Type
Summary
Indicates whether power management configuration is enabled or disabled.
kdump_detect ion options
Toggles whether to determine if kdump is running on the host before it is shut down.
Fencing options for the selected type= specified with the option name="" and value="" strings.
password
A valid, robust password for power management.
pm_proxies
status
Determines the power management proxy.
Determines the power status of the host.
type username
Fencing device code.
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.
584
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.
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 off
Summary
Host is OFF.
Host is ON.
on unknown
Unknown status.
CHAPTER 6. TYPES
6.190. PRODUCT STRUCT
Table 6.250. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
id name
A unique identifier.
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 name
Type
Summary
The name of the product, for example
oVirt Engine
.
The name of the vendor, for example `ovirt.
vendor 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
Name Type block_statis tics
Summary duration
fop_statisti cs
profile_type
statistics
6.193. PROPERTY STRUCT
Table 6.253. Attributes summary
Name name
Type
Summary value
6.194. PROXYTICKET STRUCT
Table 6.254. Attributes summary
Name value
Type
Summary
6.195. QOS STRUCT
This type represents the attributes to define Quality of service (QoS).
CHAPTER 6. TYPES
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
, 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 comment
Type
Summary
Free text containing comments about this object.
The maximum processing capability in %.
cpu_limit
description
A human-readable description in plain text.
A unique identifier.
id
inbound_aver age
inbound_burs t
inbound_peak
max_iops
The desired average inbound bit rate in Mbps.
The amount of data that can be delivered in a single burst in
MiB.
The maximum inbound rate in Mbps.
Maximum permitted number of input and output operations per second.
max_read_iop s
Maximum permitted number of input operations per second.
588
Name Type max_read_thr oughput
max_throughp ut
max_write_io ps
max_write_th roughput
name
outbound_ave rage
outbound_ave rage_linksha re
outbound_ave rage_realtim e
outbound_ave rage_upperli mit
outbound_bur st
outbound_pea k
CHAPTER 6. TYPES
Summary
Maximum permitted throughput for read operations.
Maximum permitted total throughput.
Maximum permitted number of output operations per second.
Maximum permitted throughput for write operations.
A human-readable name in plain text.
The desired average outbound bit rate in Mbps.
Weighted share.
The committed rate in Mbps.
The maximum bandwidth to be used by a network in Mbps.
The amount of data that can be sent in a single burst in MiB.
The maximum outbound rate in Mbps.
589
Red Hat Virtualization 4.0 REST API Guide
Name type
Type
Summary
The kind of resources this entry can be assigned.
590
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
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 data_center
Summary
The data center the QoS is assiciated to.
592
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 cpu
Summary
The
can be assigned to resources with computing capabilities.
hostnetwork
The
can be assigned to host networks.
network
The
can be assigned to virtual machines networks.
CHAPTER 6. TYPES
Name storage
Summary
The
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 cluster_hard
_limit_pct
Summary cluster_soft
_limit_pct
comment
data_center
description
disks
Free text containing comments about this object.
A human-readable description in plain text.
593
Red Hat Virtualization 4.0 REST API Guide
Name id
Type
Summary
A unique identifier.
name
storage_hard
_limit_pct
storage_soft
_limit_pct
A human-readable name in plain text.
users vms
Table 6.259. Links summary
Name Type permissions
quota_cluste r_limits
Summary quota_storag e_limits
6.198. QUOTACLUSTERLIMIT STRUCT
Table 6.260. Attributes summary
594
Name comment
Type
description
id
memory_limit
memory_usage
name
vcpu_limit
vcpu_usage
Table 6.261. Links summary
Name cluster
Type
quota
CHAPTER 6. TYPES
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
Summary
6.199. QUOTAMODETYPE ENUM
Table 6.262. Values summary
Name audit
Summary
595
Red Hat Virtualization 4.0 REST API Guide
Name disabled
Summary enabled
6.200. QUOTASTORAGELIMIT STRUCT
Table 6.263. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
limit name usage description
id
A unique identifier.
A human-readable name in plain text.
Table 6.264. Links summary
Name Type quota
storage_doma in
Summary
596
6.201. RANGE STRUCT
CHAPTER 6. TYPES
6.201. RANGE STRUCT
Table 6.265. Attributes summary
Name from
Type
Summary to
6.202. RATE STRUCT
Determines maximum speed of consumption of bytes from random number generator device.
Table 6.266. Attributes summary
Name bytes
Type
Summary
Number of bytes allowed to consume per period.
period
Duration of one period in milliseconds.
6.203. REPORTEDCONFIGURATION STRUCT
Table 6.267. Attributes summary
Name Type actual_value
Summary expected_val ue
in_sync
false
when the network attachment contains uncommitted network configuration.
597
Red Hat Virtualization 4.0 REST API Guide
Name name
Type
Summary
6.204. REPORTEDDEVICE STRUCT
Table 6.268. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
mac name type description
id ips
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
Table 6.269. Links summary
Name vm
Type
Summary
598
6.205. REPORTEDDEVICETYPE ENUM
Table 6.270. Values summary
CHAPTER 6. TYPES
Name network
Summary
6.206. RESOLUTIONTYPE ENUM
Table 6.271. Values summary
Name add
Summary copy
6.207. RNGDEVICE STRUCT
Random number generator (RNG) device model.
Table 6.272. Attributes summary
Name rate
Type
Summary
Determines maximum speed of consumption of bytes from random number generator device.
source
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 hwrng
Summary
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 administrati ve
Summary
Defines the role as administrative-only or not.
Free text containing comments about this object.
comment
description
id mutable name
A human-readable description in plain text.
A unique identifier.
Defines the ability to update or delete the role.
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
Name permits user
Type
CHAPTER 6. TYPES
Summary
A link to the permits sub-collection for role permits.
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 admin
Summary
Administrative role.
user
User role.
6.211. SCHEDULINGPOLICY STRUCT
Table 6.277. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
default_poli cy
description
A human-readable description in plain text.
id locked
A unique identifier.
601
Red Hat Virtualization 4.0 REST API Guide
Name name
Type
Summary
A human-readable name in plain text.
properties
Table 6.278. Links summary
Name balances
Type
filters weight
Summary
6.212. SCHEDULINGPOLICYUNIT STRUCT
Table 6.279. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
enabled id
A unique identifier.
internal name
A human-readable name in plain text.
602
Name properties type
Type
Summary
6.213. SCSIGENERICIO ENUM
Table 6.280. Values summary
Name filtered unfiltered
Summary
6.214. SELINUX STRUCT
Table 6.281. Attributes summary
Name mode
Type
Summary
6.215. SELINUXMODE ENUM
Table 6.282. Values summary
Name disabled
Summary enforcing
CHAPTER 6. TYPES
603
Red Hat Virtualization 4.0 REST API Guide
Name permissive
Summary
6.216. SERIALNUMBER STRUCT
Table 6.283. Attributes summary
Name policy value
Type
Summary
6.217. SERIALNUMBERPOLICY ENUM
Table 6.284. Values summary
Name custom
Summary host vm
6.218. SESSION STRUCT
Describes user session to a virtual machine.
Table 6.285. Attributes summary
604
Name comment
Type
console_user
description
id ip name protocol
CHAPTER 6. TYPES
Summary
Free text containing comments about this object.
Indicates if this is a console session.
A human-readable description in plain text.
A unique identifier.
IP address user is connected from.
A human-readable name in plain text.
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 user
Type
Summary
User related to this session.
605
Red Hat Virtualization 4.0 REST API Guide
Name vm
Type
Summary
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 enabled
Type
Summary
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
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
Name enabled
Type
CHAPTER 6. TYPES
Summary
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= "/ovirtengine/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 bios
Type
Summary
Reference to virtual machine’s BIOS configuration.
Free text containing comments about this object.
comment console
cpu
cpu_shares
Console configured for this virtual machine.
The configuration of the virtual machine CPU.
607
Red Hat Virtualization 4.0 REST API Guide
Name Type creation_tim e
Summary
The virtual machine creation date.
custom_compa tibility_ver sion
Virtual machine custom compatibility version.
custom_cpu_m odel
custom_emula ted_machine
custom_prope rties
Properties sent to VDSM to configure various hooks.
date
If
true
, the virtual machine cannot be deleted.
delete_prote cted
description
display domain
A human-readable description in plain text.
The virtual machine display configuration.
Domain configured for this virtual machine.
fqdn
Fully qualified domain name of the virtual machine.
guest_operat ing_system
What operating system is installed on the virtual machine.
608
Name Type guest_time_z one
CHAPTER 6. TYPES
Summary
What time zone is used by the virtual machine (as returned by guest agent).
high_availab ility
The virtual machine high availability configuration.
A unique identifier.
id
initializati on
Reference to virtual machine’s initialization configuration.
For performance tuning of IO threading.
io
large_icon
memory
Virtual machine’s large icon.
The virtual machine’s memory, in bytes.
memory_polic y
Reference to virtual machine’s memory management configuration.
migration
Reference to configuration of migration of running virtual machine to another host.
migration_do wntime
Maximum time the virtual machine can be non responsive during its live migration to another host in ms.
name
next_run_con figuration_e xists
A human-readable name in plain text.
Virtual machine configuration has been changed and requires restart of the virtual machine.
numa_tune_mo de
How the NUMA topology is applied.
609
Red Hat Virtualization 4.0 REST API Guide
Name Type Summary
610 origin os payloads
The origin of this virtual machine.
Operating system type installed on the virtual machine.
Optional payloads of the virtual machine, used for ISOs to configure it.
persist_memo rystate
placement_po licy
The configuration of the virtual machine’s placement policy.
rng_device
Random Number Generator device configuration for this virtual machine.
run_once
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 r
Virtual machine’s serial number in a cluster.
small_icon
snapshot_sta tus
Virtual machine’s small icon.
snapshot_typ e
Name Type soundcard_en abled
sso
start_paused
start_time
stateless
CHAPTER 6. TYPES
Summary
If
true
, the sound card is added to the virtual machine.
Reference to the Single Sign On configuration this virtual machine is configured for.
If
true
, the virtual machine will be initially in 'paused' state after start.
The date in which the virtual machine was started.
If
true
, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.
status
status_detai l
stop_reason
stop_time time_zone
tunnel_migra tion
type
The current status of the virtual machine.
Human readable detail of current status.
The reason the virtual machine was stopped.
The date in which the virtual machine was stopped.
The virtual machine’s time zone set by oVirt.
If
true
, the network data transfer will be encrypted during virtual machine live migration.
Determines whether the virtual machine is optimized for desktop or server.
611
Red Hat Virtualization 4.0 REST API Guide
Name usb
Type
Summary
Configuration of USB devices for this virtual machine (count, type).
If
true
, the virtual machine is reconfigured to the latest version of it’s template when it is started.
use_latest_t emplate_vers ion
virtio_scsi
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.
612
6.221.3. high_availability
The virtual machine high availability configuration. If set, the virtual machine will be automatically
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 = 2
30
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.
614
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>
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 affinity_lab els
Summary
Optional.
applications
List of applications installed on the virtual machine.
cdroms cluster
Reference to the ISO mounted to the CDROM.
Reference to cluster the virtual machine belongs to.
cpu_profile
Reference to CPU profile used by this virtual machine.
disk_attachm ents
References the disks attached to the virtual machine.
external_hos t_provider
floppies
Reference to the ISO mounted to the floppy.
615
Red Hat Virtualization 4.0 REST API Guide
Name Type Summary graphics_con soles
List of graphics consoles configured for this virtual machine.
616 host
host_devices
Reference to the host the virtual machine is running on.
References devices associated to this virtual machine.
instance_typ e
The virtual machine configuration can be optionally predefined via one of the instance types.
katello_erra ta
Lists all the Katello errata assigned to the virtual machine.
nics
References the list of network interface devices on the virtual machine.
numa_nodes
Refers to the NUMA Nodes configuration used by this virtual machine.
permissions
Permissions set for this virtual machine.
quota
reported_dev ices
Reference to quota configuration set for this virtual machine.
sessions
List of user sessions opened for this virtual machine.
Refers to all snapshots taken from the virtual machine.
snapshots
statistics
Statistics data collected from this virtual machine.
CHAPTER 6. TYPES
Name Type Summary storage_doma in
Reference to storage domain the virtual machine belongs to.
tags
template vm
Reference to the template the virtual machine is based on.
vm_pool
Reference to the pool the virtual machine is optionally member of.
watchdogs
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 in_preview
Summary locked ok
6.223. SNAPSHOTTYPE ENUM
Table 6.292. Values summary
Name active
Summary preview regular stateless
618
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
Name Type blank_templa te
root_tag
Summary
Reference to the blank template.
Reference to the root of the hierarchy of tags.
6.225. SPM STRUCT
Table 6.294. Attributes summary
Name priority
Type
Summary status
6.226. SPMSTATUS ENUM
Table 6.295. Values summary
Name contending
Summary none spm
6.227. SSH STRUCT
Table 6.296. Attributes summary
CHAPTER 6. TYPES
619
Red Hat Virtualization 4.0 REST API Guide
Name Type authenticati on_method
Summary comment
Free text containing comments about this object.
A human-readable description in plain text.
id name port user description
fingerprint
A unique identifier.
A human-readable name in plain text.
6.228. SSHAUTHENTICATIONMETHOD ENUM
Table 6.297. Values summary
Name password
Summary publickey
6.229. SSHPUBLICKEY STRUCT
Table 6.298. Attributes summary
620
Name comment
Type
content
description
id name
Table 6.299. Links summary
Name user
Type
CHAPTER 6. TYPES
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
Summary
6.230. SSO STRUCT
Table 6.300. Attributes summary
Name methods
Type
Summary
6.231. SSOMETHOD ENUM
Table 6.301. Values summary
Name guest_agent
Summary
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= "/ovirtengine/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 comment
Type
Summary
Free text containing comments about this object.
622
name type unit values
Name Type description
id
kind
CHAPTER 6. TYPES
Summary
A human-readable description in plain text.
A unique identifier.
The type of statistic measures.
A human-readable name in plain text.
The data type for the statistical values that follow.
The unit or rate to measure of the statistical values.
A data set that contains
datum
.
Table 6.303. Links summary
Name brick
Type
Summary disk
gluster_volu me
A relationship to the containing
disk
resource.
host
host_nic
host_numa_no de
A reference to the host NIC.
623
Red Hat Virtualization 4.0 REST API Guide
Name nic step
Type
Summary vm
6.233. STATISTICKIND ENUM
Table 6.304. Values summary
Name counter
Summary gauge
6.234. STATISTICUNIT ENUM
Table 6.305. Values summary
Name bits_per_sec ond
Summary bytes bytes_per_se cond count_per_se cond
624
CHAPTER 6. TYPES
Name none
Summary 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 comment
Type
Summary
Free text containing comments about this object.
description
end_time
A human-readable description in plain text.
The end time of the step.
external name number
external_typ e
The external system which is referenced by the step.
id
A unique identifier.
Indicates if the step is originated by an external system.
A human-readable name in plain text.
The order of the step in current hierarchy level.
625
Red Hat Virtualization 4.0 REST API Guide
Name start_time
Type
Summary
The start time of the step.
status type
The status of the step.
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 job
Type
Summary
References the
job
which is the top of the current step hierarchy.
parent_step
References the parent step of the current step in the hierarchy.
statistics
626
6.236. STEPENUM ENUM
Type representing a step type.
Table 6.308. Values summary
Name executing
Summary
The executing step type.
finalizing
The finalizing step type.
CHAPTER 6. TYPES
Name Summary rebalancing_ volume
The
rebalancing volume
step type.
removing_bri cks
The
removing bricks
step type.
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 aborted
Summary
The aborted step status.
The failed step status.
failed finished
The finished step status.
started unknown
The started step status.
The unknown step status.
628
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
Name address
Type
comment
description
id
mount_option s
name
nfs_retrans
nfs_timeo
nfs_version
password
path port portal
target type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
CHAPTER 6. TYPES
629
Red Hat Virtualization 4.0 REST API Guide
Name username
Type
Summary vfs_type
Table 6.311. Links summary
Name host
Type
Summary id name password target username
6.239. STORAGECONNECTIONEXTENSION STRUCT
Table 6.312. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
A unique identifier.
A human-readable name in plain text.
630
Table 6.313. Links summary
CHAPTER 6. TYPES
Name host
Type
Summary
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 available
Type
Summary comment
Free text containing comments about this object.
committed
631
Red Hat Virtualization 4.0 REST API Guide
Name Type critical_spa ce_action_bl ocker
Summary description
external_sta tus
A human-readable description in plain text.
id
A unique identifier.
import
master
name status
A human-readable name in plain text.
storage
storage_form at
type
used
632
CHAPTER 6. TYPES
Name Type warning_low_ space_indica tor
wipe_after_d elete
Summary
Serves as the default value of
wipe_after_delete
for
.
6.240.1. wipe_after_delete
Serves as the default value of wipe_after_delete for disk
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 data_center
Summary
This is used to link to the data center that the storage domain is attached to.
data_centers
disk_profile s
disk_snapsho ts
This is a set of links to the data centers that the storage domain is attached to.
disks
files
host
Host is only relevant at creation time.
633
Red Hat Virtualization 4.0 REST API Guide
Name Type images
permissions
storage_conn ections
templates
vms
Summary
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 activating
Summary active detaching inactive locked
634
Name maintenance
Summary mixed preparing_fo r_maintenanc e unattached unknown
6.242. STORAGEDOMAINTYPE ENUM
Table 6.317. Values summary
Name data
Summary export image iso volume
6.243. STORAGEFORMAT ENUM
Table 6.318. Values summary
CHAPTER 6. TYPES
635
Red Hat Virtualization 4.0 REST API Guide
Name v1
Summary v2 v3
6.244. STORAGETYPE ENUM
Type representing a storage domain type.
Table 6.319. Values summary
Name cinder
Summary
Cinder storage domain.
Fibre-Channel storage domain.
fcp glance glusterfs iscsi localfs nfs posixfs
Glance storage domain.
Gluster-FS storage domain.
iSCSI storage domain.
Storage domain on Local storage.
NFS storage domain.
POSIX-FS storage domain.
6.244.1. cinder
636
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 legacy
Summary
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 comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id name
A unique identifier.
A human-readable name in plain text.
Table 6.322. Links summary
CHAPTER 6. TYPES
637
Red Hat Virtualization 4.0 REST API Guide
Name group
Type
Summary
Reference to the group which has this tag assigned.
Reference to the host which has this tag assigned.
host parent
Reference to the parent tag of this tag.
Reference to the template which has this tag assigned.
template user vm
Reference to the user who has this tag assigned.
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 bios
Type
Summary
Reference to virtual machine’s BIOS configuration.
Free text containing comments about this object.
comment console
cpu
cpu_shares
Console configured for this virtual machine.
The configuration of the virtual machine CPU.
638
CHAPTER 6. TYPES
Name Type creation_tim e
Summary
The virtual machine creation date.
custom_compa tibility_ver sion
Virtual machine custom compatibility version.
custom_cpu_m odel
custom_emula ted_machine
custom_prope rties
Properties sent to VDSM to configure various hooks.
delete_prote cted
If
true
, the virtual machine cannot be deleted.
description
display
initializati on
io
A human-readable description in plain text.
The virtual machine display configuration.
domain
Domain configured for this virtual machine.
high_availab ility
The virtual machine high availability configuration.
id
A unique identifier.
Reference to virtual machine’s initialization configuration.
For performance tuning of IO threading.
639
Red Hat Virtualization 4.0 REST API Guide
Name Type Summary large_icon
memory
Virtual machine’s large icon.
The virtual machine’s memory, in bytes.
memory_polic y
Reference to virtual machine’s memory management configuration.
migration
Reference to configuration of migration of running virtual machine to another host.
migration_do wntime
name
Maximum time the virtual machine can be non responsive during its live migration to another host in ms.
A human-readable name in plain text.
origin os
rng_device
The origin of this virtual machine.
Operating system type installed on the virtual machine.
Random Number Generator device configuration for this virtual machine.
serial_numbe r
Virtual machine’s serial number in a cluster.
small_icon
Virtual machine’s small icon.
soundcard_en abled
If
true
, the sound card is added to the virtual machine.
640
Name sso start_paused
Type
CHAPTER 6. TYPES
Summary
Reference to the Single Sign On configuration this virtual machine is configured for.
If
true
, the virtual machine will be initially in 'paused' state after start.
stateless
status time_zone
The status of the template.
tunnel_migra tion
type
The virtual machine’s time zone set by oVirt.
If
true
, the network data transfer will be encrypted during virtual machine live migration.
Determines whether the virtual machine is optimized for desktop or server.
usb
If
true
, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.
Configuration of USB devices for this virtual machine (count, type).
version
Indicates whether this is a base version or a sub version of another template.
virtio_scsi
vm
Reference to VirtIO SCSI configuration.
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 = 2
30
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 cdroms
Type
Summary
References to the CD-ROM devices attached to the template.
Reference to cluster the virtual machine belongs to.
cluster
cpu_profile
Reference to CPU profile used by this virtual machine.
disk_attachm ents
References to the disks attached to the template.
graphics_con soles
References to the graphic consoles attached to the template.
nics
References to the network interfaces attached to the template.
permissions
quota
Reference to quota configuration set for this virtual machine.
storage_doma in
Reference to storage domain the virtual machine belongs to.
tags watchdogs
References to the user permissions attached to the template.
References to the tags attached to the template.
References to the watchdog devices attached to the template.
644
6.248. TEMPLATESTATUS ENUM
Type representing a status of a virtual machine template.
CHAPTER 6. TYPES
Table 6.325. Values summary
Name illegal
Summary
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 version_name
Summary
The name of this version.
version_numb er
The index of this version in the versions hierarchy of the 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 base_templat e
Summary
References the template that this version is associated with.
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 expiry
Type
Summary
Time to live for the ticket in seconds.
value
The virtual machine access ticket.
6.251. TIMEZONE STRUCT
Time zone representation.
Table 6.329. Attributes summary
Name name
Type
Summary
Name of the time zone.
utc_offset
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 enabled
Type
Summary
Enable THP support.
646
6.253. TRANSPORTTYPE ENUM
Protocol used to access a Gluster volume.
Table 6.331. Values summary
Name rdma
Summary
Remote direct memory access.
tcp
TCP.
6.254. UNMANAGEDNETWORK STRUCT
Table 6.332. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
id name
A unique identifier.
A human-readable name in plain text.
Table 6.333. Links summary
Name host
Type
host_nic
Summary
CHAPTER 6. TYPES
6.255. USB STRUCT
Table 6.334. Attributes summary
647
Red Hat Virtualization 4.0 REST API Guide
Name enabled
Type
Summary type
6.256. USBTYPE ENUM
Table 6.335. Values summary
Name legacy
Summary native
6.257. USER STRUCT
Represents a user in the system.
Table 6.336. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
department
description
domain_entry
_id
A human-readable description in plain text.
648
CHAPTER 6. TYPES
Name id
Type
last_name logged_in name namespace password principal
Summary
A unique identifier.
A human-readable name in plain text.
Namespace where user resides.
Same as
user_name
principal has different formats based on LDAP provider.
Username of the user.
user_name
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: [email protected]@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 domain
Type
Summary groups
permissions
roles
ssh_public_k eys
A link to the roles sub-collection for user resources.
tags
A link to the tags sub-collection for user resources.
6.258. VALUE STRUCT
Table 6.338. Attributes summary
Name datum
Type
Summary detail
6.259. VALUETYPE ENUM
Table 6.339. Values summary
Name decimal
Summary
650
Name integer string
Summary
6.260. VCPUPIN STRUCT
Table 6.340. Attributes summary
Name cpu_set
Type
Summary vcpu
6.261. VENDOR STRUCT
Table 6.341. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
id name
A unique identifier.
A human-readable name in plain text.
6.262. VERSION STRUCT
Table 6.342. Attributes summary
CHAPTER 6. TYPES
651
Red Hat Virtualization 4.0 REST API Guide
Name build
Type
Summary
Free text containing comments about this object.
comment
description
A human-readable description in plain text.
full_version
id major
A unique identifier.
minor name
A human-readable name in plain text.
revision
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 enabled
Type
Summary
Enable Virtio SCSI support.
652
6.264. VIRTUALNUMANODE STRUCT
Represents the virtual NUMA node.
An example XML representation:
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 comment
Type
Summary
Free text containing comments about this object.
cpu
A human-readable description in plain text.
description
id index
A unique identifier.
Memory of the NUMA node in MB.
memory name
node_distanc e
A human-readable name in plain text.
653
Red Hat Virtualization 4.0 REST API Guide
Name Type numa_node_pi ns
Summary
Table 6.345. Links summary
Name host
Type
statistics
vm
Summary
6.265. VLAN STRUCT
Type representing a Virtual LAN (VLAN) type.
Table 6.346. Attributes summary
Name id
Type
Summary
Virtual LAN ID.
6.266. VM STRUCT
Represents a virtual machine.
Table 6.347. Attributes summary
Name bios
Type
Summary
Reference to virtual machine’s BIOS configuration.
654
Name comment console cpu
Type
cpu_shares
creation_tim e
custom_compa tibility_ver sion
custom_cpu_m odel
custom_emula ted_machine
CHAPTER 6. TYPES
Summary
Free text containing comments about this object.
Console configured for this virtual machine.
The configuration of the virtual machine CPU.
The virtual machine creation date.
Virtual machine custom compatibility version.
custom_prope rties
Properties sent to VDSM to configure various hooks.
delete_prote cted
If
true
, the virtual machine cannot be deleted.
A human-readable description in plain text.
description
display domain
The virtual machine display configuration.
Domain configured for this virtual machine.
655
Red Hat Virtualization 4.0 REST API Guide
Name fqdn
Type
Summary
Fully qualified domain name of the virtual machine.
guest_operat ing_system
What operating system is installed on the virtual machine.
guest_time_z one
What time zone is used by the virtual machine (as returned by guest agent).
high_availab ility
The virtual machine high availability configuration.
A unique identifier.
id
initializati on
io
Reference to virtual machine’s initialization configuration.
For performance tuning of IO threading.
large_icon
memory
Virtual machine’s large icon.
The virtual machine’s memory, in bytes.
memory_polic y
Reference to virtual machine’s memory management configuration.
migration
Reference to configuration of migration of running virtual machine to another host.
migration_do wntime
name
Maximum time the virtual machine can be non responsive during its live migration to another host in ms.
A human-readable name in plain text.
656
Name Type next_run_con figuration_e xists
CHAPTER 6. TYPES
Summary
Virtual machine configuration has been changed and requires restart of the virtual machine.
numa_tune_mo de
How the NUMA topology is applied.
origin
The origin of this virtual machine.
os payloads
Operating system type installed on the virtual machine.
Optional payloads of the virtual machine, used for ISOs to configure it.
placement_po licy
The configuration of the virtual machine’s placement policy.
rng_device
Random Number Generator device configuration for this virtual machine.
run_once
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 r
Virtual machine’s serial number in a cluster.
small_icon
Virtual machine’s small icon.
soundcard_en abled
sso
If
true
, the sound card is added to the virtual machine.
Reference to the Single Sign On configuration this virtual machine is configured for.
657
Red Hat Virtualization 4.0 REST API Guide
Name Type start_paused
Summary
If
true
, the virtual machine will be initially in 'paused' state after start.
The date in which the virtual machine was started.
start_time
stateless
If
true
, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.
The current status of the virtual machine.
status
status_detai l
stop_reason
stop_time
time_zone
tunnel_migra tion
type
Human readable detail of current status.
The reason the virtual machine was stopped.
The date in which the virtual machine was stopped.
The virtual machine’s time zone set by oVirt.
If
true
, the network data transfer will be encrypted during virtual machine live migration.
Determines whether the virtual machine is optimized for desktop or server.
usb
Configuration of USB devices for this virtual machine (count, type).
If
true
, the virtual machine is reconfigured to the latest version of it’s template when it is started.
use_latest_t emplate_vers ion
virtio_scsi
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 = 2
30
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.
660
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
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 affinity_lab els
Summary
Optional.
List of applications installed on the virtual machine.
applications
cdroms
Reference to the ISO mounted to the CDROM.
cluster
Reference to cluster the virtual machine belongs to.
cpu_profile
Reference to CPU profile used by this virtual machine.
disk_attachm ents
References the disks attached to the virtual machine.
external_hos t_provider
floppies
Reference to the ISO mounted to the floppy.
graphics_con soles
List of graphics consoles configured for this virtual machine.
host
host_devices
Reference to the host the virtual machine is running on.
References devices associated to this virtual machine.
instance_typ e
The virtual machine configuration can be optionally predefined via one of the instance types.
katello_erra ta
Lists all the Katello errata assigned to the virtual machine.
662
Name nics
Type
CHAPTER 6. TYPES
Summary
References the list of network interface devices on the virtual machine.
numa_nodes
Refers to the NUMA Nodes configuration used by this virtual machine.
permissions
Permissions set for this virtual machine.
quota
reported_dev ices
Reference to quota configuration set for this virtual machine.
sessions
List of user sessions opened for this virtual machine.
Refers to all snapshots taken from the virtual machine.
snapshots
statistics
Statistics data collected from this virtual machine.
storage_doma in
Reference to storage domain the virtual machine belongs to.
tags
template
Reference to the template the virtual machine is based on.
vm_pool
Reference to the pool the virtual machine is optionally member of.
watchdogs
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 migratable pinned user_migrata ble
Summary
664
6.268. VMBASE STRUCT
Represents basic virtual machine configuration. This is used by virtual machines, templates and instance types.
Table 6.350. Attributes summary
CHAPTER 6. TYPES
Name bios
Type
Summary
Reference to virtual machine’s BIOS configuration.
Free text containing comments about this object.
comment console
Console configured for this virtual machine.
The configuration of the virtual machine CPU.
cpu
cpu_shares
creation_tim e
custom_compa tibility_ver sion
custom_cpu_m odel
custom_emula ted_machine
The virtual machine creation date.
Virtual machine custom compatibility version.
custom_prope rties
Properties sent to VDSM to configure various hooks.
delete_prote cted
If
true
, the virtual machine cannot be deleted.
665
Red Hat Virtualization 4.0 REST API Guide
Name Type description
Summary
A human-readable description in plain text.
The virtual machine display configuration.
display domain
Domain configured for this virtual machine.
high_availab ility
The virtual machine high availability configuration.
A unique identifier.
id
initializati on
Reference to virtual machine’s initialization configuration.
For performance tuning of IO threading.
io
large_icon
memory
Virtual machine’s large icon.
The virtual machine’s memory, in bytes.
memory_polic y
Reference to virtual machine’s memory management configuration.
migration
Reference to configuration of migration of running virtual machine to another host.
migration_do wntime
name origin
Maximum time the virtual machine can be non responsive during its live migration to another host in ms.
A human-readable name in plain text.
The origin of this virtual machine.
666
Name os
CHAPTER 6. TYPES
Type Summary
Operating system type installed on the virtual machine.
rng_device
Random Number Generator device configuration for this virtual machine.
serial_numbe r
Virtual machine’s serial number in a cluster.
small_icon
Virtual machine’s small icon.
soundcard_en abled
sso
If
true
, the sound card is added to the virtual machine.
Reference to the Single Sign On configuration this virtual machine is configured for.
start_paused
If
true
, the virtual machine will be initially in 'paused' state after start.
stateless
time_zone
tunnel_migra tion
type
If
true
, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.
The virtual machine’s time zone set by oVirt.
If
true
, the network data transfer will be encrypted during virtual machine live migration.
usb
Determines whether the virtual machine is optimized for desktop or server.
Configuration of USB devices for this virtual machine (count, type).
667
Red Hat Virtualization 4.0 REST API Guide
Name Type virtio_scsi
Summary
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 = 2
30
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 cluster
Type
Summary
Reference to cluster the virtual machine belongs to.
cpu_profile
quota
Reference to CPU profile used by this virtual machine.
Reference to quota configuration set for this virtual machine.
storage_doma in
Reference to storage domain the virtual machine belongs to.
6.269. VMDEVICETYPE ENUM
Table 6.352. Values summary
Name cdrom
Summary floppy
6.270. VMPLACEMENTPOLICY STRUCT
670
Table 6.353. Attributes summary
Name affinity
Type
Summary
Table 6.354. Links summary
Name hosts
Type
Summary
6.271. VMPOOL STRUCT
Table 6.355. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
A human-readable description in plain text.
description
display id
max_user_vms
name
prestarted_v ms
rng_device
A unique identifier.
A human-readable name in plain text.
CHAPTER 6. TYPES
671
Red Hat Virtualization 4.0 REST API Guide
Name size
Type
Summary soundcard_en abled
stateful type
Virtual machine pool’s stateful flag.
use_latest_t 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 cluster
Type
Summary
Reference to the instance type on which this pool is based.
instance_typ e
permissions
template 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 automatic
Summary manual
6.273. VMSTATUS ENUM
Type represeting a status of a virtual machine.
Table 6.358. Values summary
Name down
Summary
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 ng
This status indicates that the hypervisor detected that the virtual machine is not 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 n
This status indicates that the virtual machine process is running and it is about to 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 ogress
This status indicates that the virtual machine process is running and the guest operating system is being rebooted.
restoring_st ate
This status indicates that the virtual machine process is about to run and the virtual 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 nch
This status indicates that the virtual machine process is about to run.
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.
674
6.273.2. powering_up
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 active
Type
Summary
675
Red Hat Virtualization 4.0 REST API Guide
Name migrating
Type
Summary total
6.275. VMTYPE ENUM
Type representing what the virtual machine is optimized for.
Table 6.360. Values summary
Name desktop
Summary
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 mode
Type Summary
Defines whether the vNIC will be implemented as a virtual device, or as a pass-through to a host device.
676
6.277. VNICPASSTHROUGHMODE ENUM
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
CHAPTER 6. TYPES
Name disabled
Summary
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
custom_prope rties
Free text containing comments about this object.
description
A human-readable description in plain text.
id
A unique identifier.
name
pass_through
port_mirrori ng
A human-readable name in plain text.
Table 6.364. Links summary
677
Red Hat Virtualization 4.0 REST API Guide
Name network
Type
Summary network_filt er
Network filter will enhance the admin ability to manage the network packets traffic from/to the participated VMs.
permissions
qos
6.279. VOLUMEGROUP STRUCT
Table 6.365. Attributes summary
Name id
Type
Summary logical_unit s
name
678
6.280. WATCHDOG STRUCT
This type represents a watchdog configuration.
Table 6.366. Attributes summary
Name action
Type Summary
Watchdog action to be performed when watchdog is triggered.
comment
Free text containing comments about this object.
CHAPTER 6. TYPES
Name Type description
id model
Summary
A human-readable description in plain text.
A unique identifier.
Model of watchdog device.
name
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 instance_typ e
Summary
Optionally references to an instance type the device is used by.
template
Optionally references to a template the device is used by.
vm vms
Don’t use this element, use
vms
instead.
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 dump
Summary
Virtual machine process will get core dumped to the default path on the host.
No action will be performed when watchdog action is triggered.
none pause
Virtual machine will be paused when watchdog action is triggered.
poweroff reset
Virtual machine will be powered off when watchdog action is triggered.
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 i6300esb
Summary
Currently only model supported is model I6300ESB.
680
6.283. WEIGHT STRUCT
Table 6.370. Attributes summary
Name comment
Type
Summary
Free text containing comments about this object.
description
A human-readable description in plain text.
Name factor id name
Type
Summary
A unique identifier.
A human-readable name in plain text.
Table 6.371. Links summary
Name Type scheduling_p olicy
Summary scheduling_p olicy_unit
CHAPTER 6. TYPES
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.
682
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 -
2
31
(-2147483648) and the maximum value is 2
31
-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
APPENDIX A. PRIMITIVE TYPES
StorageDomain.available
StorageDomain.used
StorageDomain.committed
VmBase.memory
For these exception cases the minimum value is -2
63
(-9223372036854775808) and the maximum value is 2
63
-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 1 st
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
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
RESTful API access
Manage virtual machines
Manage data centers
Manage storage domains
Control Red Hat Virtualization environment from applications
Integration with enterprise IT systems
Integration with third-party virtualization software
Automated maintenance or error-checking tasks
Automate repetitive tasks in a Red Hat Virtualization environment
Frequently asked questions
The preferred authentication mechanism is OAuth 2.0.
The scope parameter is mandatory and its value must be ovirt-app-api.
The API provides broad client support, is self-descriptive, and uses a resource-based model.
You can obtain the CA certificate by using the openssl s_client command line tool, downloading it from the Red Hat Virtualization Manager, or exporting it from the truststore.
Examples include the oVirt Python SDK, the oVirt Ruby SDK, the oVirt Java SDK, the cURL command line tool, and RESTClient.
