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

3.1. Types

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

There are three relevant kinds of types:

Primitive types

Describe simple kinds of objects, like strings or integers.

Enumerated types

Describe lists of valid values like VmStatus or DiskFormat.

Structured types

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

3.2. Identified types

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

Attribute Type Description

id

String

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

href

String

The canonical location of the object as an absolute path.

name

String

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

description

String

A free-form user-supplied human readable description of the object.

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

3.3. Objects

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

3.4. Collections

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

3.5. Representations

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

3.5.1. XML representation

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

<vm id="123" href="/ovirt-engine/api/vms/123">
  <name>myvm</name>
  <description>My VM</description>
  <memory>1073741824</memory>
  ...
</vm>

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

<vms>
  <vm id="123" href="/ovirt-engine/api/vms/123">
    <name>yourvm</name>
    <description>Your VM</description>
    <memory>1073741824</memory>
    ...
  </vm>
  <vm id="456" href="/ovirt-engine/api/vms/456">
    <name>myname</name>
    <description>My description</description>
    <memory>2147483648</memory>
    ...
  </vm>
  ...
</vms>
In the XML representation of objects the id and href attributes are the only ones that are represented as XML attributes, the rest are represented as nested XML elements.

3.5.2. JSON representation

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

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

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

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

3.6. Services

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

There are two relevant kinds of services:

Services that manage a collection of objects

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

Services that manage a specific object

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

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

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

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

Method name HTTP method

add

POST

get

GET

list

GET

update

PUT

remove

DELETE

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

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

GET /ovirt-engine/api/vms

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

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

Each method has a set of parameters.

Parameters are classified into two categories:

Main parameter

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

Secondary parameters

The rest of the parameters.

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

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

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

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

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

HTTP/1.1 201 Created
Content-Type: application/xml

<vm href="/ovirt-engine/api/vms/123" id="123">
  <name>myvm</name>
  <description>My VM</description>
  ...
</vm>

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

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

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

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

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

<action>
  <use_cloud_init>true</use_cloud_init>
  <vm>
    <initialization>
      <nic_configurations>
        <nic_configuration>
          <name>eth0</name>
          <on_boot>true</on_boot>
          <boot_protocol>static</boot_protocol>
          <ip>
            <address>192.168.0.100</address>
            <netmask>255.255.255.0</netmask>
            <gateway>192.168.0.1</netmask>
          </ip>
        </nic_configuration>
      </nic_configurations>
      <dns_servers>192.168.0.1</dns_servers>
    </initialization>
  </vm>
</action>

3.7. Searching

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

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

3.7.1. Maximum results parameter

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

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

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

3.7.2. Case sensitivity

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

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

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

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

3.7.3. Search syntax

The search parameters use the same syntax as the oVirt query language:

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

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

Example search queries:

Collection Criteria Result

hosts

vms.status=up

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

vms

domain=example.com

Returns a list of all virtual machines running on the specified domain.

vms

users.name=mary

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

events

severity > normal sortby time

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

events

severity > normal sortby time desc

Returns a list of all events with severity higher than normal and sorted by the the value of their time attribute in descending order.

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

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

3.7.4. Wildcards

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

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

3.7.5. Pagination

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

GET /ovirt-engine/api/vms?search=page%201&max=10
The search parameter is URL-encoded, the actual value of the search parameter, before encoding, is page 1, so this is actually requesting the first page.

Increase the page value to retrieve the next page:

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

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

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

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

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

3.8. Following links

The API returns references to related objects as links. For example, when a virtual machine is retrieved it contains links to its disk attachments and network interface cards:

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <link rel="diskattachments" href="/ovirt-engine/api/vms/123/diskattachments"/>
  <link rel="nics" href="/ovirt-engine/api/vms/123/nics"/>
  ...
</vm>

The complete description of those linked objects can be retrieved by sending separate requests:

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

However, in some situations it is more convenient for the application using the API to retrieve the linked information in the same request. This is useful, for example, when the additional network round trips introduce an unacceptable overhead, or when the multiple requests complicate the code of the application in an unacceptable way. For those use cases the API provides a follow parameter that allows the application to retrieve the linked information using only one request.

The value of the follow parameter is a list of strings, separated by commas. Each of those strings is the path of the linked object. For example, to retrieve the disk attachments and the NICs in the example above the request should be like this:

GET /ovirt-engine/api/vms/123?follow=disk_attachments,nics

That will return an response like this:

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <disk_attachments>
    <disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
      <active>true</active>
      <bootable>true</bootable>
      <interface>virtio_scsi</interface>
      <pass_discard>false</pass_discard>
      <read_only>false</read_only>
      <uses_scsi_reservation>false</uses_scsi_reservation>
      <disk id="789" href="/ovirt-engine/api/disks/789"/>
    </disk_attachment>
    ...
  </disk_attacments>
  <nics>
    <nic id="234" href="/ovirt-engine/api/vms/123/nics/234">
      <name>eth0</name>
      <interface>virtio</interface>
      <linked>true</linked>
      <mac>
        <address>00:1a:4a:16:01:00</address>
      </mac>
      <plugged>true</plugged>
    </nic>
    ...
  </nics>
  ...
</vm>

The path to the linked object can be a single word, as in the previous example, or it can be a sequence of words, separated by dots, to request nested data. For example, the previous example used disk_attachments in order to retrieve the complete description of the disk attachments, but each disk attachment contains a link to the disk, which wasn’t followed. In order to also follow the links to the disks, the following request can be used:

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk

That will result in the following response:

<vm id="123" href="/ovirt-engine/api/vms/123">
  <disk_attachments>
    <disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
      <active>true</active>
      <bootable>true</bootable>
      <interface>virtio_scsi</interface>
      <pass_discard>false</pass_discard>
      <read_only>false</read_only>
      <uses_scsi_reservation>false</uses_scsi_reservation>
      <disk id="789" href="/ovirt-engine/api/disks/789">
        <name>mydisk</name>
        <description>My disk</description>
        <actual_size>0</actual_size>
        <format>raw</format>
        <sparse>true</sparse>
        <status>ok</status>
        <storage_type>image</storage_type>
        <total_size>0</total_size>
        ...
      </disk>
    </disk_attachment>
    ...
  </disk_attachments>
  ...
</vm>

The path can be made as deep as needed. For example, to also get the statistics of the disks:

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics

Multiple path elements and multiple paths can be combined. For example, to get the disk attachments and the network interface cards, both with their statistics:

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics,nics.statistics
Almost all the operations that retrieve objects support the follow parameter, but make sure to explicitly check the reference documentation, as some operations may not support it, or may provide advice on how to use it to get the best performance.
Using the follow parameter moves the overhead from the client side to the server side. When you request additional data, the server must fetch and merge it with the basic data. That consumes CPU and memory in the server side, and will in most cases require additional database queries. That may adversely affect the performance of the server, especially in large scale environments. Make sure to test your application in a realistic environment, and use the follow parameter only when justified.

3.9. Permissions

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

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

The response body will look like this:

<permissions>
  <permission id="456" href="/ovirt-engien/api/vms/123/permissions/456">
    <user id="789" href="/ovirt-engine/api/users/789"/>
    <role id="abc" href="/ovirt-engine/api/roles/abc"/>
    <vm id="123" href="/ovirt-engine/api/vms/123"/>
  </permission>
  ...
</permissions>

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

3.10. Handling errors

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

HTTP/1.1 400 Bad Request

And the following response body:

<fault>
  <reason>Incomplete parameters</reason>
  <detail>Vm [name] required for add</detail>
</fault>

4. Quick Start Examples

The examples in this section show you how to use the REST API to set up a basic oVirt environment and to create a virtual machine. In addition to the standard prerequisites, these examples require the following:

  • A networked and configured oVirt installation.

  • An ISO file containing the virtual machine operating system you want to install. This chapter uses CentOS 7 for the installation ISO example.

The API examples use curl to demonstrate API requests with a client application. You can use any application that sends HTTP requests.

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.

The curl examples use admin@internal for the user name, mypassword for the password, /etc/pki/ovirt-engine/ca.pem for the certificate location, and myengine.example.com for the host name. You must replace them with the correct values for your environment.

oVirt generates a unique identifier for the id attribute for each resource. Identifier codes in this example will differ from the identifier codes in your oVirt environment.

In many examples, some attributes of the results returned by the API have been omitted, for brevity. See, for example, the Cluster reference for a complete list of attributes.

4.1. Access API entry point

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

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

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

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

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

