1. Introduction

The oVirt Engine provides a Representational State Transfer (REST) API. The API provides software developers and system administrators with control over their oVirt environment outside of the standard web interface. The API is useful for developers and administrators to integrate the functionality of a oVirt 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 oVirt environment with scripts.

This documentation acts as a reference for the oVirt API. It aims to provide developers and administrators with instructions and examples to help harness the functionality of their oVirt 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 oVirt API:

  • A networked installation of oVirt Engine, which includes the API.

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

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

2. Authentication and Security

2.1. TLS/SSL Certification

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

2.1.1. Obtaining the CA Certificate

You can obtain the CA certificate from the oVirt Engine 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
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----
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 oVirt Engine.

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 oVirt Engine, export the certificate from the truststore, and copy it to your client machine.

  1. Log in to the oVirt Engine machine as root.

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

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

    This creates a certificate file called ca.crt.

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

    $ scp ca.crt myuser@myclient.example.com:/home/myuser/.

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

2.1.2. Importing a Certificate to a Client

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

2.2. Authentication

Any user with a oVirt Engine 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 oVirt 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 oVirt 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 oVirt Engine 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 1. OAuth token request parameters
Name Value

grant_type

password

scope

ovirt-app-api

username

admin@internal

password

mypassword

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

grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
The scope parameter is described as optional in the OAuth RFC, but when using it with the oVirt API it is mandatory, and its value must be ovirt-app-api.

If the user name and password are valid, the oVirt Engine 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:

HTTP/1.1 401 Unauthorized

When this happens, a new token is needed, as the oVirt Engine 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

Basic authentication is supported only for backwards compatibility; it is deprecated since version 4.0 of oVirt, and will be removed in the future.

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

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

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. Encode an appropriate oVirt Engine 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. Encoding credentials for API access
Item Value

User name

admin

Domain

internal

Password

mypassword

Unencoded credentials

admin@internal:mypassword

Base64 encoded credentials

YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

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
Basic authentication involves potentially sensitive information, such as passwords, sent as plain text. The API requires Hypertext Transfer Protocol Secure (HTTPS) for transport-level encryption of plain-text requests.
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.

Requesting an Authenticated Session

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

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

HTTP/1.1 200 OK
...

    This returns a response with the following header:

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

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

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

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

3. Quick start example

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

  • A networked and configured oVirt installation;

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

  • oVirt’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.

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 oVirt.
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.
oVirt 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 oVirt environment.
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:

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

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

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

Same request, using the curl command:

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

The result will be an object of type Api:

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

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

# echo "ENGINE_API_DEFAULT_VERSION=3" > \
/etc/ovirt-engine/engine.conf.d/99-set-default-version.conf
# systemctl restart ovirt-engine

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

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

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

3.2. Example: List data centers

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

oVirt creates a Default hosts cluster on installation. This example uses the Default cluster to group resources in your oVirt 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

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

oVirt creates a default ovirtmgmt network on installation. This network acts as the management network for oVirt Engine 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' \
--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">
    <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>
  <description>My data</description>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>

The same request, using the curl command:

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

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

<storage_domain href="/ovirt-engine/api/storagedomains/005" id="005">
  <name>mydata</name>
  <description>My data</description>
  <available>42949672960</available>
  <committed>0</committed>
  <master>false</master>
  <status>unattached</status>
  <storage>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
    <type>nfs</type>
  </storage>
  <storage_format>v3</storage_format>
  <type>data</type>
  <used>9663676416</used>
</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>
  </host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains

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

<storage_domain href="/ovirt-engine/api/storagedomains/006" id="006">
  <name>myiso</name>
  <description>My ISOs</description>
  <available>42949672960</available>
  <committed>0</committed>
  <master>false</master>
  <status>unattached</status>
  <storage>
    <address>mynfs.example.com</address>
    <path>/exports/myisos</path>
    <type>nfs</type>
  </storage>
  <storage_format>v1</storage_format>
  <type>iso</type>
  <used>9663676416</used>
</storage_domain>

3.8. Example: Attach storage domains to data center

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

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

POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

With a request body like this:

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

Same request, using the curl command:

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

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

POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

With a request body like this:

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

Same request, using the curl command:

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

3.9. Example: Create virtual machine

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

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

POST /ovirt-engine/api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

And the request body should be like this:

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </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>
      <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>
  <description>My network interface card</description>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/nics

3.11. Example: Create virtual machine disk

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

The request should be like this:

POST /ovirt-engine/api/vms/007/diskattachments HTTP/1.1
Content-Type: application/xml
Accept: application/xml

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

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

Same request, using the curl command:

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

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

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

Same request, using the curl command:

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

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

3.13. Example: Start the virtual machine

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

The request should be like this:

POST /ovirt-engine/api/vms/007/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

The request body should be like this:

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

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.

4. Requests

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

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 3. Methods summary
Name Summary

get

Retrieve the affinity group details.

remove

Remove the affinity group.

update

Update the affinity group.

5.1.1. get GET

Retrieve the affinity group details.

<affinity_group id="00000000-0000-0000-0000-000000000000">
  <name>AF_GROUP_001</name>
  <cluster id="00000000-0000-0000-0000-000000000000"/>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
Table 4. Parameters summary
Name Type Direction Summary

group

AffinityGroup

Out

The affinity group.

5.1.2. remove DELETE

Remove the affinity group.

DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456
Table 5. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.1.3. update PUT

Update the affinity group.

Table 6. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

group

AffinityGroup

In/Out

The affinity group.

5.2. AffinityGroupVm

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

Table 7. Methods summary
Name Summary

remove

Remove this virtual machine from the affinity group.

5.2.1. remove DELETE

Remove this virtual machine from the affinity group.

Table 8. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.3. AffinityGroupVms

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

Table 9. Methods summary
Name Summary

add

Add a virtual machine to the affinity group.

list

List all virtual machines assigned to this affinity group.

5.3.1. add POST

Add a virtual machine to the affinity group.

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

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

With the following body:

<vm id="000-000"/>
Table 10. Parameters summary
Name Type Direction Summary

vm

Vm

In/Out

5.3.2. list GET

List all virtual machines assigned to this affinity group.

Table 11. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of virtual machines to return.

vms

Vm[]

Out
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 12. Methods summary
Name Summary

add

Create a new affinity group.

list

List existing affinity groups.

5.4.1. add POST

Create a new affinity group.

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

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

And use the following example in its body:

<affinity_group>
  <name>AF_GROUP_001</name>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
Table 13. Parameters summary
Name Type Direction Summary

group

AffinityGroup

In/Out

The affinity group object to create.

5.4.2. list GET

List existing affinity groups.

Table 14. Parameters summary
Name Type Direction Summary

groups

AffinityGroup[]

Out

The list of existing affinity groups.

max

Integer

In

Sets the maximum number of affinity groups to return.
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 15. Methods summary
Name Summary

get

Retrieves details about a label.

remove

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

update

Updates a label.

5.5.1. get GET

Retrieves details about a label.

Table 16. Parameters summary
Name Type Direction Summary

label

AffinityLabel

Out

5.5.2. remove DELETE

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

5.5.3. update PUT

Updates a label.

This call will update all metadata like name or description.

Table 17. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

5.6. AffinityLabelHost

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

Table 18. Methods summary
Name Summary

get

Retrieves details about a host that has this label assigned.

remove

Remove a label from a host.

5.6.1. get GET

Retrieves details about a host that has this label assigned.

Table 19. Parameters summary
Name Type Direction Summary

host

Host

Out

5.6.2. remove DELETE

Remove a label from a host.

5.7. AffinityLabelHosts

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

Table 20. Methods summary
Name Summary

add

Add a label to a host.

list

List all hosts with the label.

5.7.1. add POST

Add a label to a host.

Table 21. Parameters summary
Name Type Direction Summary

host

Host

In/Out

5.7.2. list GET

List all hosts with the label.

Table 22. Parameters summary
Name Type Direction Summary

hosts

Host[]

Out

5.8. AffinityLabelVm

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

Table 23. Methods summary
Name Summary

get

Retrieves details about a vm that has this label assigned.

remove

Remove a label from a vm.

5.8.1. get GET

Retrieves details about a vm that has this label assigned.

Table 24. Parameters summary
Name Type Direction Summary

vm

Vm

Out

5.8.2. remove DELETE

Remove a label from a vm.

5.9. AffinityLabelVms

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

Table 25. Methods summary
Name Summary

add

Add a label to a vm.

list

List all vms with the label.

5.9.1. add POST

Add a label to a vm.

Table 26. Parameters summary
Name Type Direction Summary

vm

Vm

In/Out

5.9.2. list GET

List all vms with the label.

Table 27. Parameters summary
Name Type Direction Summary

vms

Vm[]

Out

5.10. AffinityLabels

Manages the affinity labels available in the system.

Table 28. Methods summary
Name Summary

add

Creates a new label.

list

Lists all labels present in the system.

5.10.1. add POST

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

Table 29. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

5.10.2. list GET

Lists all labels present in the system.

Table 30. Parameters summary
Name Type Direction Summary

labels

AffinityLabel[]

Out

max

Integer

In

Sets the maximum number of labels to return.
max

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

5.11. Area

This annotation is intended to specify what oVirt area is the annotated concept related to. Currently the following areas are in use, and they are closely related to the oVirt teams, but not necessarily the same:

  • Infrastructure

  • Network

  • SLA

  • Storage

  • Virtualization

A concept may be associated to more than one area, or to no area.

The value of this annotation is intended for reporting only, and it doesn’t affect at all the generated code or the validity of the model

5.12. AssignedAffinityLabel

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

Table 31. Methods summary
Name Summary

get

Retrieves details about the attached label.

remove

Removes the label from an entity.

5.12.1. get GET

Retrieves details about the attached label.

Table 32. Parameters summary
Name Type Direction Summary

label

AffinityLabel

Out

5.12.2. remove DELETE

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

5.13. AssignedAffinityLabels

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

Table 33. Methods summary
Name Summary

add

Attaches a label to an entity.

list

Lists all labels that are attached to an entity.

5.13.1. add POST

Attaches a label to an entity.

Table 34. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

5.13.2. list GET

Lists all labels that are attached to an entity.

Table 35. Parameters summary
Name Type Direction Summary

label

AffinityLabel[]

Out

5.14. AssignedCpuProfile

Table 36. Methods summary
Name Summary

get

remove

5.14.1. get GET

Table 37. Parameters summary
Name Type Direction Summary

profile

CpuProfile

Out

5.14.2. remove DELETE

Table 38. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.15. AssignedCpuProfiles

Table 39. Methods summary
Name Summary

add

list

5.15.1. add POST

Table 40. Parameters summary
Name Type Direction Summary

profile

CpuProfile

In/Out

5.15.2. list GET

Table 41. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

CpuProfile[]

Out
max

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

5.16. AssignedDiskProfile

Table 42. Methods summary
Name Summary

get

remove

5.16.1. get GET

Table 43. Parameters summary
Name Type Direction Summary

disk_profile

DiskProfile

Out

5.16.2. remove DELETE

Table 44. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.17. AssignedDiskProfiles

Table 45. Methods summary
Name Summary

add

list

5.17.1. add POST

Table 46. Parameters summary
Name Type Direction Summary

profile

DiskProfile

In/Out

5.17.2. list GET

Table 47. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

DiskProfile[]

Out
max

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

5.18. AssignedNetwork

Table 48. Methods summary
Name Summary

get

remove

update

5.18.1. get GET

Table 49. Parameters summary
Name Type Direction Summary

network

Network

Out

5.18.2. remove DELETE

Table 50. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.18.3. update PUT

Table 51. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

network

Network

In/Out

5.19. AssignedNetworks

Table 52. Methods summary
Name Summary

add

list

5.19.1. add POST

Table 53. Parameters summary
Name Type Direction Summary

network

Network

In/Out

5.19.2. list GET

Table 54. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out
max

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

5.20. AssignedPermissions

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

Table 55. Methods summary
Name Summary

add

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

list

List all the permissions of the specific entity.

5.20.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"/>
</permission>
Table 56. Parameters summary
Name Type Direction Summary

permission

Permission

In/Out

The permission.

5.20.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 57. Parameters summary
Name Type Direction Summary

permissions

Permission[]

Out

The list of permissions.

5.21. AssignedRoles

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

Table 58. Methods summary
Name Summary

list

5.21.1. list GET

Table 59. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out
max

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

5.22. AssignedTag

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

Table 60. Methods summary
Name Summary

get

Gets the information about the assigned tag.

remove

Unassign tag from specific entity in the system.

5.22.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
<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 61. Parameters summary
Name Type Direction Summary

tag

Tag

Out

The assigned tag.

5.22.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 62. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.23. AssignedTags

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

Table 63. Methods summary
Name Summary

add

Assign tag to specific entity in the system.

list

List all tags assigned to the specific entity.

5.23.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 64. Parameters summary
Name Type Direction Summary

tag

Tag

In/Out

The assigned tag.

5.23.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 65. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

The list of assigned tags.
max

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

5.24. AssignedVnicProfile

Table 66. Methods summary
Name Summary

get

remove

5.24.1. get GET

Table 67. Parameters summary
Name Type Direction Summary

profile

VnicProfile

Out

5.24.2. remove DELETE

Table 68. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.25. AssignedVnicProfiles

Table 69. Methods summary
Name Summary

add

list

5.25.1. add POST

Table 70. Parameters summary
Name Type Direction Summary

profile

VnicProfile

In/Out

5.25.2. list GET

Table 71. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

Out
max

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

5.26. AttachedStorageDomain

Table 72. Methods summary
Name Summary

activate

This operation activates an attached storage domain.

deactivate

This operation deactivates an attached storage domain.

get

remove

5.26.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 73. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

5.26.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 74. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

5.26.3. get GET

Table 75. Parameters summary
Name Type Direction Summary

storage_domain

StorageDomain

Out

5.26.4. remove DELETE

Table 76. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.27. AttachedStorageDomainDisk

Manages a single disk available in a storage domain attached to a data center.

Since version 4.2 of the engine this service is intended only to list disks available in the storage domain, and to register unregistered disks. All the other operations, like copying a disk, moving a disk, etc, have been deprecated and will be removed in the future. To perform those operations use the service that manages all the disks of the system, or the service that manages an specific disk.
Table 77. Methods summary
Name Summary

copy

Copies a disk to the specified storage domain.

export

Exports a disk to an export storage domain.

get

Retrieves the description of the disk.

move

Moves a disk to another storage domain.

register

Registers an unregistered disk.

remove

Removes a disk.

sparsify

Sparsify the disk.

update

Updates the disk.

5.27.1. copy POST

Copies a disk to the specified storage domain.

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To copy a disk use the copy operation of the service that manages that disk.
Table 78. Parameters summary
Name Type Direction Summary

disk

Disk

In

Description of the resulting disk.

storage_domain

StorageDomain

In

The storage domain where the new disk will be created.

5.27.2. export POST

Exports a disk to an export storage domain.

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To export a disk use the export operation of the service that manages that disk.
Table 79. Parameters summary
Name Type Direction Summary

storage_domain

StorageDomain

In

The export storage domain where the disk should be exported to.

5.27.3. get GET

Retrieves the description of the disk.

Table 80. Parameters summary
Name Type Direction Summary

disk

Disk

Out

The description of the disk.

5.27.4. move POST

Moves a disk to another storage domain.

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To move a disk use the move operation of the service that manages that disk.
Table 81. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the move should be performed asynchronously.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

storage_domain

StorageDomain

In

The storage domain where the disk will be moved to.

5.27.5. register POST

Registers an unregistered disk.

5.27.6. remove DELETE

Removes a disk.

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk.

5.27.7. sparsify POST

Sparsify the disk.

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk.

5.27.8. update PUT

Updates the disk.

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To update a disk use the update operation of the service that manages that disk.
Table 82. Parameters summary
Name Type Direction Summary

disk

Disk

In/Out

The update to apply to the disk.

5.28. AttachedStorageDomainDisks

Manages the collection of disks available inside an storage domain that is attached to a data center.

Table 83. Methods summary
Name Summary

add

Adds or registers a disk.

list

Retrieve the list of disks that are available in the storage domain.

5.28.1. add POST

Adds or registers a disk.

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To add a new disk use the add operation of the service that manages the disks of the system. To register an unregistered disk use the register operation of the service that manages that disk.
Table 84. Parameters summary
Name Type Direction Summary

disk

Disk

In/Out

The disk to add or register.

unregistered

Boolean

In

Indicates if a new disk should be added or if an existing unregistered disk should be registered.
unregistered

Indicates if a new disk should be added or if an existing unregistered disk should be registered. If the value is true then the identifier of the disk to register needs to be provided. For example, to register the disk with id 456 send a request like this:

POST /ovirt-engine/api/storagedomains/123/disks?unregistered=true

With a request body like this:

<disk id="456"/>

If the value is false then a new disk will be created in the storage domain. In that case the provisioned_size, format and name attributes are mandatory. For example, to create a new copy on write disk of 1 GiB, send a request like this:

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

With a request body like this:

<disk>
  <name>mydisk</name>
  <format>cow</format>
  <provisioned_size>1073741824</provisioned_size>
</disk>

The default value is false.

5.28.2. list GET

Retrieve the list of disks that are available in the storage domain.

Table 85. Parameters summary
Name Type Direction Summary

disks

Disk[]

Out

List of retrieved disks.

max

Integer

In

Sets the maximum number of disks to return.
max

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

5.29. AttachedStorageDomains

Table 86. Methods summary
Name Summary

add

list

5.29.1. add POST

Table 87. Parameters summary
Name Type Direction Summary

storage_domain

StorageDomain

In/Out

5.29.2. list GET

Table 88. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of storage domains to return.

storage_domains

StorageDomain[]

Out
max

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

5.30. Balance

Table 89. Methods summary
Name Summary

get

remove

5.30.1. get GET

Table 90. Parameters summary
Name Type Direction Summary

balance

Balance

Out

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

5.30.2. remove DELETE

Table 91. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.31. Balances

Table 92. Methods summary
Name Summary

add

list

5.31.1. add POST

Table 93. Parameters summary
Name Type Direction Summary

balance

Balance

In/Out

5.31.2. list GET

Table 94. Parameters summary
Name Type Direction Summary

balances

Balance[]

Out

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

max

Integer

In

Sets the maximum number of balances to return.
max

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

5.32. Bookmark

A service to manage a bookmark.

Table 95. Methods summary
Name Summary

get

Get a bookmark.

remove

Remove a bookmark.

update

Update a bookmark.

5.32.1. get GET

Get a bookmark.

An example for getting a bookmark:

GET /ovirt-engine/api/bookmarks/123
<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
  <name>example_vm</name>
  <value>vm: name=example*</value>
</bookmark>
Table 96. Parameters summary
Name Type Direction Summary