4.2. List data centers

oVirt creates a Default data center on installation. This example uses the Default data center as the basis for the virtual environment.

The following request retrieves a representation of the data centers:

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

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

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

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

4.4. 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 the Default cluster and is a member of the Default data center. This example uses the ovirtmgmt network to connect the virtual machines.

The following request retrieves the list of logical networks:

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

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

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

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

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

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

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

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

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>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains

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

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

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

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

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

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

4.12. Attach ISO image to virtual machine

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

ISO images must be available in the myisos ISO domain for the virtual machines to use. You can use ImageTransfers to create an image transfer and ImageTransfer to upload the ISO image.

Once the ISO image 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

The 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 the 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>

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

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

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

5. Requests

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

6. Services

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

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

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

follow

String

In

Indicates which inner links should be followed.

group

AffinityGroup

Out

The affinity group.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.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 removal should be performed asynchronously.

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

6.2. AffinityGroupHost

This service manages a single host to affinity group assignment.

Table 7. Methods summary
Name Summary

remove

Remove host from the affinity group.

6.2.1. remove DELETE

Remove host from the affinity group.

Table 8. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.3. AffinityGroupHostLabel

This service manages a single host label assigned to an affinity group.

Table 9. Methods summary
Name Summary

remove

Remove this label from the affinity group.

6.3.1. remove DELETE

Remove this label from the affinity group.

Table 10. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.4. AffinityGroupHostLabels

This service manages a collection of all host labels assigned to an affinity group.

Table 11. Methods summary
Name Summary

add

Adds a host label to the affinity group.

list

List all host labels assigned to this affinity group.

6.4.1. add POST

Adds a host label to the affinity group.

For example, to add the label 789 to the affinity group 456 of cluster 123, send a request like this:

POST /ovirt-engine/api/clusters/123/affinitygroups/456/hostlabels

With the following body:

<affinity_label id="789"/>
Table 12. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

The AffinityLabel object to add to the affinity group.

6.4.2. list GET

List all host labels assigned to this affinity group.

The order of the returned labels isn’t guaranteed.

Table 13. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

labels

AffinityLabel[]

Out

Host labels assigned to the affinity group.

max

Integer

In

Sets the maximum number of host labels to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.5. AffinityGroupHosts

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

Table 14. Methods summary
Name Summary

add

Adds a host to the affinity group.

list

List all hosts assigned to this affinity group.

6.5.1. add POST

Adds a host to the affinity group.

For example, to add the host 789 to the affinity group 456 of cluster 123, send a request like this:

POST /ovirt-engine/api/clusters/123/affinitygroups/456/hosts

With the following body:

<host id="789"/>
Table 15. Parameters summary
Name Type Direction Summary

host

Host

In/Out

The host to be added to the affinity group.

6.5.2. list GET

List all hosts assigned to this affinity group.

The order of the returned hosts isn’t guaranteed.

Table 16. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

hosts

Host[]

Out

The list of hosts assigned to this affinity group.

max

Integer

In

Sets the maximum number of hosts to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.6. AffinityGroupVm

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

Table 17. Methods summary
Name Summary

remove

Remove this virtual machine from the affinity group.

6.6.1. remove DELETE

Remove this virtual machine from the affinity group.

Table 18. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.7. AffinityGroupVmLabel

This service manages a single virtual machine label assigned to an affinity group.

Table 19. Methods summary
Name Summary

remove

Remove this label from the affinity group.

6.7.1. remove DELETE

Remove this label from the affinity group.

Table 20. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.8. AffinityGroupVmLabels

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

Table 21. Methods summary
Name Summary

add

Adds a virtual machine label to the affinity group.

list

List all virtual machine labels assigned to this affinity group.

6.8.1. add POST

Adds a virtual machine label to the affinity group.

For example, to add the label 789 to the affinity group 456 of cluster 123, send a request like this:

POST /ovirt-engine/api/clusters/123/affinitygroups/456/vmlabels

With the following body:

<affinity_label id="789"/>
Table 22. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

The AffinityLabel object to add to the affinity group.

6.8.2. list GET

List all virtual machine labels assigned to this affinity group.

The order of the returned labels isn’t guaranteed.

Table 23. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

labels

AffinityLabel[]

Out

Virtual machine labels assigned to the affinity group.

max

Integer

In

Sets the maximum number of virtual machine labels to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.9. AffinityGroupVms

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

Table 24. Methods summary
Name Summary

add

Adds a virtual machine to the affinity group.

list

List all virtual machines assigned to this affinity group.

6.9.1. add POST

Adds a virtual machine to the affinity group.

For example, to add the virtual machine 789 to the affinity group 456 of cluster 123, send a request like this:

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

With the following body:

<vm id="789"/>
Table 25. Parameters summary
Name Type Direction Summary

vm

Vm

In/Out

6.9.2. list GET

List all virtual machines assigned to this affinity group.

The order of the returned virtual machines isn’t guaranteed.

Table 26. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of virtual machines to return.

vms