bookmark

Bookmark

Out

The requested bookmark.

5.32.2. remove DELETE

Remove a bookmark.

An example for removing a bookmark:

DELETE /ovirt-engine/api/bookmarks/123
Table 97. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.32.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 98. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bookmark

Bookmark

In/Out

The updated bookmark.

5.33. Bookmarks

A service to manage bookmarks.

Table 99. Methods summary
Name Summary

add

Adding a new bookmark.

list

Listing all the available bookmarks.

5.33.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 100. Parameters summary
Name Type Direction Summary

bookmark

Bookmark

In/Out

The added bookmark.

5.33.2. list GET

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 101. Parameters summary
Name Type Direction Summary

bookmarks

Bookmark[]

Out

The list of available bookmarks.

max

Integer

In

Sets the maximum number of bookmarks to return.
max

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

5.34. Cluster

A service to manage specific cluster.

Table 102. Methods summary
Name Summary

get

Get information about the cluster.

remove

Removes cluster from the system.

resetemulatedmachine

update

Updates information about the cluster.

5.34.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>
  <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 103. Parameters summary
Name Type Direction Summary

cluster

Cluster

Out

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

5.34.2. remove DELETE

Removes cluster from the system.

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
Table 104. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.34.3. resetemulatedmachine POST

Table 105. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

5.34.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 106. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

cluster

Cluster

In/Out

5.35. ClusterLevel

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

Table 107. Methods summary
Name Summary

get

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

5.35.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>
    </permit>
    ...
  </permits>
</cluster_level>
Table 108. Parameters summary
Name Type Direction Summary

level

ClusterLevel

Out

Retreived cluster level.

5.36. 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 109. Methods summary
Name Summary

list

Lists the cluster levels supported by the system.

5.36.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 110. Parameters summary
Name Type Direction Summary

levels

ClusterLevel[]

Out

Retrieved cluster levels.

5.37. Clusters

A service to manage clusters.

Table 111. Methods summary
Name Summary

add

Creates a new cluster.

list

5.37.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 112. Parameters summary
Name Type Direction Summary

cluster

Cluster

In/Out

5.37.2. list GET

Table 113. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

clusters

Cluster[]

Out

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

max

Integer

In

Sets the maximum number of clusters to return.

search

String

In

A query string used to restrict the returned clusters.
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.

max

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

5.38. Copyable

Table 114. Methods summary
Name Summary

copy

5.38.1. copy POST

Table 115. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

5.39. CpuProfile

Table 116. Methods summary
Name Summary

get

remove

update

5.39.1. get GET

Table 117. Parameters summary
Name Type Direction Summary

profile

CpuProfile

Out

5.39.2. remove DELETE

Table 118. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.39.3. update PUT

Table 119. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

CpuProfile

In/Out

5.40. CpuProfiles

Table 120. Methods summary
Name Summary

add

list

5.40.1. add POST

Table 121. Parameters summary
Name Type Direction Summary

profile

CpuProfile

In/Out

5.40.2. list GET

Table 122. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of profiles to return.

profile

CpuProfile[]

Out
max

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

5.41. DataCenter

A service to manage a data center.

Table 123. Methods summary
Name Summary

get

Get a data center.

remove

Removes the data center.

update

Updates the data center.

5.41.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"/>
  <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 124. Parameters summary
Name Type Direction Summary

data_center

DataCenter

Out

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

5.41.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 125. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

force

Boolean

In

Indicates if the operation should succeed, and the storage domain removed from the database, even if something fails during the operation.
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.41.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 126. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

data_center

DataCenter

In/Out

The data center that is being updated.

5.42. DataCenters

A service to manage data centers.

Table 127. Methods summary
Name Summary

add

Creates a new data center.

list

Lists the data centers.

5.42.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 128. Parameters summary
Name Type Direction Summary

data_center

DataCenter

In/Out

The data center that is being added.

5.42.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 \
--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 129. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

data_centers

DataCenter[]

Out

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

max

Integer

In

Sets the maximum number of data centers to return.

search

String

In

A query string used to restrict the returned data centers.
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.

max

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

5.43. Disk

Manages a single disk.

Table 130. Methods summary
Name Summary

copy

This operation copies a disk to the specified storage domain.

export

Exports a disk to an export storage domain.

get

Retrieves the description of the disk.

move

Moves a disk to another storage domain.

remove

Removes a disk.

sparsify

Sparsify the disk.

update

This operation updates the disk with the appropriate parameters.

5.43.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 131. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

disk

Disk

In

Description of the resulting disk.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

storage_domain

StorageDomain

In

The storage domain where the new disk will be created.
disk

Description of the resulting disk. The only accepted value is the name attribute, which will be the name used for the new disk. For example, to copy disk 123 using myname as the name for the new disk, send a request like this:

POST /ovirt-engine/disks/123

With a request body like this:

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

The storage domain where the new disk will be created. Can be specified using the id or name attributes. For example, to copy a disk to the storage domain named mydata send a request like this:

POST /ovirt-engine/api/storagedomains/123/disks/789

With a request body like this:

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

5.43.2. export POST

Exports a disk to an export storage domain.

Table 132. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the export should be performed asynchronously.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

storage_domain

StorageDomain

In

The export storage domain where the disk should be exported to.

5.43.3. get GET

Retrieves the description of the disk.

Table 133. Parameters summary
Name Type Direction Summary

disk

Disk

Out

The description of the disk.

5.43.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 134. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the move should be performed asynchronously.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

storage_domain

StorageDomain

In

The storage domain where the disk will be moved to.

5.43.5. remove DELETE

Removes a disk.

Table 135. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.43.6. sparsify POST

Sparsify the disk.

Sparsification frees space in the disk image that is not used by its filesystem. As a result, the image will occupy less space on the storage.

Currently sparsification works only on disks without snapshots. Disks having derived disks are also not allowed.

5.43.7. update PUT

This operation updates the disk with the appropriate parameters. The only field that can be updated is qcow_version.

For example, update disk can be facilitated using the following request:

PUT /ovirt-engine/api/disks/123

With a request body like this:

<disk>
  <qcow_version>qcow2_v3</qcow_version>
</disk>

Since the backend operation is asynchronous the disk element which will be returned to the user might not be synced with the changed properties.

Table 136. Parameters summary
Name Type Direction Summary

disk

Disk

In/Out

The update to apply to the disk.

5.44. DiskAttachment

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

Table 137. Methods summary
Name Summary

get

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

remove

Removes the disk attachment.

update

Update the disk attachment and the disk properties within it.

5.44.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
<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 138. Parameters summary
Name Type Direction Summary

attachment

DiskAttachment

Out

5.44.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 139. Parameters summary
Name Type Direction Summary

detach_only

Boolean

In

Indicates if the disk should only be detached from the virtual machine, but not removed from the system.
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.44.3. update PUT

Update the disk attachment and the disk properties within it.

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 140. Parameters summary
Name Type Direction Summary

disk_attachment

DiskAttachment

In/Out

5.45. 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 141. Methods summary
Name Summary

add

Adds a new disk attachment to the virtual machine.

list

List the disk that are attached to the virtual machine.

5.45.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>
  <pass_discard>true</pass_discard>
  <interface>ide</interface>
  <active>true</active>
  <disk id="123"/>
</disk_attachment>

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

<disk_attachment>
  <bootable>true</bootable>
  <pass_discard>true</pass_discard>
  <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
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 142. Parameters summary
Name Type Direction Summary

attachment

DiskAttachment

In/Out

5.45.2. list GET

List the disk that are attached to the virtual machine.

Table 143. Parameters summary
Name Type Direction Summary

attachments

DiskAttachment[]

Out

5.46. DiskProfile

Table 144. Methods summary
Name Summary

get

remove

update

5.46.1. get GET

Table 145. Parameters summary
Name Type Direction Summary

profile

DiskProfile

Out

5.46.2. remove DELETE

Table 146. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.46.3. update PUT

Table 147. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

DiskProfile

In/Out

5.47. DiskProfiles

Table 148. Methods summary
Name Summary

add

list

5.47.1. add POST

Table 149. Parameters summary
Name Type Direction Summary

profile

DiskProfile

In/Out

5.47.2. list GET

Table 150. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of profiles to return.

profile

DiskProfile[]

Out
max

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

5.48. DiskSnapshot

Table 151. Methods summary
Name Summary

get

remove

5.48.1. get GET

Table 152. Parameters summary
Name Type Direction Summary

snapshot

DiskSnapshot

Out

5.48.2. remove DELETE

Table 153. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.49. DiskSnapshots

Table 154. Methods summary
Name Summary

list

5.49.1. list GET

Table 155. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

DiskSnapshot[]

Out
max

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

5.50. Disks

Manages the collection of disks available in the system.

Table 156. Methods summary
Name Summary

add

Adds a new floating disk.

list

Get list of disks.

5.50.1. add POST

Adds a new floating disk.

There are three types of disks that can be added - disk image, direct LUN and Cinder disk.

Adding a new image disk:

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

To create a new floating image disk with specified provisioned_size, format and name on a storage domain with an id 123, send a request as follows:

POST /ovirt-engine/api/disks

With a request body as follows:

<disk>
  <storage_domains>
    <storage_domain id="123"/>
  </storage_domains>
  <name>mydisk</name>
  <provisioned_size>1048576</provisioned_size>
  <format>cow</format>
</disk>

Adding a new direct LUN disk:

When adding a new floating direct LUN via the API, there are two flavors that can be used:

  1. With a host element - in this case, the host is used for sanity checks (e.g., that the LUN is visible) and to retrieve basic information about the LUN (e.g., size and serial).

  2. Without a host element - in this case, the operation is a database-only operation, and the storage is never accessed.

To create a new floating direct LUN disk with a host element with an id 123, specified alias, type and logical_unit with an id 456 (that has the attributes address, port and target), send a request as follows:

POST /ovirt-engine/api/disks

With a request body as follows:

<disk>
  <alias>mylun</alias>
  <lun_storage>
    <host id="123"/>
    <type>iscsi</type>
    <logical_units>
      <logical_unit id="456">
        <address>10.35.10.20</address>
        <port>3260</port>
        <target>iqn.2017-01.com.myhost:444</target>
      </logical_unit>
    </logical_units>
  </lun_storage>
</disk>

To create a new floating direct LUN disk without using a host, remove the host element.

Adding a new Cinder disk:

To create a new floating Cinder disk, send a request as follows:

POST /ovirt-engine/api/disks

With a request body as follows:

<disk>
  <openstack_volume_type>
    <name>myceph</name>
  </openstack_volume_type>
  <storage_domains>
    <storage_domain>
      <name>cinderDomain</name>
    </storage_domain>
  </storage_domains>
  <provisioned_size>1073741824</provisioned_size>
  <interface>virtio</interface>
  <format>raw</format>
</disk>
Table 157. Parameters summary
Name Type Direction Summary

disk

Disk

In/Out

The disk.

5.50.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 158. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

disks

Disk[]

Out

List of retrieved disks.

max

Integer

In

Sets the maximum number of disks to return.

search

String

In

A query string used to restrict the returned disks.
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.

max

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

5.51. Domain

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

Table 159. Methods summary
Name Summary

get

Gets the authentication domain information.

5.51.1. get GET

Gets the authentication domain information.

Usage:

GET /ovirt-engine/api/domains/5678

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 160. Parameters summary
Name Type Direction Summary

domain

Domain

Out

The authentication domain.

5.52. DomainGroup

Table 161. Methods summary
Name Summary

get

5.52.1. get GET

Table 162. Parameters summary
Name Type Direction Summary

get

Group

Out

5.53. DomainGroups

Table 163. Methods summary
Name Summary

list

5.53.1. list GET

Table 164. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

groups

Group[]

Out

max

Integer

In

Sets the maximum number of groups to return.

search

String

In

A query string used to restrict the returned groups.
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.

max

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

5.54. DomainUser

A service to view a domain user in the system.

Table 165. Methods summary
Name Summary

get

Gets the domain user information.

5.54.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 166. Parameters summary
Name Type Direction Summary

user

User

Out

The domain user.

5.55. DomainUsers

A service to list all domain users in the system.

Table 167. Methods summary
Name Summary

list

List all the users in the domain.

5.55.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 168. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

max

Integer

In

Sets the maximum number of users to return.

search

String

In

A query string used to restrict the returned users.

users

User[]

Out

The list of users in the domain.
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.

max

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

5.56. Domains

A service to list all authentication domains in the system.

Table 169. Methods summary
Name Summary

list

List all the authentication domains in the system.

5.56.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 170. Parameters summary
Name Type Direction Summary

domains

Domain[]

Out

The list of domains.

max

Integer

In

Sets the maximum number of domains to return.
max

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

5.57. EngineKatelloErrata

A service to manage Katello errata assigned to the engine. The information is retrieved from Katello.

Table 171. Methods summary
Name Summary

list

Retrieves the representation of the Katello errata.

5.57.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 172. Parameters summary
Name Type Direction Summary

errata

KatelloErratum[]

Out

A representation of Katello errata.

max

Integer

In

Sets the maximum number of errata to return.
max

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

5.58. Event

A service to manage an event in the system.

Table 173. Methods summary
Name Summary

get

Get an event.

remove

Removes an event from internal audit log.

5.58.1. get GET

Get an event.

An example of getting an event:

GET /ovirt-engine/api/events/123
<event href="/ovirt-engine/api/events/123" id="123">
  <description>Host example.com was added by admin@internal-authz.</description>
  <code>42</code>
  <correlation_id>135</correlation_id>
  <custom_id>-1</custom_id>
  <flood_rate>30</flood_rate>
  <origin>oVirt</origin>
  <severity>normal</severity>
  <time>2016-12-11T11:13:44.654+02:00</time>
  <cluster href="/ovirt-engine/api/clusters/456" id="456"/>
  <host href="/ovirt-engine/api/hosts/789" id="789"/>
  <user href="/ovirt-engine/api/users/987" id="987"/>
</event>

Note that the number of fields changes according to the information that resides on the event. For example, for storage domain related events you will get the storage domain reference, as well as the reference for the data center this storage domain resides in.

Table 174. Parameters summary
Name Type Direction Summary

event

Event

Out

5.58.2. remove DELETE

Removes an event from internal audit log.

An event can be removed by sending following request

DELETE /ovirt-engine/api/events/123
Table 175. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.59. Events

A service to manage events in the system.

Table 176. Methods summary
Name Summary

add

Adds an external event to the internal audit log.

list

Get list of events.

undelete

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

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>
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 177. Parameters summary
Name Type Direction Summary

event

Event

In/Out

5.59.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>
    <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 178. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

events

Event[]

Out

from

Integer

In

Indicates the identifier of the the first event that should be returned.

max

Integer

In

Sets the maximum number of events to return.

search

String

In

The events service provides search queries similar to other resource services.
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.

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:

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.

max

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

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:

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.59.3. undelete POST

Table 179. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the un-delete should be performed asynchronously.

5.60. ExternalComputeResource

Table 180. Methods summary
Name Summary

get

5.60.1. get GET

Table 181. Parameters summary
Name Type Direction Summary

resource

ExternalComputeResource

Out

5.61. ExternalComputeResources

Table 182. Methods summary
Name Summary

list

5.61.1. list GET

Table 183. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of resources to return.

resources

ExternalComputeResource[]

Out
max

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

5.62. ExternalDiscoveredHost

Table 184. Methods summary
Name Summary

get

5.62.1. get GET

Table 185. Parameters summary
Name Type Direction Summary

host

ExternalDiscoveredHost

Out

5.63. ExternalDiscoveredHosts

Table 186. Methods summary
Name Summary

list

5.63.1. list GET

Table 187. Parameters summary
Name Type Direction Summary

hosts

ExternalDiscoveredHost[]

Out

max

Integer

In

Sets the maximum number of hosts to return.
max

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

5.64. ExternalHost

Table 188. Methods summary
Name Summary

get

5.64.1. get GET

Table 189. Parameters summary
Name Type Direction Summary

host

ExternalHost

Out

5.65. ExternalHostGroup

Table 190. Methods summary
Name Summary

get

5.65.1. get GET

Table 191. Parameters summary
Name Type Direction Summary

group

ExternalHostGroup

Out

5.66. ExternalHostGroups

Table 192. Methods summary
Name Summary

list

5.66.1. list GET

Table 193. Parameters summary
Name Type Direction Summary

groups

ExternalHostGroup[]

Out

max

Integer

In

Sets the maximum number of groups to return.
max

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

5.67. ExternalHostProvider

Table 194. Methods summary
Name Summary

get

importcertificates

remove

testconnectivity

update

5.67.1. get GET

Table 195. Parameters summary
Name Type Direction Summary

provider

ExternalHostProvider

Out

5.67.2. importcertificates POST

Table 196. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

5.67.3. remove DELETE

Table 197. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.67.4. testconnectivity POST

Table 198. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the test should be performed asynchronously.

5.67.5. update PUT

Table 199. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

ExternalHostProvider

In/Out

5.68. ExternalHostProviders

Table 200. Methods summary
Name Summary

add

list

5.68.1. add POST

Table 201. Parameters summary
Name Type Direction Summary

provider

ExternalHostProvider

In/Out

5.68.2. list GET

Table 202. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of providers to return.

providers

ExternalHostProvider[]

Out
max

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

5.69. ExternalHosts

Table 203. Methods summary
Name Summary

list

5.69.1. list GET

Table 204. Parameters summary
Name Type Direction Summary

hosts

ExternalHost[]

Out

max

Integer

In

Sets the maximum number of hosts to return.
max

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

5.70. ExternalProvider

Table 205. Methods summary
Name Summary

importcertificates

testconnectivity

5.70.1. importcertificates POST

Table 206. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

5.70.2. testconnectivity POST

Table 207. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the test should be performed asynchronously.

5.71. ExternalProviderCertificate

Table 208. Methods summary
Name Summary

get

5.71.1. get GET

Table 209. Parameters summary
Name Type Direction Summary

certificate

Certificate

Out

5.72. ExternalProviderCertificates

Table 210. Methods summary
Name Summary

list

5.72.1. list GET

Table 211. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

Out

max

Integer

In

Sets the maximum number of certificates to return.
max

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

5.73. ExternalVmImports

Provides capability to import external virtual machines.

Table 212. Methods summary
Name Summary

add

This operation is used to import a virtual machine from external hypervisor, such as KVM, XEN or VMware.

5.73.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 213. Parameters summary
Name Type Direction Summary

import

ExternalVmImport

In/Out

5.74. FenceAgent

Table 214. Methods summary
Name Summary

get

remove

update

5.74.1. get GET

Table 215. Parameters summary
Name Type Direction Summary

agent

Agent

Out

5.74.2. remove DELETE

Table 216. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.74.3. update PUT

Table 217. Parameters summary
Name Type Direction Summary

agent

Agent

In/Out

async