Vm[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.10. AffinityGroups

The affinity groups service manages virtual machine relationships and dependencies.

Table 27. Methods summary
Name Summary

add

Create a new affinity group.

list

List existing affinity groups.

6.10.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>
  <hosts_rule>
    <enforcing>true</enforcing>
    <positive>true</positive>
  </hosts_rule>
  <vms_rule>
    <enabled>false</enabled>
  </vms_rule>
</affinity_group>
Table 28. Parameters summary
Name Type Direction Summary

group

AffinityGroup

In/Out

The affinity group object to create.

6.10.2. list GET

List existing affinity groups.

The order of the affinity groups results isn’t guaranteed.

Table 29. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

groups

AffinityGroup[]

Out

The list of existing affinity groups.

max

Integer

In

Sets the maximum number of affinity groups to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.11. AffinityLabel

The details of a single affinity label.

Table 30. Methods summary
Name Summary

get

Retrieves the details of a label.

remove

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

update

Updates a label.

6.11.1. get GET

Retrieves the details of a label.

Table 31. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

label

AffinityLabel

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.11.2. remove DELETE

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

6.11.3. update PUT

Updates a label. This call will update all metadata, such as the name or description.

Table 32. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

6.12. AffinityLabelHost

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

Table 33. Methods summary
Name Summary

get

Retrieves details about a host that has this label assigned.

remove

Remove a label from a host.

6.12.1. get GET

Retrieves details about a host that has this label assigned.

Table 34. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

host

Host

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.12.2. remove DELETE

Remove a label from a host.

6.13. AffinityLabelHosts

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

Table 35. Methods summary
Name Summary

add

Add a label to a host.

list

List all hosts with the label.

6.13.1. add POST

Add a label to a host.

Table 36. Parameters summary
Name Type Direction Summary

host

Host

In/Out

6.13.2. list GET

List all hosts with the label.

The order of the returned hosts isn’t guaranteed.

Table 37. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

hosts

Host[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.14. AffinityLabelVm

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

Table 38. Methods summary
Name Summary

get

Retrieves details about a vm that has this label assigned.

remove

Remove a label from a vm.

6.14.1. get GET

Retrieves details about a vm that has this label assigned.

Table 39. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

vm

Vm

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.14.2. remove DELETE

Remove a label from a vm.

6.15. AffinityLabelVms

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

Table 40. Methods summary
Name Summary

add

Add a label to a vm.

list

List all virtual machines with the label.

6.15.1. add POST

Add a label to a vm.

Table 41. Parameters summary
Name Type Direction Summary

vm

Vm

In/Out

6.15.2. list GET

List all virtual machines with the label.

The order of the returned virtual machines isn’t guaranteed.

Table 42. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

vms

Vm[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.16. AffinityLabels

Manages the affinity labels available in the system.

Table 43. Methods summary
Name Summary

add

Creates a new label.

list

Lists all labels present in the system.

6.16.1. add POST

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

Table 44. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

6.16.2. list GET

Lists all labels present in the system.

The order of the returned labels isn’t guaranteed.

Table 45. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

labels

AffinityLabel[]

Out

max

Integer

In

Sets the maximum number of labels to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

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

6.18. AssignedAffinityLabel

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

Table 46. Methods summary
Name Summary

get

Retrieves details about the attached label.

remove

Removes the label from an entity.

6.18.1. get GET

Retrieves details about the attached label.

Table 47. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

label

AffinityLabel

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.18.2. remove DELETE

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

6.19. AssignedAffinityLabels

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

Table 48. Methods summary
Name Summary

add

Attaches a label to an entity.

list

Lists all labels that are attached to an entity.

6.19.1. add POST

Attaches a label to an entity.

Table 49. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

6.19.2. list GET

Lists all labels that are attached to an entity.

The order of the returned entities isn’t guaranteed.

Table 50. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

label

AffinityLabel[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.20. AssignedCpuProfile

Table 51. Methods summary
Name Summary

get

remove

6.20.1. get GET

Table 52. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

profile

CpuProfile

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.20.2. remove DELETE

Table 53. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.21. AssignedCpuProfiles

Table 54. Methods summary
Name Summary

add

Add a new cpu profile for the cluster.

list

List the CPU profiles assigned to the cluster.

6.21.1. add POST

Add a new cpu profile for the cluster.

Table 55. Parameters summary
Name Type Direction Summary

profile

CpuProfile

In/Out

6.21.2. list GET

List the CPU profiles assigned to the cluster.

The order of the returned CPU profiles isn’t guaranteed.

Table 56. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profiles

CpuProfile[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.22. AssignedDiskProfile

Table 57. Methods summary
Name Summary

get

remove

6.22.1. get GET

Table 58. Parameters summary
Name Type Direction Summary

disk_profile

DiskProfile

Out

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.22.2. remove DELETE

Table 59. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.23. AssignedDiskProfiles

Table 60. Methods summary
Name Summary

add

Add a new disk profile for the storage domain.

list

Returns the list of disk profiles assigned to the storage domain.

6.23.1. add POST

Add a new disk profile for the storage domain.

Table 61. Parameters summary
Name Type Direction Summary

profile

DiskProfile

In/Out

6.23.2. list GET

Returns the list of disk profiles assigned to the storage domain.

The order of the returned disk profiles isn’t guaranteed.

Table 62. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profiles

DiskProfile[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.24. AssignedPermissions

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

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

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

permission

Permission

In/Out

The permission.

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

The order of the returned permissions isn’t guaranteed.

Table 65. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

permissions

Permission[]

Out

The list of permissions.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.25. AssignedRoles

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

Table 66. Methods summary
Name Summary

list

Returns the roles assigned to the permission.

6.25.1. list GET

Returns the roles assigned to the permission.

The order of the returned roles isn’t guaranteed.

Table 67. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.26. AssignedTag

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

Table 68. Methods summary
Name Summary

get

Gets the information about the assigned tag.

remove

Unassign tag from specific entity in the system.

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

follow

String

In

Indicates which inner links should be followed.

tag

Tag

Out

The assigned tag.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.27. AssignedTags

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

Table 71. Methods summary
Name Summary

add

Assign tag to specific entity in the system.

list

List all tags assigned to the specific entity.

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

tag

Tag

In/Out

The assigned tag.

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

The order of the returned tags isn’t guaranteed.

Table 73. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

The list of assigned tags.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.28. AssignedVnicProfile

Table 74. Methods summary
Name Summary

get

remove

6.28.1. get GET

Table 75. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

profile

VnicProfile

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.28.2. remove DELETE

Table 76. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.29. AssignedVnicProfiles

Table 77. Methods summary
Name Summary

add

Add a new virtual network interface card profile for the network.

list

Returns the list of VNIC profiles assifned to the network.

6.29.1. add POST

Add a new virtual network interface card profile for the network.

Table 78. Parameters summary
Name Type Direction Summary

profile

VnicProfile

In/Out

6.29.2. list GET

Returns the list of VNIC profiles assifned to the network.

The order of the returned VNIC profiles isn’t guaranteed.

Table 79. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.30. AttachedStorageDomain

Table 80. Methods summary
Name Summary

activate

This operation activates an attached storage domain.

deactivate

This operation deactivates an attached storage domain.

get

remove

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

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.30.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. For example, to deactivate storage domain 456, send the following request:

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

With a request body like this:

<action/>

If the force parameter is true then the operation will succeed, even if the OVF update which takes place before the deactivation of the storage domain failed. If the force parameter is false and the OVF update failed, the deactivation of the storage domain will also fail.

Table 82. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

force

Boolean

In

Indicates if the operation should succeed and the storage domain should be moved to a deactivated state, even if the OVF update for the storage domain failed.

force

Indicates if the operation should succeed and the storage domain should be moved to a deactivated state, even if the OVF update for the storage domain failed. For example, to deactivate storage domain 456 using force flag, send the following request:

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

With a request body like this:

<action>
  <force>true</force>
<action>

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

6.30.3. get GET

Table 83. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

storage_domain

StorageDomain

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.30.4. remove DELETE

Table 84. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

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

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

storage_domain

StorageDomain

In

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

6.31.3. get GET

Retrieves the description of the disk.

Table 88. Parameters summary
Name Type Direction Summary

disk

Disk

Out

The description of the disk.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

6.31.5. register POST

Registers an unregistered disk.

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

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

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

disk

Disk

In/Out

The update to apply to the disk.

6.32. AttachedStorageDomainDisks

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

Table 91. Methods summary
Name Summary

add

Adds or registers a disk.

list

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

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

6.32.2. list GET

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

Table 93. Parameters summary
Name Type Direction Summary

disks

Disk[]

Out

List of retrieved disks.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of disks to return.

disks

List of retrieved disks.

The order of the returned disks isn’t guaranteed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.33. AttachedStorageDomains

Manages the storage domains attached to a data center.

Table 94. Methods summary
Name Summary

add

Attaches an existing storage domain to the data center.

list

Returns the list of storage domains attached to the data center.

6.33.1. add POST

Attaches an existing storage domain to the data center.

Table 95. Parameters summary
Name Type Direction Summary

storage_domain

StorageDomain

In/Out

The storage domain to attach to the data center.

6.33.2. list GET

Returns the list of storage domains attached to the data center.

The order of the returned storage domains isn’t guaranteed.

Table 96. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of storage domains to return.

storage_domains

StorageDomain[]

Out

A list of storage domains that are attached to the data center.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.34. Balance

Table 97. Methods summary
Name Summary

get

remove

6.34.1. get GET

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

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.34.2. remove DELETE

Table 99. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.35. Balances

Table 100. Methods summary
Name Summary

add

Add a balance module to a specified user defined scheduling policy.

list

Returns the list of balance modules used by the scheduling policy.

6.35.1. add POST

Add a balance module to a specified user defined scheduling policy.

Table 101. Parameters summary
Name Type Direction Summary

balance

Balance

In/Out

6.35.2. list GET

Returns the list of balance modules used by the scheduling policy.

The order of the returned balance modules isn’t guaranteed.

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

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of balances to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.36. Bookmark

A service to manage a bookmark.

Table 103. Methods summary
Name Summary

get

Get a bookmark.

remove

Remove a bookmark.

update

Update a bookmark.

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

bookmark

Bookmark

Out

The requested bookmark.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.36.2. remove DELETE

Remove a bookmark.

An example for removing a bookmark:

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the update should be performed asynchronously.

bookmark

Bookmark

In/Out

The updated bookmark.

6.37. Bookmarks

A service to manage bookmarks.

Table 107. Methods summary
Name Summary

add

Adding a new bookmark.

list

Listing all the available bookmarks.

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

bookmark

Bookmark

In/Out

The added bookmark.

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

The order of the returned bookmarks isn’t guaranteed.

Table 109. Parameters summary
Name Type Direction Summary

bookmarks

Bookmark[]

Out

The list of available bookmarks.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of bookmarks to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.38. Cluster

A service to manage a specific cluster.

Table 110. Methods summary
Name Summary

get

Gets information about the cluster.

refreshglusterhealstatus

Refresh the Gluster heal info for all volumes in cluster.

remove

Removes the cluster from the system.

resetemulatedmachine

syncallnetworks

Synchronizes all networks on the cluster.

update

Updates information about the cluster.

upgrade

Start or finish upgrade process for the cluster based on the action value.

6.38.1. get GET

Gets 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 Nehalem 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>
  <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>
  <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 111. 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.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.38.2. refreshglusterhealstatus POST

Refresh the Gluster heal info for all volumes in cluster.

For example, Cluster 123, send a request like this:

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

6.38.3. remove DELETE

Removes the cluster from the system.

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.38.4. resetemulatedmachine POST

Table 113. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

6.38.5. syncallnetworks POST

Synchronizes all networks on the cluster.

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

With a request body like this:

<action/>
Table 114. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.38.6. update PUT

Updates information about the cluster.

Only the specified fields are updated; others remain unchanged.

For example, to update the cluster’s CPU:

PUT /ovirt-engine/api/clusters/123

With a request body like this:

<cluster>
  <cpu>
    <type>Intel Haswell-noTSX Family</type>
  </cpu>
</cluster>
Table 115. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

cluster

Cluster

In/Out

6.38.7. upgrade POST

Start or finish upgrade process for the cluster based on the action value. This action marks the cluster for upgrade or clears the upgrade running flag on the cluster based on the action value which takes values of start or stop.

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

With a request body like this to mark the cluster for upgrade:

<action>
    <upgrade_action>
        start
    </upgrade_action>
</action>
Table 116. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

upgrade_action

ClusterUpgradeAction

In

The action to be performed.

6.39. ClusterEnabledFeature

Represents a feature enabled for the cluster.

Table 117. Methods summary
Name Summary

get

Provides the information about the cluster feature enabled.

remove

Disables a cluster feature.

6.39.1. get GET

Provides the information about the cluster feature enabled.

For example, to find details of the enabled feature 456 for cluster 123, send a request like this:

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

That will return a ClusterFeature object containing the name:

<cluster_feature id="456">
  <name>libgfapi_supported</name>
</cluster_feature>
Table 118. Parameters summary
Name Type Direction Summary

feature

ClusterFeature

Out

Retrieved cluster feature that’s enabled.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.39.2. remove DELETE

Disables a cluster feature.

For example, to disable the feature 456 of cluster 123 send a request like this:

DELETE /ovirt-engine/api/clusters/123/enabledfeatures/456

6.40. ClusterEnabledFeatures

Provides information about the additional features that are enabled for this cluster. The features that are enabled are the available features for the cluster level

Table 119. Methods summary
Name Summary

add

Enable an additional feature for a cluster.

list

Lists the additional features enabled for the cluster.

6.40.1. add POST

Enable an additional feature for a cluster.

For example, to enable a feature 456 on cluster 123, send a request like this:

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

The request body should look like this:

<cluster_feature id="456"/>
Table 120. Parameters summary
Name Type Direction Summary

feature

ClusterFeature

In/Out

6.40.2. list GET

Lists the additional features enabled for the cluster.

For example, to get the features enabled for cluster 123 send a request like this:

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

This will return a list of features:

<enabled_features>
  <cluster_feature id="123">
     <name>test_feature</name>
  </cluster_feature>
  ...
</enabled_features>
Table 121. Parameters summary
Name Type Direction Summary

features

ClusterFeature[]

Out

Retrieved features.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.41. ClusterExternalProviders

This service lists external providers.

Table 122. Methods summary
Name Summary

list

Returns the list of external providers.

6.41.1. list GET

Returns the list of external providers.

The order of the returned list of providers is not guaranteed.

Table 123. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

providers

ExternalProvider[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.42. ClusterFeature

Represents a feature enabled for the cluster level

Table 124. Methods summary
Name Summary

get

Provides the information about the a cluster feature supported by a cluster level.

6.42.1. get GET

Provides the information about the a cluster feature supported by a cluster level.

For example, to find details of the cluster feature 456 for cluster level 4.1, send a request like this:

GET /ovirt-engine/api/clusterlevels/4.1/clusterfeatures/456

That will return a ClusterFeature object containing the name:

<cluster_feature id="456">
  <name>libgfapi_supported</name>
</cluster_feature>
Table 125. Parameters summary
Name Type Direction Summary

feature

ClusterFeature

Out

Retrieved cluster feature.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.43. ClusterFeatures

Provides information about the cluster features that are supported by a cluster level.

Table 126. Methods summary
Name Summary

list

Lists the cluster features supported by the cluster level.

6.43.1. list GET

Lists the cluster features supported by the cluster level.

GET /ovirt-engine/api/clusterlevels/4.1/clusterfeatures

This will return a list of cluster features supported by the cluster level:

<cluster_features>
  <cluster_feature id="123">
     <name>test_feature</name>
  </cluster_feature>
  ...
</cluster_features>
Table 127. Parameters summary
Name Type Direction Summary

features

ClusterFeature[]

Out

Retrieved features.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.44. ClusterLevel

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

Table 128. Methods summary
Name Summary

get

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

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

follow

String

In

Indicates which inner links should be followed.

level

ClusterLevel

Out

Retreived cluster level.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

list

Lists the cluster levels supported by the system.

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

The order of the returned cluster levels isn’t guaranteed.

Table 131. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

levels

ClusterLevel[]

Out

Retrieved cluster levels.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.46. ClusterNetwork

A service to manage a specific cluster network.

Table 132. Methods summary
Name Summary

get

Retrieves the cluster network details.

remove

Unassigns the network from a cluster.

update

Updates the network in the cluster.

6.46.1. get GET

Retrieves the cluster network details.

Table 133. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

network

Network

Out

The cluster network.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.46.2. remove DELETE

Unassigns the network from a cluster.

6.46.3. update PUT

Updates the network in the cluster.

Table 134. Parameters summary
Name Type Direction Summary

network

Network

In/Out

The cluster network.

6.47. ClusterNetworks

A service to manage cluster networks.

Table 135. Methods summary
Name Summary

add

Assigns the network to a cluster.

list

Lists the networks that are assigned to the cluster.

6.47.1. add POST

Assigns the network to a cluster.

Post a request like in the example below to assign the network to a cluster:

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

Use the following example in its body:

<network id="123" />
Table 136. Parameters summary
Name Type Direction Summary

network

Network

In/Out

The network object to be assigned to the cluster.

6.47.2. list GET

Lists the networks that are assigned to the cluster.

The order of the returned clusters isn’t guaranteed.

Table 137. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

The list of networks that are assigned to the cluster.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.48. Clusters

A service to manage clusters.

Table 138. Methods summary
Name Summary

add

Creates a new cluster.

list

Returns the list of clusters of the system.

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

POST /ovirt-engine/api/clusters

With a request body like this:

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

To create a cluster with an external network provider to be deployed on every host that is added to the cluster, send a request like this:

POST /ovirt-engine/api/clusters

With a request body containing a reference to the desired provider:

<cluster>
  <name>mycluster</name>
  <cpu>
    <type>Intel Nehalem Family</type>
  </cpu>
  <data_center id="123"/>
  <external_network_providers>
    <external_provider name="ovirt-provider-ovn"/>
  </external_network_providers>
</cluster>
Table 139. Parameters summary
Name Type Direction Summary

cluster

Cluster

In/Out

6.48.2. list GET

Returns the list of clusters of the system.

The order of the returned clusters is guaranteed only if the sortby clause is included in the search parameter.

Table 140. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

Indicates if the search 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.

follow

String

In

Indicates which inner links should be followed.

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 should be performed taking case into account. The default value is true, which means that case is taken into account. To search ignoring case, set it to false.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.49. Copyable

Table 141. Methods summary
Name Summary

copy

6.49.1. copy POST

Table 142. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

6.50. CpuProfile

Table 143. Methods summary
Name Summary

get

remove

update

Update the specified cpu profile in the system.

6.50.1. get GET

Table 144. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

profile

CpuProfile

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.50.2. remove DELETE

Table 145. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.50.3. update PUT

Update the specified cpu profile in the system.

Table 146. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

CpuProfile

In/Out

6.51. CpuProfiles

Table 147. Methods summary
Name Summary

add

Add a new cpu profile to the system.

list

Returns the list of CPU profiles of the system.

6.51.1. add POST

Add a new cpu profile to the system.

Table 148. Parameters summary
Name Type Direction Summary

profile

CpuProfile

In/Out

6.51.2. list GET

Returns the list of CPU profiles of the system.

The order of the returned list of CPU profiles is random.

Table 149. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profile

CpuProfile[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.52. DataCenter

A service to manage a data center.

Table 150. Methods summary
Name Summary

get

Get a data center.

remove

Removes the data center.

update

Updates the data center.

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

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

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

6.53. DataCenterNetwork

A service to manage a specific data center network.

Table 154. Methods summary
Name Summary

get

Retrieves the data center network details.

remove

Removes the network.

update

Updates the network in the data center.

6.53.1. get GET

Retrieves the data center network details.

Table 155. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

network

Network

Out

The data center network.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.53.2. remove DELETE

Removes the network.

6.53.3. update PUT

Updates the network in the data center.

Table 156. Parameters summary
Name Type Direction Summary

network

Network

In/Out

The data center network.

6.54. DataCenterNetworks

A service to manage data center networks.

Table 157. Methods summary
Name Summary

add

Create a new network in a data center.

list

Lists networks in the data center.

6.54.1. add POST

Create a new network in a data center.

Post a request like in the example below to create a new network in a data center with an ID of 123.

POST /ovirt-engine/api/datacenters/123/networks

Use the following example in its body:

<network>
  <name>mynetwork</name>
</network>
Table 158. Parameters summary
Name Type Direction Summary

network

Network

In/Out

The network object to be created in the data center.

6.54.2. list GET

Lists networks in the data center.

The order of the returned list of networks isn’t guaranteed.

Table 159. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

The list of networks which are in the data center.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.55. DataCenters

A service to manage data centers.

Table 160. Methods summary
Name Summary

add

Creates a new data center.

list

Lists the data centers.

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

data_center

DataCenter

In/Out

The data center that is being added.

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

The order of the returned list of data centers is guaranteed only if the sortby clause is included in the search parameter.

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

follow

String

In

Indicates which inner links should be followed.

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.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.56. Disk

Manages a single disk.

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

reduce

Reduces the size of the disk image.

refreshlun

Refreshes a direct LUN disk with up-to-date information from the storage.

remove

Removes a disk.

sparsify

Sparsify the disk.

update

Updates the parameters of the specified disk.

6.56.1. copy POST

This operation copies a disk to the specified storage domain.

For example, a disk can be copied 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>

If the disk profile or the quota currently used by the disk are not defined for the new storage domain, they can be explicitly specified. If they are not specified, the first available disk profile and the default quota are used.

For example, to specify disk profile 987 and quota 753, send a request body like this:

<action>
  <storage_domain id="456"/>
  <disk_profile id="987"/>
  <quota id="753"/>
</action>
Table 164. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

disk

Disk

In

disk_profile

DiskProfile

In

Disk profile for the disk in the new storage domain.

filter

Boolean

In

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

quota

Quota

In

Quota for the disk in the new storage domain.

storage_domain

StorageDomain

In

The storage domain where the new disk is created.

disk_profile

Disk profile for the disk in the new storage domain.

Disk profiles are defined for storage domains, so the old disk profile will not exist in the new storage domain. If this parameter is not used, the first disk profile from the new storage domain to which the user has permissions will be assigned to the disk.

quota

Quota for the disk in the new storage domain.

This optional parameter can be used to specify new quota for the disk, because the current quota may not be defined for the new storage domain. If this parameter is not used and the old quota is not defined for the new storage domain, the default (unlimited) quota will be assigned to the disk.

storage_domain

The storage domain where the new disk is created. This can be specified using the id or name attributes. For example, to copy a disk to the storage domain called 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>

6.56.2. export POST

Exports a disk to an export storage domain.

Table 165. 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 will be exported to.

6.56.3. get GET

Retrieves the description of the disk.

Table 166. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

Indicates if all of the attributes of the disk should be included in the response.

disk

Disk

Out

The description of the disk.

follow

String

In

Indicates which inner links should be followed.

all_content

Indicates if all of the attributes of the disk should be included in the response.

By default the following disk attributes are excluded:

  • vms

For example, to retrieve the complete representation of disk '123':

GET /ovirt-engine/api/disks/123?all_content=true
follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

If the disk profile or the quota used currently by the disk aren’t defined for the new storage domain, then they can be explicitly specified. If they aren’t then the first available disk profile and the default quota are used.

For example, to explicitly use disk profile 987 and quota 753 send a request body like this:

<action>
  <storage_domain id="456"/>
  <disk_profile id="987"/>
  <quota id="753"/>
</action>
Table 167. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the move should be performed asynchronously.

disk_profile

DiskProfile

In

Disk profile for the disk in the new storage domain.

filter

Boolean

In

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

quota

Quota

In

Quota for the disk in the new storage domain.

storage_domain

StorageDomain

In

The storage domain where the disk will be moved to.

disk_profile

Disk profile for the disk in the new storage domain.

Disk profiles are defined for storage domains, so the old disk profile will not exist in the new storage domain. If this parameter is not used, the first disk profile from the new storage domain to which the user has permissions will be assigned to the disk.

quota

Quota for the disk in the new storage domain.

This optional parameter can be used to specify new quota for the disk, because the current quota may not be defined for the new storage domain. If this parameter is not used and the old quota is not defined for the new storage domain, the default (unlimited) quota will be assigned to the disk.

6.56.5. reduce POST

Reduces the size of the disk image.

Invokes reduce on the logical volume (i.e. this is only applicable for block storage domains). This is applicable for floating disks and disks attached to non-running virtual machines. There is no need to specify the size as the optimal size is calculated automatically.

Table 168. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.56.6. refreshlun POST

Refreshes a direct LUN disk with up-to-date information from the storage.

Refreshing a direct LUN disk is useful when:

  • The LUN was added using the API without the host parameter, and therefore does not contain any information from the storage (see DisksService::add).

  • New information about the LUN is available on the storage and you want to update the LUN with it.

To refresh direct LUN disk 123 using host 456, send the following request:

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

With the following request body:

<action>
  <host id='456'/>
</action>
Table 169. Parameters summary
Name Type Direction Summary

host

Host

In

The host that will be used to refresh the direct LUN disk.

6.56.7. remove DELETE

Removes a disk.

Table 170. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

6.56.9. update PUT

Updates the parameters of the specified disk.

This operation allows updating the following floating disk properties:

  • For Image disks: provisioned_size, alias, description, wipe_after_delete, shareable, backup and disk_profile.

  • For LUN disks: alias, description and shareable.

  • For Cinder and Managed Block disks: provisioned_size, alias and description.

  • For VM attached disks, the qcow_version can also be updated.

For example, a disk’s update can be done by using the following request:

PUT /ovirt-engine/api/disks/123

With a request body like this:

<disk>
  <qcow_version>qcow2_v3</qcow_version>
  <alias>new-alias</alias>
  <description>new-desc</description>
</disk>

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

Table 171. Parameters summary
Name Type Direction Summary

disk

Disk

In/Out

The update to apply to the disk.

6.57. DiskAttachment

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

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

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

attachment

DiskAttachment

Out

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

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

disk_attachment

DiskAttachment

In/Out

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

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

attachment

DiskAttachment

In/Out

The disk attachment to add to the virtual machine.

6.58.2. list GET

List the disk that are attached to the virtual machine.

The order of the returned list of disks attachments isn’t guaranteed.

Table 178. Parameters summary
Name Type Direction Summary

attachments

DiskAttachment[]

Out

A list of disk attachments that are attached to the virtual machine.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.59. DiskProfile

Table 179. Methods summary
Name Summary

get

remove

update

Update the specified disk profile in the system.

6.59.1. get GET

Table 180. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

profile

DiskProfile

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.59.2. remove DELETE

Table 181. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.59.3. update PUT

Update the specified disk profile in the system.

Table 182. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

DiskProfile

In/Out

6.60. DiskProfiles

Table 183. Methods summary
Name Summary

add

Add a new disk profile to the system.

list

Returns the list of disk profiles of the system.

6.60.1. add POST

Add a new disk profile to the system.

Table 184. Parameters summary
Name Type Direction Summary

profile

DiskProfile

In/Out

6.60.2. list GET

Returns the list of disk profiles of the system.

The order of the returned list of disk profiles isn’t guaranteed.

Table 185. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of profiles to return.

profile

DiskProfile[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.61. DiskSnapshot

Table 186. Methods summary
Name Summary

get

remove

6.61.1. get GET

Table 187. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

snapshot

DiskSnapshot

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.61.2. remove DELETE

Table 188. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.62. DiskSnapshots

Manages the collection of disk snapshots available in an storage domain.

Table 189. Methods summary
Name Summary

list

Returns the list of disk snapshots of the storage domain.

6.62.1. list GET

Returns the list of disk snapshots of the storage domain.

The order of the returned list of disk snapshots isn’t guaranteed.

Table 190. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

DiskSnapshot[]

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.63. Disks

Manages the collection of disks available in the system.

Table 191. Methods summary
Name Summary

add

Adds a new floating disk.

list

Get list of disks.

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

Note that block storage domains (i.e., storage domains with the storage type of iSCSI or FCP) don’t support the combination of the raw format with sparse=true, so sparse=false must be stated explicitly.

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>

Adding a floating disks in order to upload disk snapshots:

Since version 4.2 of the engine it is possible to upload disks with snapshots. This request should be used to create the base image of the images chain (The consecutive disk snapshots (images), should be created using disk-attachments element when creating a snapshot).

The disk has to be created with the same disk identifier and image identifier of the uploaded image. I.e. the identifiers should be saved as part of the backup process. The image identifier can be also fetched using the qemu-img info command. For example, if the disk image is stored into a file named b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img:

$ qemu-img info b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img
image: b548366b-fb51-4b41-97be-733c887fe305
file format: qcow2
virtual size: 1.0G (1073741824 bytes)
disk size: 196K
cluster_size: 65536
backing file: ad58716a-1fe9-481f-815e-664de1df04eb
backing file format: raw

To create a disk with with the disk identifier and image identifier obtained with the qemu-img info command shown above, send a request like this:

POST /ovirt-engine/api/disks

With a request body as follows:

<disk id="b7a4c6c5-443b-47c5-967f-6abc79675e8b">
  <image_id>b548366b-fb51-4b41-97be-733c887fe305</image_id>
  <storage_domains>
    <storage_domain id="123"/>
  </storage_domains>
  <name>mydisk</name>
  <provisioned_size>1048576</provisioned_size>
  <format>cow</format>
</disk>
Table 192. Parameters summary
Name Type Direction Summary

disk

Disk

In/Out

The disk.

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

The order of the returned list of disks is guaranteed only if the sortby clause is included in the search parameter.

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

follow

String

In

Indicates which inner links should be followed.

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.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.64. Domain

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

Table 194. Methods summary
Name Summary

get

Gets the authentication domain information.

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

domain

Domain

Out

The authentication domain.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.65. DomainGroup

Table 196. Methods summary
Name Summary

get

6.65.1. get GET

Table 197. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

get

Group

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.66. DomainGroups

Table 198. Methods summary
Name Summary

list

Returns the list of groups.

6.66.1. list GET

Returns the list of groups.

The order of the returned list of groups isn’t guaranteed.

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

follow

String

In

Indicates which inner links should be followed.

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.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.67. DomainUser

A service to view a domain user in the system.

Table 200. Methods summary
Name Summary

get

Gets the domain user information.

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

follow

String

In

Indicates which inner links should be followed.

user

User

Out

The domain user.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.68. DomainUserGroups

A service that shows a user’s group membership in the AAA extension.

Table 202. Methods summary
Name Summary

list

Returns the list of groups that the user is a member of.

6.68.1. list GET

Returns the list of groups that the user is a member of.

Table 203. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

groups

Group[]

Out

The list of groups that the user is a member of.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.69. DomainUsers

A service to list all domain users in the system.

Table 204. Methods summary
Name Summary

list

List all the users in the domain.

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

The order of the returned list of users isn’t guaranteed.

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

follow

String

In

Indicates which inner links should be followed.

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.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.70. Domains

A service to list all authentication domains in the system.

Table 206. Methods summary
Name Summary

list

List all the authentication domains in the system.

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

The order of the returned list of domains isn’t guaranteed.

Table 207. Parameters summary
Name Type Direction Summary

domains

Domain[]

Out

The list of domains.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of domains to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.71. EngineKatelloErrata

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

Table 208. Methods summary
Name Summary

list

Retrieves the representation of the Katello errata.

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

The order of the returned list of erratum isn’t guaranteed.

Table 209. Parameters summary
Name Type Direction Summary

errata

KatelloErratum[]

Out

A representation of Katello errata.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of errata to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.72. Event

A service to manage an event in the system.

Table 210. Methods summary
Name Summary

get

Get an event.

remove

Removes an event from internal audit log.

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

event

Event

Out

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.73. EventSubscription

A service to manage a specific event-subscription in the system.

Table 213. Methods summary
Name Summary

get

Gets the information about the event-subscription.

remove

Removes the event-subscription from the system.

6.73.1. get GET

Gets the information about the event-subscription.

For example to retrieve the information about the subscription of user '123' to the event 'vm_console_detected':

GET /ovirt-engine/api/users/123/vm_console_detected
<event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/vm_console_detected">
  <event>vm_console_detected</event>
  <notification_method>smtp</notification_method>
  <user href="/ovirt-engine/api/users/123" id="123"/>
  <address>a@b.com</address>
</event-subscription>
Table 214. Parameters summary
Name Type Direction Summary

event_subscription

EventSubscription

Out

The event-subscription.

6.73.2. remove DELETE

Removes the event-subscription from the system.

For example to remove user 123’s subscription to vm_console_detected event:

DELETE /ovirt-engine/api/users/123/vm_console_detected
Table 215. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.74. EventSubscriptions

Represents a service to manage collection of event-subscription of a user.

Table 216. Methods summary
Name Summary

add

Add a new event-subscription to the system.

list

List the event-subscriptions for the provided user.

6.74.1. add POST

Add a new event-subscription to the system.

An event-subscription is always added in the context of a user. For example, to add new event-subscription for host_high_cpu_use for user 123, and have the notification sent to the e-mail address: a@b.com, send a request like this:

POST /ovirt-engine/api/users/123/eventsubscriptions

With a request body like this:

<event_subscription>
    <event>host_high_cpu_use</event>
    <address>a@b.com</address>
</event_subscription>

The event name will become the ID of the new event-subscription entity: GET …​/api/users/123/eventsubscriptions/host_high_cpu_use

Note that no user id is provided in the request body. This is because the user-id (in this case 123) is already known to the API from the context. Note also that event-subscription entity contains notification-method field, but it is not provided either in the request body. This is because currently it’s always set to SMTP as SNMP notifications are still unsupported by the API layer.

Table 217. Parameters summary
Name Type Direction Summary

event_subscription

EventSubscription

In/Out

The added event-subscription.

6.74.2. list GET

List the event-subscriptions for the provided user.

For example to list event-subscriptions for user 123:

GET /ovirt-engine/api/users/123/event-subscriptions
<event-subscriptions>
  <event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/host_install_failed">
    <event>host_install_failed</event>
    <notification_method>smtp</notification_method>
    <user href="/ovirt-engine/api/users/123" id="123"/>
    <address>a@b.com</address>
  </event-subscription>
  <event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/vm_paused">
    <event>vm_paused</event>
    <notification_method>smtp</notification_method>
    <user href="/ovirt-engine/api/users/123" id="123"/>
    <address>a@b.com</address>
  </event-subscription>
</event-subscriptions>
Table 218. Parameters summary
Name Type Direction Summary

event_subscriptions

EventSubscription[]

Out

List of the event-subscriptions for the specified user

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of event-subscriptions to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

Sets the maximum number of event-subscriptions to return. If not specified all the event-subscriptions are returned.

6.75. Events

A service to manage events in the system.

Table 219. Methods summary
Name Summary

add

Adds an external event to the internal audit log.

list

Get list of events.

undelete

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

event

Event

In/Out

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

The order of the returned list of events is always garanteed. If the sortby clause is included in the search parameter, then the events will be ordered according to that clause. If the sortby clause isn’t included, then the events will be sorted by the numeric value of the id attribute, starting with the highest value. This, combined with the max parameter, simplifies obtaining the most recent event:

GET /ovirt-engine/api/events?max=1
Table 221. 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

follow

String

In

Indicates which inner links should be followed.

from

Integer

In

Indicates the event index after which events 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.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

from

Indicates the event index after which events should be returned. The indexes of events are strictly increasing, so when this parameter is used only the events with greater indexes will be returned. For example, the following request will return only the events with indexes greater 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

6.75.3. undelete POST

Table 222. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the un-delete should be performed asynchronously.

6.76. ExternalComputeResource

Manages a single external compute resource.

Compute resource is a term of host external provider. The external provider also needs to know to where the provisioned host needs to register. The login details of the engine are saved as a compute resource in the external provider side.

Table 223. Methods summary
Name Summary

get

Retrieves external compute resource details.

6.76.1. get GET

Retrieves external compute resource details.

For example, to get the details of compute resource 234 of provider 123, send a request like this:

GET /ovirt-engine/api/externalhostproviders/123/computeresources/234

It will return a response like this:

<external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234">
  <name>hostname</name>
  <provider>oVirt</provider>
  <url>https://hostname/api</url>
  <user>admin@internal</user>
  <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
</external_compute_resource>
Table 224. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

resource

ExternalComputeResource

Out

External compute resource information

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.77. ExternalComputeResources

Manages a collection of external compute resources.

Compute resource is a term of host external provider. The external provider also needs to know to where the provisioned host needs to register. The login details of the engine is saved as a compute resource in the external provider side.

Table 225. Methods summary
Name Summary

list

Retrieves a list of external compute resources.

6.77.1. list GET

Retrieves a list of external compute resources.

For example, to retrieve the compute resources of external host provider 123, send a request like this:

GET /ovirt-engine/api/externalhostproviders/123/computeresources

It will return a response like this:

<external_compute_resources>
  <external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234">
    <name>hostname</name>
    <provider>oVirt</provider>
    <url>https://address/api</url>
    <user>admin@internal</user>
    <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
   </external_compute_resource>
   ...
</external_compute_resources>

The order of the returned list of compute resources isn’t guaranteed.

Table 226. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of resources to return.

resources

ExternalComputeResource[]

Out

List of external computer resources.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.78. ExternalDiscoveredHost

This service manages a single discovered host.

Table 227. Methods summary
Name Summary

get

Get discovered host info.

6.78.1. get GET

Get discovered host info.

Retrieves information about an host that is managed in external provider management system, such as Foreman. The information includes hostname, address, subnet, base image and more.

For example, to get the details of host 234 from provider 123, send a request like this:

GET /ovirt-engine/api/externalhostproviders/123/discoveredhosts/234

The result will be like this:

<external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/234" id="234">
 <name>mac001a4ad04040</name>
 <ip>10.34.67.43</ip>
 <last_report>2017-04-24 11:05:41 UTC</last_report>
 <mac>00:1a:4a:d0:40:40</mac>
 <subnet_name>sat0</subnet_name>
 <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
</external_discovered_host>
Table 228. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

host

ExternalDiscoveredHost

Out

Host’s hardware and config information.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.79. ExternalDiscoveredHosts

This service manages external discovered hosts.

Table 229. Methods summary
Name Summary

list

Get list of discovered hosts' information.

6.79.1. list GET

Get list of discovered hosts' information.

Discovered hosts are fetched from third-party providers such as Foreman.

To list all discovered hosts for provider 123 send the following:

GET /ovirt-engine/api/externalhostproviders/123/discoveredhost
<external_discovered_hosts>
 <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/456" id="456">
  <name>mac001a4ad04031</name>
  <ip>10.34.67.42</ip>
  <last_report>2017-04-24 11:05:41 UTC</last_report>
  <mac>00:1a:4a:d0:40:31</mac>
  <subnet_name>sat0</subnet_name>
  <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
 </external_discovered_host>
 <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/789" id="789">
  <name>mac001a4ad04040</name>
  <ip>10.34.67.43</ip>
  <last_report>2017-04-24 11:05:41 UTC</last_report>
  <mac>00:1a:4a:d0:40:40</mac>
  <subnet_name>sat0</subnet_name>
  <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
 </external_discovered_host>
 ...
</external_discovered_hosts>

The order of the returned list of hosts isn’t guaranteed.

Table 230. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

hosts

ExternalDiscoveredHost[]

Out

List of discovered hosts

max

Integer

In

Sets the maximum number of hosts to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.80. ExternalHost

Table 231. Methods summary
Name Summary

get

6.80.1. get GET

Table 232. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

host

ExternalHost

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.81. ExternalHostGroup

This service manages a single host group information.

Host group is a term of host provider - the host group includes provision details that are applied to new discovered host. Information such as subnet, operating system, domain, etc.

Table 233. Methods summary
Name Summary

get

Get host group information.

6.81.1. get GET

Get host group information.

For example, to get the details of hostgroup 234 of provider 123, send a request like this:

GET /ovirt-engine/api/externalhostproviders/123/hostgroups/234

It will return a response like this:

<external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234">
  <name>rhel7</name>
  <architecture_name>x86_64</architecture_name>
  <domain_name>s.com</domain_name>
  <operating_system_name>RedHat 7.3</operating_system_name>
  <subnet_name>sat0</subnet_name>
  <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
</external_host_group>
Table 234. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

group

ExternalHostGroup

Out

Host group information.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.82. ExternalHostGroups

This service manages hostgroups.

Table 235. Methods summary
Name Summary

list

Get host groups list from external host provider.

6.82.1. list GET

Get host groups list from external host provider.

Host group is a term of host providers - the host group includes provision details. This API returns all possible hostgroups exposed by the external provider.

For example, to get the details of all host groups of provider 123, send a request like this:

GET /ovirt-engine/api/externalhostproviders/123/hostgroups

The response will be like this:

<external_host_groups>
  <external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234">
    <name>rhel7</name>
    <architecture_name>x86_64</architecture_name>
    <domain_name>example.com</domain_name>
    <operating_system_name>RedHat 7.3</operating_system_name>
    <subnet_name>sat0</subnet_name>
    <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/>
  </external_host_group>
  ...
</external_host_groups>

The order of the returned list of host groups isn’t guaranteed.

Table 236. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

groups

ExternalHostGroup[]

Out

List of all hostgroups available for external host provider

max

Integer

In

Sets the maximum number of groups to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.83. ExternalHostProvider

Represents an external host provider, such as Foreman or Satellite.

See https://www.theforeman.org/ for more details on Foreman. See https://access.redhat.com/products/red-hat-satellite for more details on Red Hat Satellite.

Table 237. Methods summary
Name Summary

get

Get external host provider information

Host provider, Foreman or Satellite, can be set as an external provider in ovirt.

importcertificates

Import the SSL certificates of the external host provider.

remove

testconnectivity

In order to test connectivity for external provider we need to run following request where 123 is an id of a provider.

update

Update the specified external host provider in the system.

6.83.1. get GET

Get external host provider information

Host provider, Foreman or Satellite, can be set as an external provider in ovirt. To see details about specific host providers attached to ovirt use this API.

For example, to get the details of host provider 123, send a request like this:

GET /ovirt-engine/api/externalhostproviders/123

The response will be like this:

<external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123">
  <name>mysatellite</name>
  <requires_authentication>true</requires_authentication>
  <url>https://mysatellite.example.com</url>
  <username>admin</username>
</external_host_provider>
Table 238. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

provider

ExternalHostProvider

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.83.2. importcertificates POST

Import the SSL certificates of the external host provider.

Table 239. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

6.83.3. remove DELETE

Table 240. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.83.4. testconnectivity POST

In order to test connectivity for external provider we need to run following request where 123 is an id of a provider.

POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
Table 241. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.83.5. update PUT

Update the specified external host provider in the system.

Table 242. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

ExternalHostProvider

In/Out

6.84. ExternalHostProviders

Table 243. Methods summary
Name Summary

add

Add a new external host provider to the system.

list

Returns the list of external host providers.

6.84.1. add POST

Add a new external host provider to the system.

Table 244. Parameters summary
Name Type Direction Summary

provider

ExternalHostProvider

In/Out

6.84.2. list GET

Returns the list of external host providers.

The order of the returned list of host providers isn’t guaranteed.

Table 245. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of providers to return.

providers

ExternalHostProvider[]

Out

search

String

In

A query string used to restrict the returned external host providers.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.85. ExternalHosts

Table 246. Methods summary
Name Summary

list

Return the list of external hosts.

6.85.1. list GET

Return the list of external hosts.

The order of the returned list of hosts isn’t guaranteed.

Table 247. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

hosts

ExternalHost[]

Out

max

Integer

In

Sets the maximum number of hosts to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.86. ExternalNetworkProviderConfiguration

Describes how an external network provider is provisioned by the system on the host.

Table 248. Methods summary
Name Summary

get

Returns the information about an external network provider on the host.

6.86.1. get GET

Returns the information about an external network provider on the host.

Table 249. Parameters summary
Name Type Direction Summary

configuration

ExternalNetworkProviderConfiguration

Out

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.87. ExternalNetworkProviderConfigurations

A service to list all external network providers provisioned by the system on the host.

Table 250. Methods summary
Name Summary

list

Returns the list of all external network providers on the host.

6.87.1. list GET

Returns the list of all external network providers on the host.

The order of the returned list of networks is not guaranteed.

Table 251. Parameters summary
Name Type Direction Summary

configurations

ExternalNetworkProviderConfiguration[]

Out

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.88. ExternalProvider

Provides capability to manage external providers.

Table 252. Methods summary
Name Summary

importcertificates

Import the SSL certificates of the external host provider.

testconnectivity

In order to test connectivity for external provider we need to run following request where 123 is an id of a provider.

6.88.1. importcertificates POST

Import the SSL certificates of the external host provider.

Table 253. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

6.88.2. testconnectivity POST

In order to test connectivity for external provider we need to run following request where 123 is an id of a provider.

POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
Table 254. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.89. ExternalProviderCertificate

A service to view specific certificate for external provider.

Table 255. Methods summary
Name Summary

get

Get specific certificate.

6.89.1. get GET

Get specific certificate.

GET /ovirt-engine/api/externalhostproviders/123/certificate/0

And here is sample response:

<certificate id="0">
  <organization>provider.example.com</organization>
  <subject>CN=provider.example.com</subject>
  <content>...</content>
</certificate>
Table 256. Parameters summary
Name Type Direction Summary

certificate

Certificate

Out

The details of the certificate.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.90. ExternalProviderCertificates

A service to view certificates for external provider.

Table 257. Methods summary
Name Summary

list

Returns the chain of certificates presented by the external provider.

6.90.1. list GET

Returns the chain of certificates presented by the external provider.

GET /ovirt-engine/api/externalhostproviders/123/certificates

And here is sample response:

<certificates>
  <certificate id="789">...</certificate>
  ...
</certificates>

The order of the returned certificates is always guaranteed to be the sign order: the first is the certificate of the server itself, the second the certificate of the CA that signs the first, so on.

Table 258. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

Out

List containing certificate details.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of certificates to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.91. ExternalVmImports

Provides capability to import external virtual machines.

Table 259. Methods summary
Name Summary

add

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

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

import

ExternalVmImport

In/Out

6.92. FenceAgent

A service to manage fence agent for a specific host.

Table 261. Methods summary
Name Summary

get

Gets details of this fence agent.

remove

Removes a fence agent for a specific host.

update

Update a fencing-agent.

6.92.1. get GET

Gets details of this fence agent.

GET /ovirt-engine/api/hosts/123/fenceagents/0

And here is sample response:

<agent id="0">
  <type>apc</type>
  <order>1</order>
  <ip>192.168.1.101</ip>
  <user>user</user>
  <password>xxx</password>
  <port>9</port>
  <options>name1=value1, name2=value2</options>
</agent>
Table 262. Parameters summary
Name Type Direction Summary

agent

Agent

Out

Fence agent details.

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.92.2. remove DELETE

Removes a fence agent for a specific host.

DELETE /ovirt-engine/api/hosts/123/fenceagents/0
Table 263. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.92.3. update PUT

Update a fencing-agent.

Table 264. Parameters summary
Name Type Direction Summary

agent

Agent

In/Out

Fence agent details.

async

Boolean

In

Indicates if the update should be performed asynchronously.

6.93. FenceAgents

A service to manage fence agents for a specific host.

Table 265. Methods summary
Name Summary

add

Add a new fencing-agent to the host.

list

Returns the list of fencing agents configured for the host.

6.93.1. add POST

Add a new fencing-agent to the host.

POST /ovirt-engine/api/hosts/123/fenceagents

You should consult the /usr/sbin/fence_<agent_name> manual page for
the legal parameters to [name1=value1, name2=value2,...] in the options field.
If any parameter in options appears by name that means that it is mandatory.
For example in <options>slot=7[,name1=value1, name2=value2,...]</options>
slot is mandatory.

apc, bladecenter, wti fencing agent/s sample request:

  <agent>
    <type>apc</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <port>9</port>
    <options>slot=7[,name1=value1, name2=value2,...]</options>
  </agent>

apc_snmp, hpblade, ilo, ilo2, ilo_ssh, redfish, rsa fencing agent/s sample request:

  <agent>
    <type>apc_snmp</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <port>9</port>
    <options>[name1=value1, name2=value2,...]</options>
  </agent>

cisco_ucs, drac5, eps fencing agent/s sample request:

  <agent>
    <type>cisco_ucs</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <options>slot=7[,name1=value1, name2=value2,...]</options>
  </agent>

drac7, ilo3, ilo4, ipmilan, rsb fencing agent/s sample request:

  <agent>
    <type>drac7</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <options>[name1=value1, name2=value2,...]</options>
  </agent>
Table 266. Parameters summary
Name Type Direction Summary

agent

Agent

In/Out

6.93.2. list GET

Returns the list of fencing agents configured for the host.

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

And here is sample response:

<agents>
  <agent id="0">
    <type>apc</type>
    <order>1</order>
    <ip>192.168.1.101</ip>
    <user>user</user>
    <password>xxx</password>
    <port>9</port>
    <options>name1=value1, name2=value2</options>
  </agent>
</agents>

The order of the returned list of fencing agents isn’t guaranteed.

Table 267. Parameters summary
Name Type Direction Summary

agents

Agent[]

Out

List of fence agent details.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of agents to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.94. File

Table 268. Methods summary
Name Summary

get

6.94.1. get GET

Table 269. Parameters summary
Name Type Direction Summary

file

File

Out

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.95. Files

Provides a way for clients to list available files.

This service is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks (VFDs) that an administrator uploads.

The addition of a CD-ROM device to a virtual machine requires an ISO image from the files of an ISO storage domain.

Table 270. Methods summary
Name Summary

list

Returns the list of ISO images and virtual floppy disks available in the storage domain.

6.95.1. list GET

Returns the list of ISO images and virtual floppy disks available in the storage domain. The order of the returned list is not guaranteed.

If the refresh parameter is false, the returned list may not reflect recent changes to the storage domain; for example, it may not contain a new ISO file that was recently added. This is because the server caches the list of files to improve performance. To get the very latest results, set the refresh parameter to true.

The default value of the refresh parameter is true, but it can be changed using the configuration value ForceRefreshDomainFilesByDefault:

# engine-config -s ForceRefreshDomainFilesByDefault=false
Setting the value of the refresh parameter to true has an impact on the performance of the server. Use it only if necessary.
Table 271. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

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

file

File[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of files to return.

refresh

Boolean

In

Indicates whether the list of files should be refreshed from the storage domain, rather than showing cached results that are updated at certain intervals.

search

String

In

A query string used to restrict the returned files.

case_sensitive

Indicates if the search performed using the search parameter should take case into account. The default value is true.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.96. Filter

Table 272. Methods summary
Name Summary

get

remove

6.96.1. get GET

Table 273. Parameters summary
Name Type Direction Summary

filter

Boolean

In

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

follow

String

In

Indicates which inner links should be followed.

result

Filter

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.96.2. remove DELETE

Table 274. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.97. Filters

Manages the filters used by an scheduling policy.

Table 275. Methods summary
Name Summary

add

Add a filter to a specified user defined scheduling policy.

list

Returns the list of filters used by the scheduling policy.

6.97.1. add POST

Add a filter to a specified user defined scheduling policy.

Table 276. Parameters summary
Name Type Direction Summary

filter

Filter

In/Out

6.97.2. list GET

Returns the list of filters used by the scheduling policy.

The order of the returned list of filters isn’t guaranteed.

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

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of filters to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.98. Follow

6.99. GlusterBrick

This service manages a single gluster brick.

Table 278. Methods summary
Name Summary

get

Get details of a brick.

remove

Removes a brick.

replace

Replaces this brick with a new one.

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

brick

GlusterBrick

Out

follow

String

In

Indicates which inner links should be followed.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the replacement should be performed asynchronously.

force

Boolean

In

6.100. GlusterBricks

This service manages the gluster bricks in a gluster volume

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

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

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

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

The order of the returned list is based on the brick order provided at gluster volume creation.

Table 285. Parameters summary
Name Type Direction Summary

bricks

GlusterBrick[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of bricks to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

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

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

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

6.101. GlusterHook

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

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.101.3. get GET

Table 292. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

hook

GlusterHook

Out

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

6.101.4. remove DELETE

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

Table 293. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

host

Host

In

resolution_type

String

In

6.102. GlusterHooks

Table 295. Methods summary
Name Summary

list

Returns the list of hooks.

6.102.1. list GET

Returns the list of hooks.

The order of the returned list of hooks isn’t guaranteed.

Table 296. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

hooks

GlusterHook[]

Out

max

Integer

In

Sets the maximum number of hooks to return.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

max

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

6.103. GlusterVolume

This service manages a single gluster volume.

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

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

follow

String

In

Indicates which inner links should be followed.

volume

GlusterVolume

Out

Representation of the gluster volume.

follow

Indicates which inner links should be followed. The objects referenced by these links will be fetched as part of the current request. See here for details.

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

details

GlusterVolumeProfileDetails

Out

Gluster volume profiling information returned from the action.

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

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the reset should be performed asynchronously.

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

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

option

Option

In

Option to set.

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

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

6.103.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 308. Parameters