Boolean

In

Indicates if the update should be performed asynchronously.

5.75. FenceAgents

Table 218. Methods summary
Name Summary

add

list

5.75.1. add POST

Table 219. Parameters summary
Name Type Direction Summary

agent

Agent

In/Out

5.75.2. list GET

Table 220. Parameters summary
Name Type Direction Summary

agents

Agent[]

Out

max

Integer

In

Sets the maximum number of agents to return.
max

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

5.76. File

Table 221. Methods summary
Name Summary

get

5.76.1. get GET

Table 222. Parameters summary
Name Type Direction Summary

file

File

Out

5.77. 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 223. Methods summary
Name Summary

list

5.77.1. list GET

Table 224. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

file

File[]

Out

max

Integer

In

Sets the maximum number of files to return.

search

String

In

A query string used to restrict the returned files.
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.

max

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

5.78. Filter

Table 225. Methods summary
Name Summary

get

remove

5.78.1. get GET

Table 226. Parameters summary
Name Type Direction Summary

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

result

Filter

Out

5.78.2. remove DELETE

Table 227. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.79. Filters

Table 228. Methods summary
Name Summary

add

list

5.79.1. add POST

Table 229. Parameters summary
Name Type Direction Summary

filter

Filter

In/Out

5.79.2. list GET

Table 230. Parameters summary
Name Type Direction Summary

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

filters

Filter[]

Out

max

Integer

In

Sets the maximum number of filters to return.
max

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

5.80. GlusterBrick

This service manages a single gluster brick.

Table 231. Methods summary
Name Summary

get

Get details of a brick.

remove

Removes a brick.

replace

Replaces this brick with a new one.

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

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,swidth=2048,noquota</mnt_options>
  <pid>25589</pid>
  <port>49155</port>
</brick>
Table 232. Parameters summary
Name Type Direction Summary

brick

GlusterBrick

Out

5.80.2. remove DELETE

Removes a brick.

Removes a brick from the underlying gluster volume and deletes entries from database. This can be used only when removing a single brick without data migration. To remove multiple bricks and with data migration, use migrate instead.

For example, to delete brick 234 from gluster volume 123, send a request like this:

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234
Table 233. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.80.3. replace POST

Replaces this brick with a new one.

This operation has been deprecated since version 3.5 of the engine and will be removed in the future. Use add brick(s) and migrate brick(s) instead.
Table 234. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the replacement should be performed asynchronously.

force

Boolean

In

5.81. GlusterBricks

This service manages the gluster bricks in a gluster volume

Table 235. Methods summary
Name Summary

activate

Activate the bricks post data migration of remove brick operation.

add

Adds a list of bricks to gluster volume.

list

Lists the bricks of a gluster volume.

migrate

Start migration of data prior to removing bricks.

remove

Removes bricks from gluster volume.

stopmigrate

Stops migration of data from bricks for a remove brick operation.

5.81.1. activate POST

Activate the bricks post data migration of remove brick operation.

Used to activate brick(s) once the data migration from bricks is complete but user no longer wishes to remove bricks. The bricks that were previously marked for removal will now be used as normal bricks.

For example, to retain the bricks that on glustervolume 123 from which data was migrated, send a request like this:

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/activate

With a request body like this:

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>
Table 236. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

bricks

GlusterBrick[]

In

The list of bricks that need to be re-activated.

5.81.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 237. Parameters summary
Name Type Direction Summary

bricks

GlusterBrick[]

In/Out

The list of bricks to be added to the volume

replica_count

Integer

In

Replica count of volume post add operation.

stripe_count

Integer

In

Stripe count of volume post add operation.

5.81.3. list GET

Lists the bricks of a gluster volume.

For example, to list bricks of gluster volume 123, send a request like this:

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 238. Parameters summary
Name Type Direction Summary

bricks

GlusterBrick[]

Out

max

Integer

In

Sets the maximum number of bricks to return.
max

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

5.81.4. migrate POST

Start migration of data prior to removing bricks.

Removing bricks is a two-step process, where the data on bricks to be removed, is first migrated to remaining bricks. Once migration is completed the removal of bricks is confirmed via the API remove. If at any point, the action needs to be cancelled stopmigrate has to be called.

For instance, to delete a brick from a gluster volume with id 123, send a request:

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/migrate

With a request body like this:

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>

The migration process can be tracked from the job id returned from the API using job and steps in job using step

Table 239. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the migration should be performed asynchronously.

bricks

GlusterBrick[]

In

List of bricks for which data migration needs to be started.

5.81.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 240. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

bricks

GlusterBrick[]

In

The list of bricks to be removed

replica_count

Integer

In

Replica count of volume post add operation.

5.81.6. stopmigrate POST

Stops migration of data from bricks for a remove brick operation.

To cancel data migration that was started as part of the 2-step remove brick process in case the user wishes to continue using the bricks. The bricks that were marked for removal will function as normal bricks post this operation.

For example, to stop migration of data from the bricks of gluster volume 123, send a request like this:

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/stopmigrate

With a request body like this:

<bricks>
  <brick>
    <name>host:brick_directory</name>
  </brick>
</bricks>
Table 241. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

bricks

GlusterBrick[]

In

List of bricks for which data migration needs to be stopped.
bricks

List of bricks for which data migration needs to be stopped. This list should match the arguments passed to migrate.

5.82. GlusterHook

Table 242. Methods summary
Name Summary

disable

Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the cluster.

enable

Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the cluster.

get

remove

Removes the this Gluster hook from all servers in cluster and deletes it from the database.

resolve

Resolves missing hook conflict depending on the resolution type.

5.82.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 243. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

5.82.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 244. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

5.82.3. get GET

Table 245. Parameters summary
Name Type Direction Summary

hook

GlusterHook

Out

5.82.4. remove DELETE

Removes the this Gluster hook from all servers in cluster and deletes it from the database.

Table 246. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.82.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 247. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

host

Host

In

resolution_type

String

In

5.83. GlusterHooks

Table 248. Methods summary
Name Summary

list

5.83.1. list GET

Table 249. Parameters summary
Name Type Direction Summary

hooks

GlusterHook[]

Out

max

Integer

In

Sets the maximum number of hooks to return.
max

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

5.84. GlusterVolume

This service manages a single gluster volume.

Table 250. Methods summary
Name Summary

get

Get the gluster volume details.

getprofilestatistics

Get gluster volume profile statistics.

rebalance

Rebalance the gluster volume.

remove

Removes the gluster volume.

resetalloptions

Resets all the options set in the gluster volume.

resetoption

Resets a particular option in the gluster volume.

setoption

Sets a particular option in the gluster volume.

start

Starts the gluster volume.

startprofile

Start profiling the gluster volume.

stop

Stops the gluster volume.

stopprofile

Stop profiling the gluster volume.

stoprebalance

Stop rebalancing the gluster volume.

5.84.1. get GET

Get the gluster volume details.

For example, to get details of a gluster volume with identifier 123 in cluster 456, send a request like this:

GET /ovirt-engine/api/clusters/456/glustervolumes/123

This GET request will return the following output:

<gluster_volume id="123">
 <name>data</name>
 <link href="/ovirt-engine/api/clusters/456/glustervolumes/123/glusterbricks" rel="glusterbricks"/>
 <disperse_count>0</disperse_count>
 <options>
   <option>
     <name>storage.owner-gid</name>
     <value>36</value>
   </option>
   <option>
     <name>performance.io-cache</name>
     <value>off</value>
   </option>
   <option>
     <name>cluster.data-self-heal-algorithm</name>
     <value>full</value>
   </option>
 </options>
 <redundancy_count>0</redundancy_count>
 <replica_count>3</replica_count>
 <status>up</status>
 <stripe_count>0</stripe_count>
 <transport_types>
   <transport_type>tcp</transport_type>
 </transport_types>
 <volume_type>replicate</volume_type>
 </gluster_volume>
Table 251. Parameters summary
Name Type Direction Summary

volume

GlusterVolume

Out

Representation of the gluster volume.

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

POST /ovirt-engine/api/clusters/456/glustervolumes/123/getprofilestatistics
Table 252. Parameters summary
Name Type Direction Summary

details

GlusterVolumeProfileDetails

Out

Gluster volume profiling information returned from the action.

5.84.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 253. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the rebalance should be performed asynchronously.

fix_layout

Boolean

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.

force

Boolean

In

Indicates if the rebalance should be force started.
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.

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.84.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 254. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.84.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 255. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

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

With the following request body:

<action>
 <option name="option1"/>
</action>
Table 256. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

force

Boolean

In

option

Option

In

Option to reset.

5.84.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 257. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

option

Option

In

Option to set.

5.84.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 258. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

Indicates if the volume should be force started.
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.84.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 259. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

5.84.10. stop POST

Stops the gluster volume.

Stopping a volume will make its data inaccessible.

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 260. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

5.84.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 261. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

5.84.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 262. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

5.85. GlusterVolumes

This service manages a collection of gluster volumes available in a cluster.

Table 263. Methods summary
Name Summary

add

Creates a new gluster volume.

list

Lists all gluster volumes in the cluster.

5.85.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>
      <brick_dir>/exp1</brick_dir>
    </brick>
  <bricks>
</gluster_volume>
Table 264. Parameters summary
Name Type Direction Summary

volume

GlusterVolume

In/Out

The gluster volume definition from which to create the volume is passed as input and the newly created volume is returned.

5.85.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 265. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

max

Integer

In

Sets the maximum number of volumes to return.

search

String

In

A query string used to restrict the returned volumes.

volumes

GlusterVolume[]

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

max

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

5.86. Group

Table 266. Methods summary
Name Summary

get

remove

5.86.1. get GET

Table 267. Parameters summary
Name Type Direction Summary

get

Group

Out

5.86.2. remove DELETE

Table 268. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.87. Groups

Table 269. Methods summary
Name Summary

add

Add group from a directory service.

list

5.87.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 270. Parameters summary
Name Type Direction Summary

group

Group

In/Out

5.87.2. list GET

Table 271. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

groups

Group[]

Out

max

Integer

In

Sets the maximum number of groups to return.

search

String

In

A query string used to restrict the returned groups.
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.

max

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

5.88. Host

A service to manage a host.

Table 272. Methods summary
Name Summary

activate

Activate the host for use, such as running virtual machines.

approve

Approve a pre-installed Hypervisor host for usage in the virtualization environment.

commitnetconfig

Marks the network configuration as good and persists it inside the host.

deactivate

Deactivate the host to perform maintenance tasks.

enrollcertificate

Enroll certificate of the host.

fence

Controls host’s power management device.

forceselectspm

Manually set a host as the storage pool manager (SPM).

get

Get the host details.

install

Install VDSM and related software on the host.

iscsidiscover

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.

setupnetworks

This method is used to change the configuration of the network interfaces of a host.

unregisteredstoragedomainsdiscover

update

Update the host properties.

upgrade

Upgrade VDSM and selected software on the host.

upgradecheck

Check if there are upgrades available for the host.

5.88.1. activate POST

Activate the host for use, such as running virtual machines.

Table 273. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

5.88.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 274. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the approval should be performed asynchronously.

cluster

Cluster

In

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

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 275. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

5.88.4. deactivate POST

Deactivate the host to perform maintenance tasks.

Table 276. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

reason

String

In

stop_gluster_service

Boolean

In

Indicates if the gluster service should be stopped as part of deactivating the host.
stop_gluster_service

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.88.5. enrollcertificate POST

Enroll certificate of the host. Useful in case you get a warning that it is about to, or already expired.

Table 277. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the enrollment should be performed asynchronously.

5.88.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 278. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the fencing should be performed asynchronously.

fence_type

String

In

power_management

PowerManagement

Out

5.88.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 279. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

5.88.8. get GET

Get the host details.

Table 280. Parameters summary
Name Type Direction Summary

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

host

Host

Out

5.88.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 281. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the installation should be performed asynchronously.

deploy_hosted_engine

Boolean

In

When set to true it means this host should deploy also hosted engine components.

host

Host

In

This override_iptables property is used to indicate if the firewall configuration should be replaced by the default one.

image

String

In

When installing an oVirt node a image ISO file is needed.

root_password

String

In

The password of of the root user, used to connect to the host via SSH.

ssh

Ssh

In

The SSH details used to connect to the host.

undeploy_hosted_engine

Boolean

In

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

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.88.10. iscsidiscover POST

Discover iSCSI targets on the host, using the initiator details.

Table 282. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the discovery should be performed asynchronously.

iscsi

IscsiDetails

In

The target iSCSI device.

iscsi_targets

String[]

Out

The iSCSI targets.

5.88.11. iscsilogin POST

Login to iSCSI targets on the host, using the target details.

Table 283. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the login should be performed asynchronously.

iscsi

IscsiDetails

In

The target iSCSI device.

5.88.12. refresh POST

Refresh the host devices and capabilities.

Table 284. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the refresh should be performed asynchronously.

5.88.13. remove DELETE

Remove the host from the system.

#!/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 285. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.88.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>
            <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>
      <dns_resolver_configuration>
        <name_servers>
          <name_server>1.1.1.1</name_server>
          <name_server>2.2.2.2</name_server>
        </name_servers>
      </dns_resolver_configuration>
    </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:

# Find the service that manages the collection of hosts:
hosts_service = connection.system_service().hosts_service()

# Find the host:
host = hosts_service.list(search='name=myhost')[0]

# Find the service that manages the host:
host_service = hosts_service.host_service(host.id)

# Configure the network adding a bond with two slaves and attaching it to a
# network with an static IP address:
host_service.setup_networks(
    modified_bonds=[
        types.HostNic(
            name='bond0',
            bonding=types.Bonding(
                options=[
                    types.Option(
                        name='mode',
                        value='4',
                    ),
                    types.Option(
                        name='miimon',
                        value='100',
                    ),
                ],
                slaves=[
                    types.HostNic(
                        name='eth1',
                    ),
                    types.HostNic(
                        name='eth2',
                    ),
                ],
            ),
        ),
    ],
    modified_network_attachments=[
        types.NetworkAttachment(
            network=types.Network(
                name='myvlan',
            ),
            host_nic=types.HostNic(
                name='bond0',
            ),
            ip_address_assignments=[
                types.IpAddressAssignment(
                    assignment_method=types.BootProtocol.STATIC,
                    ip=types.Ip(
                        address='192.168.122.10',
                        netmask='255.255.255.0',
                    ),
                ),
            ],
            dns_resolver_configuration=types.DnsResolverConfiguration(
                name_servers=[
                    '1.1.1.1',
                    '2.2.2.2',
                ],
            ),
        ),
    ],
)

# After modifying the network configuration it is very important to make it
# persistent:
host_service.commit_net_config()
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 286. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

check_connectivity

Boolean

In

connectivity_timeout

Integer

In

modified_bonds

HostNic[]

In

modified_labels

NetworkLabel[]

In

modified_network_attachments

NetworkAttachment[]

In

removed_bonds

HostNic[]

In

removed_labels

NetworkLabel[]

In

removed_network_attachments

NetworkAttachment[]

In

synchronized_network_attachments

NetworkAttachment[]

In

5.88.15. unregisteredstoragedomainsdiscover POST

Table 287. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the discovery should be performed asynchronously.

iscsi

IscsiDetails

In

storage_domains

StorageDomain[]

Out

5.88.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 288. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

host

Host

In/Out

5.88.17. upgrade POST

Upgrade VDSM and selected software on the host.

Table 289. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the upgrade should be performed asynchronously.

5.88.18. upgradecheck POST

Check if there are upgrades available for the host. If there are upgrades available an icon will be displayed next to host status icon in the webadmin. Audit log messages are also added to indicate the availability of upgrades. The upgrade can be started from the webadmin or by using the upgrade host action.

5.89. HostDevice

A service to access a particular device of a host.

Table 290. Methods summary
Name Summary

get

Retrieve information about a particular host’s device.

5.89.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 291. Parameters summary
Name Type Direction Summary

device

HostDevice

Out

5.90. HostDevices

A service to access host devices.

Table 292. Methods summary
Name Summary

list

List the devices of a host.

5.90.1. list GET

List the devices of a host.

Table 293. Parameters summary
Name Type Direction Summary

devices

HostDevice[]

Out

max

Integer

In

Sets the maximum number of devices to return.
max

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

5.91. HostHook

Table 294. Methods summary
Name Summary

get

5.91.1. get GET

Table 295. Parameters summary
Name Type Direction Summary

hook

Hook

Out

5.92. HostHooks

Table 296. Methods summary
Name Summary

list

5.92.1. list GET

Table 297. Parameters summary
Name Type Direction Summary

hooks

Hook[]

Out

max

Integer

In

Sets the maximum number of hooks to return.
max

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

5.93. HostNic

A service to manage a network interface of a host.

Table 298. Methods summary
Name Summary

get

updatevirtualfunctionsconfiguration

The action updates virtual function configuration in case the current resource represents an SR-IOV enabled NIC.

5.93.1. get GET

Table 299. Parameters summary
Name Type Direction Summary

nic

HostNic

Out

5.93.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 300. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

In

5.94. HostNics

A service to manage the network interfaces of a host.

Table 301. Methods summary
Name Summary

list

5.94.1. list GET

Table 302. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of NICs to return.

nics

HostNic[]

Out
max

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

5.95. HostNumaNode

Table 303. Methods summary
Name Summary

get

5.95.1. get GET

Table 304. Parameters summary
Name Type Direction Summary

node

NumaNode

Out

5.96. HostNumaNodes

Table 305. Methods summary
Name Summary

list

5.96.1. list GET

Table 306. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of nodes to return.

nodes

NumaNode[]

Out
max

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

5.97. HostStorage

A service to manage host storages.

Table 307. Methods summary
Name Summary

list

Get list of storages.

5.97.1. list GET

Get list of storages.

GET /ovirt-engine/api/hosts/123/storage

The XML response you get will be like this one:

<host_storages>
  <host_storage id="123">
    ...
  </host_storage>
  ...
</host_storages>
Table 308. Parameters summary
Name Type Direction Summary

report_status

Boolean

In

Indicates if the status of the LUNs in the storage should be checked.

storages

HostStorage[]

Out

Retrieved list of storages.
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>
      <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.98. Hosts

A service that manages hosts.

Table 309. Methods summary
Name Summary

add

Creates a new host.

list

Get a list of all available hosts.

5.98.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>
The root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent requests.

To add a hosted engine host, use the optional deploy_hosted_engine parameter:

POST /ovirt-engine/api/hosts?deploy_hosted_engine=true
Table 310. Parameters summary
Name Type Direction Summary

deploy_hosted_engine

Boolean

In

When set to true it means this host should deploy also hosted engine components.

host

Host

In/Out

The host definition from which to create the new host is passed as parameter, and the newly created host is returned.

undeploy_hosted_engine

Boolean

In

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

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.98.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>
  <host href="/ovirt-engine/api/hosts/456" id="456">
    ...
  </host>
  ...
</host>
Table 311. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

filter

Boolean

In

Indicates if the results should be filtered according to the permissions of the user.

hosts

Host[]

Out

max

Integer

In

Sets the maximum number of hosts to return.

search

String

In

A query string used to restrict the returned hosts.
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.

max

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

5.99. Icon

A service to manage an icon (read-only).

Table 312. Methods summary
Name Summary

get

Get an icon.

5.99.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 313. Parameters summary
Name Type Direction Summary

icon

Icon

Out

Retrieved icon.

5.100. Icons

A service to manage icons.

Table 314. Methods summary
Name Summary

list

Get a list of icons.

5.100.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>
  <icon id="123">
    <data>...</data>
    <media_type>image/png</media_type>
  </icon>
  ...
</icons>
Table 315. Parameters summary
Name Type Direction Summary

icons

Icon[]

Out

Retrieved list of icons.

max

Integer

In

Sets the maximum number of icons to return.
max

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

5.101. Image

Table 316. Methods summary
Name Summary

get

import

5.101.1. get GET

Table 317. Parameters summary
Name Type Direction Summary

image

Image

Out

5.101.2. import POST

Table 318. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the import should be performed asynchronously.

cluster

Cluster

In

Cluster where the image should be imported.

disk

Disk

In

The disk which should be imported.

import_as_template

Boolean

In

Specify if template should be created from the imported disk.

storage_domain

StorageDomain

In

Storage domain where disk should be imported.

template

Template

In

Name of the template, which should be created.
cluster

Cluster where the image should be imported. Has effect only in case import_as_template parameter is set to true.

template

Name of the template, which should be created. Has effect only in case import_as_template parameter is set to true.

5.102. ImageTransfer

This service provides a mechanism to control an image transfer. The client will have to create a transfer by using add of the 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(
   types.ImageTransfer(
      image=types.Image(
         id='52cb593f-837c-4633-a444-35a0a0383706'
      )
   )
)

If the user wishes to download a disk rather than upload, he/she should specify download as the direction attribute of the transfer. This will grant a read permission from the image, instead of a write permission.

E.g:

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
   types.ImageTransfer(
      image=types.Image(
         id='52cb593f-837c-4633-a444-35a0a0383706'
      ),
      direction=types.ImageTransferDirection.DOWNLOAD
   )
)

Transfers have phases, which govern the flow of the upload/download. A client implementing such a flow should poll/check the transfer’s phase and act accordingly. All the possible phases can be found in ImageTransferPhase.

After adding a new transfer, its phase will be initializing. The client will have to poll on the transfer’s phase until it changes. When the phase becomes transferring, the session is ready to start the transfer.

For example:

transfer_service = transfers_service.image_transfer_service(transfer.id)
while transfer.phase == types.ImageTransferPhase.INITIALIZING:
   time.sleep(3)
   transfer = transfer_service.get()

At that stage, if the transfer’s phase is paused_system, then the session was not successfully established. One possible reason for that is that the ovirt-imageio-daemon is not running in the host that was selected for transfer. The transfer can be resumed by calling resume of the service that manages it.

If the session was successfully established - the returned transfer entity will contain the proxy_url and signed_ticket attributes, which the client needs to use in order to transfer the required data. The client can choose whatever technique and tool for sending the HTTPS request with the image’s data.

  • proxy_url is the address of a proxy server to the image, to do I/O to.

  • signed_ticket is the content that needs to be added to the Authentication header in the HTTPS request, in order to perform a trusted communication.

For example, Python’s HTTPSConnection can be used in order to perform a transfer, so an transfer_headers dict is set for the upcoming transfer:

transfer_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.urlparse(transfer.proxy_url)

# Create a new instance of the connection.
proxy_connection = HTTPSConnection(
   url.hostname,
   url.port,
   context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)
)

For upload, 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()
      transfer_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=transfer_headers
      )
      r = proxy_connection.getresponse()
      print r.status, r.reason, "Completed", "{:.0%}".format(pos/ float(size))
      pos += chunk_size

Similarly, for a download transfer, a Range header must be sent, making the download process more easily managed by downloading the disk in chunks.

E.g., the client will again iterate on chunks of the disk image, but this time he/she will download it to a local file, rather than uploading its own file to the image:

output_file = "/home/user/downloaded_image"
MiB_per_request = 32
chunk_size = 1024*1024*MiB_per_request
total = disk_size

with open(output_file, "wb") as disk:
   pos = 0
   while pos < total:
      transfer_service.extend()
      transfer_headers['Range'] = "bytes=%d-%d" %  (pos, min(total, pos + chunk_size) - 1)
      proxy_connection.request('GET', proxy_url.path, headers=transfer_headers)
      r = proxy_connection.getresponse()
      disk.write(r.read())
      print "Completed", "{:.0%}".format(pos/ float(total))
      pos += chunk_size

When finishing the transfer, the user should call finalize. This will make the final adjustments and verifications for finishing the transfer process.

For example:

transfer_service.finalize()

In case of an error, the transfer’s phase will be changed to finished_failure, and the disk’s status will be changed to Illegal. Otherwise it will be changed to finished_success, and the disk will be ready to be used. In both cases, the transfer entity will be removed shortly after.

Table 319. Methods summary
Name Summary

extend

Extend the image transfer session.

finalize

After finishing to transfer the data, finalize the transfer.

get

Get the image transfer entity.

pause

Pause the image transfer session.

resume

Resume the image transfer session.

5.102.1. extend POST

Extend the image transfer session.

5.102.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.102.3. get GET

Get the image transfer entity.

Table 320. Parameters summary
Name Type Direction Summary

image_transfer

ImageTransfer

Out

5.102.4. pause POST

Pause the image transfer session.

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

while transfer.phase == types.ImageTransferPhase.RESUMING:
   time.sleep(1)
   transfer = transfer_service.get()

5.103. ImageTransfers

This service manages image transfers, for performing Image I/O API in oVirt. Please refer to image transfer for further documentation.

Table 321. Methods summary
Name Summary

add

Add a new image transfer.

list

Retrieves the list of image transfers that are currently being performed.

5.103.1. add POST

Add a new image transfer. An image needs to be specified in order to make a new transfer.

Table 322. Parameters summary
Name Type Direction Summary

image_transfer

ImageTransfer

In/Out

5.103.2. list GET

Retrieves the list of image transfers that are currently being performed.

Table 323. Parameters summary
Name Type Direction Summary

image_transfer

ImageTransfer[]

Out

5.104. Images

Table 324. Methods summary
Name Summary

list

5.104.1. list GET

Table 325. Parameters summary
Name Type Direction Summary

images

Image[]

Out

max

Integer

In

Sets the maximum number of images to return.
max

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

5.105. InstanceType

Table 326. Methods summary
Name Summary

get

Get a specific instance type and it’s attributes.

remove

Removes a specific instance type from the system.

update

Update a specific instance type and it’s attributes.

5.105.1. get GET

Get a specific instance type and it’s attributes.

GET /ovirt-engine/api/instancetypes/123
Table 327. Parameters summary
Name Type Direction Summary

instance_type

InstanceType

Out

5.105.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 328. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.105.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>
      <threads>1</threads>
    </topology>
  </cpu>
</instance_type>
Table 329. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

instance_type

InstanceType

In/Out

5.106. InstanceTypeGraphicsConsole

Table 330. Methods summary
Name Summary

get

Gets graphics console configuration of the instance type.

remove

Remove the graphics console from the instance type.

5.106.1. get GET

Gets graphics console configuration of the instance type.

Table 331. Parameters summary
Name Type Direction Summary

console

GraphicsConsole

Out

The information about the graphics console of the instance type.

5.106.2. remove DELETE

Remove the graphics console from the instance type.

Table 332. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.107. InstanceTypeGraphicsConsoles

Table 333. Methods summary
Name Summary

add

Add new graphics console to the instance type.

list

Lists all the configured graphics consoles of the instance type.

5.107.1. add POST

Add new graphics console to the instance type.

Table 334. Parameters summary
Name Type Direction Summary

console

GraphicsConsole

In/Out

5.107.2. list GET

Lists all the configured graphics consoles of the instance type.

Table 335. Parameters summary
Name Type Direction Summary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the instance type.

max

Integer

In

Sets the maximum number of consoles to return.
max

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

5.108. InstanceTypeNic

Table 336. Methods summary
Name Summary

get

Gets network interface configuration of the instance type.

remove

Remove the network interface from the instance type.

update

Updates the network interface configuration of the instance type.

5.108.1. get GET

Gets network interface configuration of the instance type.

Table 337. Parameters summary
Name Type Direction Summary

nic

Nic

Out

5.108.2. remove DELETE

Remove the network interface from the instance type.

Table 338. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.108.3. update PUT

Updates the network interface configuration of the instance type.

Table 339. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

5.109. InstanceTypeNics

Table 340. Methods summary
Name Summary

add

Add new network interface to the instance type.

list

Lists all the configured network interface of the instance type.

5.109.1. add POST

Add new network interface to the instance type.

Table 341. Parameters summary
Name Type Direction Summary

nic

Nic

In/Out

5.109.2. list GET

Lists all the configured network interface of the instance type.

Table 342. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

search

String

In

A query string used to restrict the returned templates.
max

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

5.110. InstanceTypeWatchdog

Table 343. Methods summary
Name Summary

get

Gets watchdog configuration of the instance type.

remove

Remove a watchdog from the instance type.

update

Updates the watchdog configuration of the instance type.

5.110.1. get GET

Gets watchdog configuration of the instance type.

Table 344. Parameters summary
Name Type Direction Summary

watchdog

Watchdog

Out

5.110.2. remove DELETE

Remove a watchdog from the instance type.

Table 345. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.110.3. update PUT

Updates the watchdog configuration of the instance type.

Table 346. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

5.111. InstanceTypeWatchdogs

Table 347. Methods summary
Name Summary

add

Add new watchdog to the instance type.

list

Lists all the configured watchdogs of the instance type.

5.111.1. add POST

Add new watchdog to the instance type.

Table 348. Parameters summary
Name Type Direction Summary

watchdog

Watchdog

In/Out

5.111.2. list GET

Lists all the configured watchdogs of the instance type.

Table 349. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of watchdogs to return.

search

String

In

A query string used to restrict the returned templates.

watchdogs

Watchdog[]

Out
max

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

5.112. InstanceTypes

Table 350. Methods summary
Name Summary

add

Creates a new instance type.

list

Lists all existing instance types in the system.

5.112.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>
    <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 351. Parameters summary
Name Type Direction Summary

instance_type

InstanceType

In/Out

5.112.2. list GET

Lists all existing instance types in the system.

Table 352. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search performed using the search parameter should be performed taking case into account.

instance_type

InstanceType[]

Out

max

Integer

In

Sets the maximum number of instance types to return.

search

String

In

A query string used to restrict the returned templates.
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.

max

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

5.113. IscsiBond

Table 353. Methods summary
Name Summary

get

remove

Removes of an existing iSCSI bond.

update

Updates an iSCSI bond.

5.113.1. get GET

Table 354. Parameters summary
Name Type Direction Summary

bond

IscsiBond

Out

5.113.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 355. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.113.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 356. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bond

IscsiBond

In/Out

5.114. IscsiBonds

Table 357. Methods summary
Name Summary

add

Create a new iSCSI bond on a data center.

list

5.114.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 358. Parameters summary
Name Type Direction Summary

bond

IscsiBond

In/Out

5.114.2. list GET

Table 359. Parameters summary
Name Type Direction Summary

bonds

IscsiBond[]

Out

max

Integer

In

Sets the maximum number of bonds to return.
max

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

5.115. Job

A service to manage a job.

Table 360. Methods summary
Name Summary

clear

Set an external job execution to be cleared by the system.

end

Marks an external job execution as ended.

get

Retrieves a job.

5.115.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/>
Table 361. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

5.115.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 362. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

Indicates if the job should be forcibly terminated.

succeeded

Boolean

In

Indicates if the job should be marked as successfully finished or as failed.
succeeded

Indicates if the job should be marked as successfully finished or as failed.

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

5.115.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>
  <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 363. Parameters summary
Name Type Direction Summary

job

Job

Out

Retrieves the representation of the job.

5.116. Jobs

A service to manage jobs.

Table 364. Methods summary
Name Summary

add

Add an external job.

list

Retrieves the representation of the jobs.

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

<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 365. Parameters summary
Name Type Direction Summary

job

Job

In/Out

Job that will be added.

5.116.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 366. Parameters summary
Name Type Direction Summary

jobs

Job[]

Out

A representation of jobs.

max

Integer

In

Sets the maximum number of jobs to return.
max

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

5.117. KatelloErrata

A service to manage Katello errata. The information is retrieved from Katello.

Table 367. Methods summary
Name Summary

list

Retrieves the representation of the Katello errata.

5.117.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 368. Parameters summary
Name Type Direction Summary

errata

KatelloErratum[]

Out

A representation of Katello errata.

max

Integer

In

Sets the maximum number of errata to return.
max

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

5.118. KatelloErratum

A service to manage a Katello erratum.

Table 369. Methods summary
Name Summary

get

Retrieves a Katello erratum.

5.118.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>
      <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
    </package>
    ...
  </packages>
</katello_erratum>
Table 370. Parameters summary
Name Type Direction Summary

erratum

KatelloErratum

Out

Retrieves the representation of the Katello erratum.

5.119. MacPool

Table 371. Methods summary
Name Summary

get

remove

Removes a MAC address pool.

update

Updates a MAC address pool.

5.119.1. get GET

Table 372. Parameters summary
Name Type Direction Summary

pool

MacPool

Out

5.119.2. remove DELETE

Removes a MAC address pool.

For example, to remove the MAC address pool having id 123 send a request like this:

DELETE /ovirt-engine/api/macpools/123
Table 373. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.119.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 374. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

pool

MacPool

In/Out

5.120. MacPools

Table 375. Methods summary
Name Summary

add

Creates a new MAC address pool.

list

5.120.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 376. Parameters summary
Name Type Direction Summary

pool

MacPool

In/Out

5.120.2. list GET

Table 377. Parameters summary
Name Type Direction Summary

max

Integer

In

Sets the maximum number of pools to return.

pools

MacPool[]

Out
max

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

5.121. Measurable

5.122. Moveable

Table 378. Methods summary
Name Summary

move

5.122.1. move POST

Table 379. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the move should be performed asynchronously.

5.123. Network

A service managing a network

Table 380. Methods summary
Name Summary

get

Gets a logical network.

remove

Removes a logical network, or the association of a logical network to a data center.

update

Updates a logical network.

5.123.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 381. Parameters summary
Name Type Direction Summary

network

Network

Out

5.123.2. remove DELETE

Removes a logical network, or the association of a logical network to a data center.

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 382. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.123.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 383. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

network

Network

In/Out

5.124. NetworkAttachment

Table 384. Methods summary
Name Summary

get

remove

update

5.124.1. get GET

Table 385. Parameters summary
Name Type Direction Summary

attachment

NetworkAttachment

Out

5.124.2. remove DELETE

Table 386. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.124.3. update PUT

Table 387. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

attachment

NetworkAttachment

In/Out

5.125. NetworkAttachments

Table 388. Methods summary
Name Summary

add

list

5.125.1. add POST

Table 389. Parameters summary
Name Type Direction Summary

attachment

NetworkAttachment

In/Out

5.125.2. list GET

Table 390. Parameters summary
Name Type Direction Summary

attachments

NetworkAttachment[]

Out

max

Integer

In

Sets the maximum number of attachments to return.
max

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

5.126. 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 391. Methods summary
Name Summary

get

Retrieves a representation of the network filter.

5.126.1. get GET

Retrieves a representation of the network filter.

Table 392. Parameters summary
Name Type Direction Summary

network_filter

NetworkFilter

Out

5.127. NetworkFilterParameter

This service manages a parameter for a network filter.

Table 393. Methods summary
Name Summary

get

Retrieves a representation of the network filter parameter.

remove

Removes the filter parameter.

update

Updates the network filter parameter.

5.127.1. get GET

Retrieves a representation of the network filter parameter.

Table 394. Parameters summary
Name Type Direction Summary

parameter

NetworkFilterParameter

Out

The representation of the network filter parameter.

5.127.2. remove DELETE

Removes the filter parameter.

For example, to remove the filter parameter with id 123 on NIC 456 of virtual machine 789 send a request like this:

DELETE /ovirt-engine/api/vms/789/nics/456/networkfilterparameters/123

5.127.3. update PUT

Updates the network filter parameter.

For example, to update the network filter parameter having with with id 123 on NIC 456 of virtual machine 789 send a request like this:

PUT /ovirt-engine/api/vms/789/nics/456/networkfilterparameters/123

With a request body like this:

<network_filter_parameter>
  <name>updatedName</name>
  <value>updatedValue</value>
</network_filter_parameter>
Table 395. Parameters summary
Name Type Direction Summary

parameter

NetworkFilterParameter

In/Out

The network filter parameter that is being updated.

5.128. NetworkFilterParameters

This service manages a collection of parameters for network filters.

Table 396. Methods summary
Name Summary

add

Add a network filter parameter.

list

Retrieves the representations of the network filter parameters.

5.128.1. add POST

Add a network filter parameter.

For example, to add the parameter for the network filter on NIC 456 of virtual machine 789 send a request like this:

POST /ovirt-engine/api/vms/789/nics/456/networkfilterparameters

With a request body like this:

<network_filter_parameter>
  <name>IP</name>
  <value>10.0.1.2</value>
</network_filter_parameter>
Table 397. Parameters summary
Name Type Direction Summary

parameter

NetworkFilterParameter

In/Out

The network filter parameter that is being added.

5.128.2. list GET

Retrieves the representations of the network filter parameters.

Table 398. Parameters summary
Name Type Direction Summary

parameters

NetworkFilterParameter[]

Out

The list of the network filter parameters.

5.129. NetworkFilters

Represents a readonly network filters sub-collection.

The network filter enables to filter packets send to/from the VM’s nic according to defined rules. For more information please refer to NetworkFilter service documentation

Network filters are supported in different versions, starting from version 3.0.

A network filter is defined for each vnic profile.

A vnic profile is defined for a specific network.

A network can be assigned to several different clusters. In the future, each network will be defined in cluster level.

Currently, each network is being defined at data center level. Potential network filters for each network are determined by the network’s data center compatibility version V. V must be >= the network filter version in order to configure this network filter for a specific network. Please note, that if a network is assigned to cluster with a version supporting a network filter, the filter may not be available due to the data center version being smaller then the network filter’s version.

Example of listing all of the supported network filters for a specific cluster:

GET http://localhost:8080/ovirt-engine/api/clusters/{cluster:id}/networkfilters

Output:

<network_filters>
  <network_filter id="00000019-0019-0019-0019