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

This documentation acts as a reference for the {product-name} API. It aims to provide developers and administrators with instructions and examples to help harness the functionality of their {product-name} environment through the API, either directly or using the provided SDKs.

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.

API Prerequisites

Prerequisites for using the {product-name} API:

Authentication and Security

TLS/SSL Certification

The {product-name} API requires Hypertext Transfer Protocol Secure (HTTPS) footnote:[See RFC 2818: HTTP Over TLS 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.

Obtaining the CA Certificate

You can obtain the CA certificate from the {engine-name} 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.

  1. Run the openssl s_client command as in the following example:

    $ openssl s_client \
-connect myengine.example.com:443 \
-showcerts \
< /dev/null
    Example output
    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----- lines shows the certificates presented by the server.

    The first certificate is the certificate of the server itself. The second certificate is the certificate of the CA.

  2. Copy the CA certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, to the ca.crt file as in the following example:

    -----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 the certificate has been manually replaced by the server administrator.
Method 2

If you cannot use openssl s_client to obtain the certificate, you can use a command line tool, for example curl or wget, to download the CA certificate from the {engine-name}. curl and wget 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 is downloaded or imported into the browser’s keystore:

  • If the browser downloads the certificate, save the file as ca.crt.

  • If the browser imports the certificate, export it using the browser’s certificate management options and save it as ca.crt.

Method 4

Log in to the {engine-name}, export the certificate from the truststore, and copy it to your client machine.

  1. Log in to the {engine-name} 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.

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.

Authentication

Any user with a {engine-name} account has access to the API. All requests must be authenticated using either OAuth or basic authentication, as described below.

OAuth Authentication

Since version 4.0 of {product-name} 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 {product-name} API, the only supported one is the Resource Owner Password Credentials Grant, as described in RFC 6749.

You must first obtain a token, sending the user name and password to the {engine-name} 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 {product-name} API it is mandatory, and its value must be ovirt-app-api.

If the user name and password are valid, the {engine-name} 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 {engine-name} single sign-on service does not currently support refreshing tokens. A new token can be requested using the same method described above.

Basic Authentication

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

Each request uses HTTP Basic Authentication [1] 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 {engine-name} 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.

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

Common concepts

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.

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.

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.

Collections

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

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.

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.

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,
      ...
    },
  ]
}

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>

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

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.

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

Search syntax

The search parameters use the same syntax as the {product-name} 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

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*

Pagination

Some {product-name} 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.

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.

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.

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>

Quick Start Examples

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

  • A networked and configured {product-name} 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 {product-name}.

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.

{product-name} generates a unique identifier for the id attribute for each resource. Identifier codes in this example will differ from the identifier codes in your {product-name} 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.

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

List data centers

{product-name} 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.

List host clusters

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

List logical networks

{product-name} creates a default ovirtmgmt network on installation. This network acts as the management network for {engine-name} 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.

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.

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>

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>

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

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>

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

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.

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 ImageTransfer to create an image transfer and ImageTransfers 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.

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.

Requests

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

Services

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

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.

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.

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.

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.

AffinityGroupHost

This service manages a single host to affinity group assignment.

Table 7. Methods summary
Name Summary

remove

Remove host from the affinity group.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

remove DELETE

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

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

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.

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.

remove DELETE

Remove a label from a host.

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.

add POST

Add a label to a host.

Table 36. Parameters summary
Name Type Direction Summary

host

Host

In/Out

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.

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.

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.

remove DELETE

Remove a label from a vm.

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.

add POST

Add a label to a vm.

Table 41. Parameters summary
Name Type Direction Summary

vm

Vm

In/Out

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.

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.

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

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.

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

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.

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.

remove DELETE

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

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.

add POST

Attaches a label to an entity.

Table 49. Parameters summary
Name Type Direction Summary

label

AffinityLabel

In/Out

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.

AssignedCpuProfile

Table 51. Methods summary
Name Summary

get

remove

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.

remove DELETE

Table 53. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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.

add POST

Add a new cpu profile for the cluster.

Table 55. Parameters summary
Name Type Direction Summary

profile

CpuProfile

In/Out

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.

AssignedDiskProfile

Table 57. Methods summary
Name Summary

get

remove

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.

remove DELETE

Table 59. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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.

add POST

Add a new disk profile for the storage domain.

Table 61. Parameters summary
Name Type Direction Summary

profile

DiskProfile

In/Out

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

AssignedVnicProfile

Table 74. Methods summary
Name Summary

get

remove

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.

remove DELETE

Table 76. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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.

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

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.

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

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.

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.

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.

remove DELETE

Table 84. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

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.

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.

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.

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.

register POST

Registers an unregistered disk.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Balance

Table 97. Methods summary
Name Summary

get

remove

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.

remove DELETE

Table 99. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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.

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

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.

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.

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.

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.

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.

Bookmarks

A service to manage bookmarks.

Table 107. Methods summary
Name Summary

add

Adding a new bookmark.

list

Listing all the available bookmarks.

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.

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.

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, update or finish upgrade process for the cluster based on the action value.

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.

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

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.

resetemulatedmachine POST

Table 113. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

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.

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

upgrade POST

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

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>

After starting the upgrade, use a request body like this to update the progress to 15%:

<action>
    <upgrade_action>
        update_progress
    </upgrade_action>
    <upgrade_percent_complete>
        15
    </upgrade_percent_complete>
</action>
Table 116. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

correlation_id

String

In

Explicitly set the upgrade correlation identifier.

upgrade_action

ClusterUpgradeAction

In

The action to be performed.

upgrade_percent_complete

Integer

In

Update the upgrade’s progress as a percent complete of the total process.

correlation_id

Explicitly set the upgrade correlation identifier. Use to correlate events detailing the cluster upgrade to the upgrade itself. If not specificed, the correlation id from Correlation-Id http header will be used.

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.

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.

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

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.

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

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.

ClusterExternalProviders

This service lists external providers.

Table 122. Methods summary
Name Summary

list

Returns the list of external providers.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

remove DELETE

Unassigns the network from a cluster.

update PUT

Updates the network in the cluster.

Table 134. Parameters summary
Name Type Direction Summary

network

Network

In/Out

The cluster network.

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.

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.

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.

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.

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

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.

Copyable

Table 141. Methods summary
Name Summary

copy

copy POST

Table 142. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

CpuProfile

Table 143. Methods summary
Name Summary

get

remove

update

Update the specified cpu profile in the system.

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.

remove DELETE

Table 145. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

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.

add POST

Add a new cpu profile to the system.

Table 148. Parameters summary
Name Type Direction Summary

profile

CpuProfile

In/Out

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.

DataCenter

A service to manage a data center.

Table 150. Methods summary
Name Summary

cleanfinishedtasks

Currently, the storage pool manager (SPM) fails to switch to another host if the SPM has uncleared tasks.

get

Get a data center.

remove

Removes the data center.

setmaster

Used for manually setting a storage domain in the data center as a master.

update

Updates the data center.

cleanfinishedtasks POST

Currently, the storage pool manager (SPM) fails to switch to another host if the SPM has uncleared tasks. Clearing all finished tasks enables the SPM switching.

For example, to clean all the finished tasks on a data center with ID 123 send a request like this:

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

With a request body like this:

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

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

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

setmaster POST

Used for manually setting a storage domain in the data center as a master. For example, for setting a storage domain with ID '456' as a master on a data center with ID '123', send a request like this:

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

With a request body like this:

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

The new master storage domain can be also specified by its name.

Table 154. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

storage_domain

StorageDomain

In

The new master storage domain for the data center.

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

DataCenterNetwork

A service to manage a specific data center network.

Table 156. Methods summary
Name Summary

get

Retrieves the data center network details.

remove

Removes the network.

update

Updates the network in the data center.

get GET

Retrieves the data center network details.

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

remove DELETE

Removes the network.

update PUT

Updates the network in the data center.

Table 158. Parameters summary
Name Type Direction Summary

network

Network

In/Out

The data center network.

DataCenterNetworks

A service to manage data center networks.

Table 159. Methods summary
Name Summary

add

Create a new network in a data center.

list

Lists networks in the data center.

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

network

Network

In/Out

The network object to be created in the data center.

list GET

Lists networks in the data center.

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

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

DataCenters

A service to manage data centers.

Table 162. Methods summary
Name Summary

add

Creates a new data center.

list

Lists the data centers.

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

data_center

DataCenter

In/Out

The data center that is being added.

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

case_sensitive

Boolean

In

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

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.

Disk

Manages a single disk.

Table 165. Methods summary
Name Summary

convert

Converts disk format and/or preallocation mode.

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.

convert POST

Converts disk format and/or preallocation mode.

For example, to convert the disk format from preallocated-cow to a sparse-raw image, send a request like the following:

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

With the following request body:

 <action>
   <disk>
     <sparse>true</sparse>
     <format>raw</format>
   </disk>
 </action>

Note: In order to sparsify a disk, two conversions might be needed if the disk is on a Block Storage Domain. For example: If a disk is RAW, converting it to QCOW will result in a larger disk. In order to reduce the size, it is possible to convert the disk again to QCOW and keep the same allocation policy.

Table 166. Parameters summary
Name Type Direction Summary

disk

Disk

In

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.

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

export POST

Exports a disk to an export storage domain.

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

get GET

Retrieves the description of the disk.

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

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

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

host

Host

In

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

remove DELETE

Removes a disk.

Table 173. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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.

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.

  • Cinder integration has been replaced by Managed Block Storage.

  • For 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 174. Parameters summary
Name Type Direction Summary

disk

Disk

In/Out

The update to apply to the disk.

DiskAttachment

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

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

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

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

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

disk_attachment

DiskAttachment

In/Out

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

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 do not 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 180. Parameters summary
Name Type Direction Summary

attachment

DiskAttachment

In/Out

The disk attachment to add to the virtual machine.

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

DiskProfile

Table 182. Methods summary
Name Summary

get

remove

update

Update the specified disk profile in the system.

get GET

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

remove DELETE

Table 184. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update the specified disk profile in the system.

Table 185. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

DiskProfile

In/Out

DiskProfiles

Table 186. Methods summary
Name Summary

add

Add a new disk profile to the system.

list

Returns the list of disk profiles of the system.

add POST

Add a new disk profile to the system.

Table 187. Parameters summary
Name Type Direction Summary

profile

DiskProfile

In/Out

list GET

Returns the list of disk profiles of the system.

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

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

DiskSnapshot

Table 189. Methods summary
Name Summary

get

remove

get GET

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

remove DELETE

Table 191. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

DiskSnapshots

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

Table 192. Methods summary
Name Summary

list

Returns the list of disk snapshots of the storage domain.

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

follow

String

In

Indicates which inner links should be followed.

include_active

Boolean

In

If true return also active snapshots.

include_template

Boolean

In

If true return also template snapshots.

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.

include_active

If true return also active snapshots. If not specified active snapshots are not returned.

include_template

If true return also template snapshots. If not specified template snapshots are not returned.

max

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

Disks

Manages the collection of disks available in the system.

Table 194. Methods summary
Name Summary

add

Adds a new floating disk.

list

Get list of disks.

add POST

Adds a new floating disk.

There are three types of disks that can be added - disk image, direct LUN and Managed Block disk. Cinder integration has been replaced by Managed Block Storage.

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) do not 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 and enabled for incremental backup, 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>
  <backup>incremental</backup>
</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:

Cinder integration has been replaced by Managed Block Storage.

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

disk

Disk

In/Out

The disk.

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

Domain

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

Table 197. Methods summary
Name Summary

get

Gets the authentication domain information.

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

DomainGroup

Table 199. Methods summary
Name Summary

get

get GET

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

DomainGroups

Table 201. Methods summary
Name Summary

list

Returns the list of groups.

list GET

Returns the list of groups.

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

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

DomainUser

A service to view a domain user in the system.

Table 203. Methods summary
Name Summary

get

Gets the domain user information.

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

DomainUserGroups

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

Table 205. Methods summary
Name Summary

list

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

list GET

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

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

DomainUsers

A service to list all domain users in the system.

Table 207. Methods summary
Name Summary

list

List all the users in the domain.

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

Domains

A service to list all authentication domains in the system.

Table 209. Methods summary
Name Summary

list

List all the authentication domains in the system.

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

EngineKatelloErrata

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

Table 211. Methods summary
Name Summary

list

Retrieves the representation of the Katello errata.

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

Event

A service to manage an event in the system.

Table 213. Methods summary
Name Summary

get

Get an event.

remove

Removes an event from internal audit log.

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

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

EventSubscription

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

Table 216. Methods summary
Name Summary

get

Gets the information about the event-subscription.

remove

Removes the event-subscription from the system.

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

event_subscription

EventSubscription

Out

The event-subscription.

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

EventSubscriptions

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

Table 219. Methods summary
Name Summary

add

Add a new event-subscription to the system.

list

List the event-subscriptions for the provided user.

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

event_subscription

EventSubscription

In/Out

The added event-subscription.

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

Events

A service to manage events in the system.

Table 222. Methods summary
Name Summary

add

Adds an external event to the internal audit log.

list

Get list of events.

undelete

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

event

Event

In/Out

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

case_sensitive

Boolean

In

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

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.

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

undelete POST

Table 225. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the un-delete should be performed asynchronously.

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

get

Retrieves external compute resource details.

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

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

list

Retrieves a list of external compute resources.

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

ExternalDiscoveredHost

This service manages a single discovered host.

Table 230. Methods summary
Name Summary

get

Get discovered host info.

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

ExternalDiscoveredHosts

This service manages external discovered hosts.

Table 232. Methods summary
Name Summary

list

Get list of discovered hosts' information.

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

ExternalHost

Table 234. Methods summary
Name Summary

get

get GET

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

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

get

Get host group information.

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

ExternalHostGroups

This service manages hostgroups.

Table 238. Methods summary
Name Summary

list

Get host groups list from external host provider.

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

ExternalHostProvider

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

See Foreman documentation for details. See Satellite documentation for details.

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

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

importcertificates POST

Import the SSL certificates of the external host provider.

Table 242. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

remove DELETE

Table 243. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the test should be performed asynchronously.

update PUT

Update the specified external host provider in the system.

Table 245. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

ExternalHostProvider

In/Out

ExternalHostProviders

Table 246. Methods summary
Name Summary

add

Add a new external host provider to the system.

list

Returns the list of external host providers.

add POST

Add a new external host provider to the system.

Table 247. Parameters summary
Name Type Direction Summary

provider

ExternalHostProvider

In/Out

list GET

Returns the list of external host providers.

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

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

ExternalHosts

Table 249. Methods summary
Name Summary

list

Return the list of external hosts.

list GET

Return the list of external hosts.

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

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

ExternalNetworkProviderConfiguration

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

Table 251. Methods summary
Name Summary

get

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

get GET

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

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

ExternalNetworkProviderConfigurations

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

Table 253. Methods summary
Name Summary

list

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

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

ExternalProvider

Provides capability to manage external providers.

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

importcertificates POST

Import the SSL certificates of the external host provider.

Table 256. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

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

async

Boolean

In

Indicates if the test should be performed asynchronously.

ExternalProviderCertificate

A service to view specific certificate for external provider.

Table 258. Methods summary
Name Summary

get

Get specific certificate.

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

ExternalProviderCertificates

A service to view certificates for external provider.

Table 260. Methods summary
Name Summary

list

Returns the chain of certificates presented by the external provider.

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

ExternalTemplateImports

Provides capability to import external templates. Currently supports OVA only.

Table 262. Methods summary
Name Summary

add

This operation is used to import a template from external hypervisor.

add POST

This operation is used to import a template from external hypervisor.

For example import of a template OVA can be facilitated using the following request:

POST /externaltemplateimports

With request body of type ExternalTemplateImport, for example:

<external_template_import>
  <template>
    <name>my_template</name>
  </template>
  <cluster id="2b18aca2-4469-11eb-9449-482ae35a5f83" />
  <storage_domain id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
  <url>ova:///mnt/ova/ova_template.ova</url>
  <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
</external_template_import>
Table 263. Parameters summary
Name Type Direction Summary

import

ExternalTemplateImport

In/Out

ExternalVmImports

Provides capability to import external virtual machines.

Table 264. Methods summary
Name Summary

add

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

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

import

ExternalVmImport

In/Out

FenceAgent

A service to manage fence agent for a specific host.

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

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

remove DELETE

Removes a fence agent for a specific host.

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update a fencing-agent.

Table 269. Parameters summary
Name Type Direction Summary

agent

Agent

In/Out

Fence agent details.

async

Boolean

In

Indicates if the update should be performed asynchronously.

FenceAgents

A service to manage fence agents for a specific host.

Table 270. Methods summary
Name Summary

add

Add a new fencing-agent to the host.

list

Returns the list of fencing agents configured for the host.

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

agent

Agent

In/Out

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

File

Table 273. Methods summary
Name Summary

get

get GET

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

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

list

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

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

Filter

Table 277. Methods summary
Name Summary

get

remove

get GET

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

remove DELETE

Table 279. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

Filters

Manages the filters used by an scheduling policy.

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

add POST

Add a filter to a specified user defined scheduling policy.

Table 281. Parameters summary
Name Type Direction Summary

filter

Filter

In/Out

list GET

Returns the list of filters used by the scheduling policy.

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

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

Follow

GlusterBrick

This service manages a single gluster brick.

Table 283. Methods summary
Name Summary

get

Get details of a brick.

remove

Removes a brick.

replace

Replaces this brick with a new one.

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

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the replacement should be performed asynchronously.

force

Boolean

In

GlusterBricks

This service manages the gluster bricks in a gluster volume

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

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

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

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

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

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

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

GlusterHook

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

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

get GET

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

remove DELETE

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

Table 298. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

host

Host

In

resolution_type

String

In

GlusterHooks

Table 300. Methods summary
Name Summary

list

Returns the list of hooks.

list GET

Returns the list of hooks.

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

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

GlusterVolume

This service manages a single gluster volume.

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

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

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

details

GlusterVolumeProfileDetails

Out

Gluster volume profiling information returned from the action.

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

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the reset should be performed asynchronously.

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

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

option

Option

In

Option to set.

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

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

stoprebalance POST

Stop rebalancing the gluster volume.

For example, to stop rebalancing a gluster volume with identifier 123 in cluster 456, send a request like this:

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

GlusterVolumes

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

Table 315. Methods summary
Name Summary

add

Creates a new gluster volume.

list

Lists all gluster volumes in the cluster.

add POST

Creates a new gluster volume.

The volume is created based on properties of the volume parameter. The properties name, volume_type and bricks are required.

For example, to add a volume with name myvolume to the cluster 123, send the following request:

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

With the following request body:

<gluster_volume>
  <name>myvolume</name>
  <volume_type>replicate</volume_type>
  <replica_count>3</replica_count>
  <bricks>
    <brick>
      <server_id>server1</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
    <brick>
      <server_id>server2</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
    <brick>
      <server_id>server3</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
  <bricks>
</gluster_volume>
Table 316. Parameters summary
Name Type Direction Summary

volume

GlusterVolume

In/Out

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

list GET

Lists all gluster volumes in the cluster.

For example, to list all Gluster Volumes in cluster 456, send a request like this:

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

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

Table 317. 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 volumes to return.

search

String

In

A query string used to restrict the returned volumes.

volumes

GlusterVolume[]

Out

case_sensitive

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

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 volumes to return. If not specified all the volumes are returned.

Group

Manages a group of users. Use this service to either get groups details or remove groups. In order to add new groups please use service that manages the collection of groups.

Table 318. Methods summary
Name Summary

get

Gets the system group information.

remove

Removes the system group.

get GET

Gets the system group information.

Usage:

GET /ovirt-engine/api/groups/123

Will return the group information:

<group href="/ovirt-engine/api/groups/123" id="123">
  <name>mygroup</name>
  <link href="/ovirt-engine/api/groups/123/roles" rel="roles"/>
  <link href="/ovirt-engine/api/groups/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/groups/123/tags" rel="tags"/>
  <domain_entry_id>476652557A382F67696B6D2B32762B37796E46476D513D3D</domain_entry_id>
  <namespace>DC=example,DC=com</namespace>
  <domain href="/ovirt-engine/api/domains/ABCDEF" id="ABCDEF">
    <name>myextension-authz</name>
  </domain>
</group>
Table 319. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

get

Group

Out

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

remove DELETE

Removes the system group.

Usage:

DELETE /ovirt-engine/api/groups/123
Table 320. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

Groups

Manages the collection of groups of users.

Table 321. Methods summary
Name Summary

add

Add group from a directory service.

list

List all the groups in the system.

add POST

Add group from a directory service. Please note that domain name is name of the authorization provider.

For example, to add the Developers group from the internal-authz authorization provider send a request like this:

POST /ovirt-engine/api/groups

With a request body like this:

<group>
  <name>Developers</name>
  <domain>
    <name>internal-authz</name>
  </domain>
</group>
Table 322. Parameters summary
Name Type Direction Summary

group

Group

In/Out

The group to be added.

list GET

List all the groups in the system.

Usage:

GET /ovirt-engine/api/groups

Will return the list of groups:

<groups>
  <group href="/ovirt-engine/api/groups/123" id="123">
    <name>mygroup</name>
    <link href="/ovirt-engine/api/groups/123/roles" rel="roles"/>
    <link href="/ovirt-engine/api/groups/123/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/groups/123/tags" rel="tags"/>
    <domain_entry_id>476652557A382F67696B6D2B32762B37796E46476D513D3D</domain_entry_id>
    <namespace>DC=example,DC=com</namespace>
    <domain href="/ovirt-engine/api/domains/ABCDEF" id="ABCDEF">
      <name>myextension-authz</name>
    </domain>
  </group>
  ...
</groups>

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

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

The list of groups.

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.

Host

A service to manage a host.

Table 324. Methods summary
Name Summary

activate

Activates the host for use, for example to run virtual machines.

approve

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

commitnetconfig

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

copyhostnetworks

Copy the network configuration of the specified host to current host.

deactivate

Deactivates the host to perform maintenance tasks.

discoveriscsi

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

enrollcertificate

Enrolls the certificate of the host.

fence

Controls the host’s power management device.

forceselectspm

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

get

Gets the host details.

install

Installs the latest version of VDSM and related software on the host.

iscsidiscover

This method has been deprecated since Engine version 4.

iscsilogin

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

refresh

Refresh the host devices and capabilities.

remove

Remove the host from the system.

setupnetworks

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

syncallnetworks

To synchronize all networks on the host, send a request like this:

[source] ---- POST /ovirt-engine/api/hosts/123/syncallnetworks ----

With a request body like this:

[source,xml] ---- <action/> ----

unregisteredstoragedomainsdiscover

Discovers the block Storage Domains which are candidates to be imported to the setup.

update

Update the host properties.

upgrade

Upgrades VDSM and selected software on the host.

upgradecheck

Check if there are upgrades available for the host.

activate POST

Activates the host for use, for example to run virtual machines.

Table 325. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

approve POST

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

This action also accepts an optional cluster element to define the target cluster for this host.

Table 326. Parameters summary
Name Type Direction Summary

activate

Boolean

In

When set to 'true', this host will be activated after its approval completes.

async

Boolean

In

Indicates if the approval should be performed asynchronously.

cluster

Cluster

In

The cluster where the host will be added after it is approved.

host

Host

In

The host to approve.

reboot

Boolean

In

Indicates if the host should be rebooted after successful installation.

activate

When set to 'true', this host will be activated after its approval completes. When set to 'false' the host will remain in 'maintenance' status after its approval. Absence of this parameter will be interpreted as 'true', since the desired default behavior is activating the host after approval.

reboot

Indicates if the host should be rebooted after successful installation. The default value is true.

commitnetconfig POST

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

An API user commits the network configuration to persist a host network interface attachment or detachment, or persist the creation and deletion of a bonded interface.

Networking configuration is only committed after the engine has established that host connectivity is not lost as a result of the configuration changes. If host connectivity is lost, the host requires a reboot and automatically reverts to the previous networking configuration.

For example, to commit the network configuration of host with id 123 send a request like this:

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

With a request body like this:

<action/>
Since {engine-name} 4.3, it is possible to also specify commit_on_success in the setupnetworks request, in which case the new configuration is automatically saved in the {hypervisor-name} upon completing the setup and re-establishing connectivity between the {hypervisor-name} and {engine-name}, and without waiting for a separate commitnetconfig request.
Table 327. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

copyhostnetworks POST

Copy the network configuration of the specified host to current host.

Any network attachments that are not present on the source host will be erased from the target host by the copy operation.

To copy networks from another host, send a request like this:

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

With a request body like this:

<action>
   <source_host id="456"/>
</action>
Table 328. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

source_host

Host

In

The host to copy networks from.

deactivate POST

Deactivates the host to perform maintenance tasks.

Table 329. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

reason

String

In

stop_gluster_service

Boolean

In

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

stop_gluster_service

Indicates if the gluster service should be stopped as part of deactivating the host. It can be used while performing maintenance operations on the gluster host. Default value for this variable is false.

discoveriscsi POST

Discovers iSCSI targets on the host, using the initiator details. Returns a list of IscsiDetails objects containing the discovered data.

For example, to discover iSCSI targets available in myiscsi.example.com, from host 123, send a request like this:

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

With a request body like this:

<action>
  <iscsi>
    <address>myiscsi.example.com</address>
  </iscsi>
</action>

The result will be like this:

<discovered_targets>
  <iscsi_details>
    <address>10.35.1.72</address>
    <port>3260</port>
    <portal>10.35.1.72:3260,1</portal>
    <target>iqn.2015-08.com.tgt:444</target>
  </iscsi_details>
</discovered_targets>
When using this method to discover iscsi targets, you can use an FQDN or an IP address, but you must use the iscsi details from the discovered targets results to log in using the iscsilogin method.
Table 330. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the discovery should be performed asynchronously.

discovered_targets

IscsiDetails[]

Out

The discovered targets including all connection information.

iscsi

IscsiDetails

In

The target iSCSI device.

enrollcertificate POST

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

Table 331. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the enrollment should be performed asynchronously.

fence POST

Controls the host’s power management device.

For example, to start the host. This can be done via:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
  <fence_type>start</fence_type>
</action>
' \
"${url}/hosts/123/fence"
Table 332. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the fencing should be performed asynchronously.

fence_type

String

In

maintenance_after_restart

Boolean

In

Indicates if host should be put into maintenance after restart.

power_management

PowerManagement

Out

forceselectspm POST

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

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

With a request body like this:

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

get GET

Gets the host details.

GET /ovirt-engine/api/hosts/123
Table 334. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

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

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.

host

Host

Out

The queried host.

all_content

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

By default the following attributes are excluded:

  • hosted_engine

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

GET /ovirt-engine/api/hosts/123?all_content=true
These attributes are not included by default because retrieving them impacts performance. They are seldom used and require additional queries to the database. Use this parameter with caution and only when specifically required.

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.

install POST

Installs the latest version of VDSM and related software on the host.

The action also performs every configuration steps on the host which is done during adding host to the engine: kdump configuration, hosted-engine deploy, kernel options changes, etc.

The host type defines additional parameters for the action.

Example of installing a host, using curl and JSON, plain:

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--request PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Version: 4" \
--user "admin@internal:..." \
--data '
{
  "root_password": "myrootpassword"
}
' \
"https://engine.example.com/ovirt-engine/api/hosts/123"

Example of installing a host using curl and JSON with hosted engine components:

curl \
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--request PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Version: 4" \
--user "admin@internal:..." \
--data '
{
  "root_password": "myrootpassword"
"deploy_hosted_engine" : "true"
}
' \
"https://engine.example.com/ovirt-engine/api/hosts/123"
Since version 4.1.2 of the engine, when a host is reinstalled we override the host firewall definitions by default.
Table 335. Parameters summary
Name Type Direction Summary

activate

Boolean

In

When set to 'true', this host will be activated after its installation completes.

async

Boolean

In

Indicates if the installation should be performed asynchronously.

deploy_hosted_engine

Boolean

In

When set to true this host will also deploy the self-hosted engine components.

host

Host

In

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

image

String

In

When installing {hypervisor-name}, an ISO image file is required.

reboot

Boolean

In

Indicates if the host should be rebooted after successful installation.

root_password

String

In

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

ssh

Ssh

In

The SSH details used to connect to the host.

undeploy_hosted_engine

Boolean

In

When set to true this host will un-deploy the self-hosted engine components, and this host will not function as part of the High Availability cluster.

activate

When set to 'true', this host will be activated after its installation completes. When set to 'false' the host will remain in 'maintenance' status after its installation. Absence of this parameter will be interpreted as 'true', since the desired default behavior is activating the host after install.

deploy_hosted_engine

When set to true this host will also deploy the self-hosted engine components. A missing value is treated as true i.e deploy. Omitting this parameter means false and will not perform any operation in the self-hosted engine area.

reboot

Indicates if the host should be rebooted after successful installation. The default value is true.

undeploy_hosted_engine

When set to true this host will un-deploy the self-hosted engine components, and this host will not function as part of the High Availability cluster. A missing value is treated as true i.e un-deploy. Omitting this parameter means false and will not perform any operation in the self-hosted engine area.

iscsidiscover POST

This method has been deprecated since Engine version 4.4.6. DiscoverIscsi should be used instead.

Discovers iSCSI targets on the host, using the initiator details. Returns an array of strings containing the discovered data.

For example, to discover iSCSI targets available in myiscsi.example.com, from host 123, send a request like this:

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

With a request body like this:

<action>
  <iscsi>
    <address>myiscsi.example.com</address>
  </iscsi>
</action>
Table 336. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the discovery should be performed asynchronously.

iscsi

IscsiDetails

In

The target iSCSI device.

iscsi_targets

String[]

Out

The iSCSI targets.

iscsi_targets

The iSCSI targets. *

iscsilogin POST

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

When using this method to log in, you must use the iscsi details from the discovered targets results in the discoveriscsi method.
Table 337. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the login should be performed asynchronously.

iscsi

IscsiDetails

In

The target iSCSI device.

refresh POST

Refresh the host devices and capabilities.

Table 338. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the refresh should be performed asynchronously.

remove DELETE

Remove the host from the system.

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request DELETE \
--header "Version: 4" \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc"
Table 339. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

force

Boolean

In

Indicates that the host should be removed even if it is non-responsive, or if it is part of a Gluster Storage cluster and has volume bricks on it.

setupnetworks POST

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

For example, if you have a host with three network interfaces eth0, eth1 and eth2 and you want to configure a new bond using eth0 and eth1, and put a VLAN on top of it. Using a simple shell script and the curl command line HTTP client that can be done as follows:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
  <modified_bonds>
    <host_nic>
      <name>bond0</name>
      <bonding>
        <options>
          <option>
            <name>mode</name>
            <value>4</value>
          </option>
          <option>
            <name>miimon</name>
            <value>100</value>
          </option>
        </options>
        <slaves>
          <host_nic>
            <name>eth1</name>
          </host_nic>
          <host_nic>
            <name>eth2</name>
          </host_nic>
        </slaves>
      </bonding>
    </host_nic>
  </modified_bonds>
  <modified_network_attachments>
    <network_attachment>
      <network>
        <name>myvlan</name>
      </network>
      <host_nic>
        <name>bond0</name>
      </host_nic>
      <ip_address_assignments>
        <ip_address_assignment>
          <assignment_method>static</assignment_method>
          <ip>
            <address>192.168.122.10</address>
            <netmask>255.255.255.0</netmask>
          </ip>
        </ip_address_assignment>
      </ip_address_assignments>
      <dns_resolver_configuration>
        <name_servers>
          <name_server>1.1.1.1</name_server>
          <name_server>2.2.2.2</name_server>
        </name_servers>
      </dns_resolver_configuration>
    </network_attachment>
  </modified_network_attachments>
 </action>
' \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc/setupnetworks"
This is valid for version 4 of the API. In previous versions some elements were represented as XML attributes instead of XML elements. In particular the options and ip elements were represented as follows: 
<options name="mode" value="4"/>
<options name="miimon" value="100"/>
<ip address="192.168.122.10" netmask="255.255.255.0"/>

The same thing can be done using the Python SDK with the following code:

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

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

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

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

# After modifying the network configuration it is very important to make it
# persistent:
host_service.commit_net_config()
To make sure that the network configuration has been saved in the host, and that it will be applied when the host is rebooted, remember to call commitnetconfig.
Since {engine-name} 4.3, it is possible to also specify commit_on_success in the setupnetworks request, in which case the new configuration is automatically saved in the {hypervisor-name} upon completing the setup and re-establishing connectivity between the {hypervisor-name} and {engine-name}, and without waiting for a separate commitnetconfig request.
Table 340. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

check_connectivity

Boolean

In

commit_on_success

Boolean

In

Specifies whether to automatically save the configuration in the {hypervisor-name} upon completing the setup and re-establishing connectivity between the {hypervisor-name} and {engine-name}, and without waiting for a separate commitnetconfig request.

connectivity_timeout

Integer

In

modified_bonds

HostNic[]

In

modified_labels

NetworkLabel[]

In

modified_network_attachments

NetworkAttachment[]

In

removed_bonds

HostNic[]

In

removed_labels

NetworkLabel[]

In

removed_network_attachments

NetworkAttachment[]

In

synchronized_network_attachments

NetworkAttachment[]

In

A list of network attachments that will be synchronized.

commit_on_success

Specifies whether to automatically save the configuration in the {hypervisor-name} upon completing the setup and re-establishing connectivity between the {hypervisor-name} and {engine-name}, and without waiting for a separate commitnetconfig request. The default value is false, which means that the configuration will not be saved automatically.

syncallnetworks POST

To synchronize all networks on the host, send a request like this:

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

With a request body like this:

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

unregisteredstoragedomainsdiscover POST

Discovers the block Storage Domains which are candidates to be imported to the setup. For FCP no arguments are required.

Table 342. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the discovery should be performed asynchronously.

iscsi

IscsiDetails

In

storage_domains

StorageDomain[]

Out

update PUT

Update the host properties.

For example, to update a the kernel command line of a host send a request like this:

PUT /ovirt-engine/api/hosts/123

With request body like this:

<host>
  <os>
    <custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline>
  </os>
</host>
Table 343. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

host

Host

In/Out

upgrade POST

Upgrades VDSM and selected software on the host.

Table 344. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the upgrade should be performed asynchronously.

image

String

In

This property is no longer relevant, since Vintage Node is no longer supported, and has been deprecated.

reboot

Boolean

In

Indicates if the host should be rebooted after the upgrade.

timeout

Integer

In

Upgrade timeout.

reboot

Indicates if the host should be rebooted after the upgrade. By default the host is rebooted.

This parameter is ignored for {hypervisor-name}, which is always rebooted after the upgrade.

timeout

Upgrade timeout.

The maximum time to wait for upgrade to finish in minutes. Default value is specified by ANSIBLE_PLAYBOOK_EXEC_DEFAULT_TIMEOUT configration option.

upgradecheck POST

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

HostCpuUnits

Table 345. Methods summary
Name Summary

list

Returns the List of all host’s CPUs with detailed information about the topology (socket, core) and with information about the current CPU pinning.

list GET

Returns the List of all host’s CPUs with detailed information about the topology (socket, core) and with information about the current CPU pinning.

Table 346. Parameters summary
Name Type Direction Summary

cpu_units

HostCpuUnit[]

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.

HostDevice

A service to access a particular device of a host.

Table 347. Methods summary
Name Summary

get

Retrieve information about a particular host’s device.

get GET

Retrieve information about a particular host’s device.

An example of getting a host device:

GET /ovirt-engine/api/hosts/123/devices/456
<host_device href="/ovirt-engine/api/hosts/123/devices/456" id="456">
  <name>usb_1_9_1_1_0</name>
  <capability>usb</capability>
  <host href="/ovirt-engine/api/hosts/123" id="123"/>
  <parent_device href="/ovirt-engine/api/hosts/123/devices/789" id="789">
    <name>usb_1_9_1</name>
  </parent_device>
</host_device>
Table 348. Parameters summary
Name Type Direction Summary

device

HostDevice

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.

HostDevices

A service to access host devices.

Table 349. Methods summary
Name Summary

list

List the devices of a host.

list GET

List the devices of a host.

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

Table 350. Parameters summary
Name Type Direction Summary

devices

HostDevice[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of devices 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 devices to return. If not specified all the devices are returned.

HostHook

Table 351. Methods summary
Name Summary

get

get GET

Table 352. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

hook

Hook

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.

HostHooks

Table 353. Methods summary
Name Summary

list

Returns the list of hooks configured for the host.

list GET

Returns the list of hooks configured for the host.

The order of the returned list of hooks is random.

Table 354. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

hooks

Hook[]

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.

HostNic

A service to manage a network interface of a host.

Table 355. Methods summary
Name Summary

get

updatevirtualfunctionsconfiguration

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

get GET

Table 356. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

Indicates if all of the attributes of the host network interface should be included in the response.

follow

String

In

Indicates which inner links should be followed.

nic

HostNic

Out

all_content

Indicates if all of the attributes of the host network interface should be included in the response.

By default the following attributes are excluded:

  • virtual_functions_configuration

For example, to retrieve the complete representation network interface '456' of host '123':

GET /ovirt-engine/api/hosts/123/nics/456?all_content=true
These attributes are not included by default because retrieving them impacts performance. They are seldom used and require additional queries to the database. Use this parameter with caution and only when specifically required.

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.

updatevirtualfunctionsconfiguration POST

The action updates virtual function configuration in case the current resource represents an SR-IOV enabled NIC. The input should be consisted of at least one of the following properties:

  • allNetworksAllowed

  • numberOfVirtualFunctions

Please see the HostNicVirtualFunctionsConfiguration type for the meaning of the properties.

Table 357. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

In

HostNics

A service to manage the network interfaces of a host.

Table 358. Methods summary
Name Summary

list

Returns the list of network interfaces of the host.

list GET

Returns the list of network interfaces of the host.

The order of the returned list of network interfaces isn’t guaranteed.

Table 359. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

Indicates if all of the attributes of the host network interface should be included in the response.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of NICs to return.

nics

HostNic[]

Out

all_content

Indicates if all of the attributes of the host network interface should be included in the response.

By default the following attributes are excluded:

  • virtual_functions_configuration

For example, to retrieve the complete representation of network interface '456' of host '123':

GET /ovirt-engine/api/hosts/123/nics?all_content=true
These attributes are not included by default because retrieving them impacts performance. They are seldom used and require additional queries to the database. Use this parameter with caution and only when specifically required.

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 NICs to return. If not specified all the NICs are returned.

HostNumaNode

Table 360. Methods summary
Name Summary

get

get GET

Table 361. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

node

NumaNode

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.

HostNumaNodes

Table 362. Methods summary
Name Summary

list

Returns the list of NUMA nodes of the host.

list GET

Returns the list of NUMA nodes of the host.

The order of the returned list of NUMA nodes isn’t guaranteed.

Table 363. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of nodes to return.

nodes

NumaNode[]

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 nodes to return. If not specified all the nodes are returned.

HostStorage

A service to manage host storages.

Table 364. Methods summary
Name Summary

list

Get list of storages.

list GET

Get list of storages.

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

The XML response you get will be like this one:

<host_storages>
  <host_storage id="123">
    ...
  </host_storage>
  ...
</host_storages>

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

Table 365. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

report_status

Boolean

In

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

storages

HostStorage[]

Out

Retrieved list of storages.

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.

report_status

Indicates if the status of the LUNs in the storage should be checked. Checking the status of the LUN is an heavy weight operation and this data is not always needed by the user. This parameter will give the option to not perform the status check of the LUNs.

The default is true for backward compatibility.

Here an example with the LUN status :

<host_storage id="123">
  <logical_units>
    <logical_unit id="123">
      <lun_mapping>0</lun_mapping>
      <paths>1</paths>
      <product_id>lun0</product_id>
      <serial>123</serial>
      <size>10737418240</size>
      <status>used</status>
      <vendor_id>LIO-ORG</vendor_id>
      <volume_group_id>123</volume_group_id>
    </logical_unit>
  </logical_units>
  <type>iscsi</type>
  <host id="123"/>
</host_storage>

Here an example without the LUN status :

<host_storage id="123">
  <logical_units>
    <logical_unit id="123">
      <lun_mapping>0</lun_mapping>
      <paths>1</paths>
      <product_id>lun0</product_id>
      <serial>123</serial>
      <size>10737418240</size>
      <vendor_id>LIO-ORG</vendor_id>
      <volume_group_id>123</volume_group_id>
    </logical_unit>
  </logical_units>
  <type>iscsi</type>
  <host id="123"/>
</host_storage>

Hosts

A service that manages hosts.

Table 366. Methods summary
Name Summary

add

Creates a new host.

list

Get a list of all available hosts.

add POST

Creates a new host.

The host is created based on the attributes of the host parameter. The name, address, and root_password properties are required.

For example, to add a host, send the following request:

POST /ovirt-engine/api/hosts

With the following request body:

<host>
  <name>myhost</name>
  <address>myhost.example.com</address>
  <root_password>myrootpassword</root_password>
</host>
The root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent requests.
Since version 4.1.2 of the engine, when a host is newly added, the host’s firewall definitions are overridden by default.

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

POST /ovirt-engine/api/hosts?deploy_hosted_engine=true

If the cluster has a default external network provider that is supported for automatic deployment, the external network provider is deployed when adding the host. Only external network providers for OVN are supported for the automatic deployment. To deploy an external network provider other than the one defined in the clusters, overwrite the external network provider when adding hosts, by sending the following request:

POST /ovirt-engine/api/hosts

With a request body that contains a reference to the desired provider in the external_network_provider_configuration:

<host>
  <name>myhost</name>
  <address>myhost.example.com</address>
  <root_password>123456</root_password>
  <external_network_provider_configurations>
    <external_network_provider_configuration>
      <external_network_provider name="ovirt-provider-ovn"/>
    </external_network_provider_configuration>
  </external_network_provider_configurations>
</host>
Table 367. Parameters summary
Name Type Direction Summary

activate

Boolean

In

When set to true, this host will be activated after its installation completes.

deploy_hosted_engine

Boolean

In

When set to true, this host deploys the hosted engine components.

host

Host

In/Out

The host definition with which the new host is created is passed as a parameter, and the newly created host is returned.

reboot

Boolean

In

Indicates if the host should be rebooted after successful installation.

undeploy_hosted_engine

Boolean

In

When set to true, this host un-deploys the hosted engine components and does not function as part of the High Availability cluster.

activate

When set to true, this host will be activated after its installation completes. When set to false the host will remain in maintenance status after its installation. Absence of this parameter will be interpreted as true, since the desired default behavior is activating the host after install.

deploy_hosted_engine

When set to true, this host deploys the hosted engine components. A missing value is treated as true, i.e., deploy the hosted engine components. Omitting this parameter equals false, and the host performs no operation in the hosted engine area.

reboot

Indicates if the host should be rebooted after successful installation. The default value is true.

undeploy_hosted_engine

When set to true, this host un-deploys the hosted engine components and does not function as part of the High Availability cluster. A missing value is treated as true, i.e., un-deploy. Omitting this parameter equals false and the host performs no operation in the hosted engine area.

list GET

Get a list of all available hosts.

For example, to list the hosts send the following request:

GET /ovirt-engine/api/hosts

The response body will be similar to this:

<hosts>
  <host href="/ovirt-engine/api/hosts/123" id="123">
    ...
  </host>
  <host href="/ovirt-engine/api/hosts/456" id="456">
    ...
  </host>
  ...
</host>

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

Table 368. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

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

case_sensitive

Boolean

In

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

check_vms_in_affinity_closure

Boolean

In

This parameter can be used with migration_target_of to get valid migration targets for the listed virtual machines and all other virtual machines that are in positive enforcing affinity with the listed virtual machines.

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.

hosts

Host[]

Out

max

Integer

In

Sets the maximum number of hosts to return.

migration_target_of

String

In

Accepts a comma-separated list of virtual machine IDs and returns the hosts that these virtual machines can be migrated to.

search

String

In

A query string used to restrict the returned hosts.

all_content

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

By default the following host attributes are excluded:

  • hosted_engine

For example, to retrieve the complete representation of the hosts:

GET /ovirt-engine/api/hosts?all_content=true
These attributes are not included by default because retrieving them impacts performance. They are seldom used and require additional queries to the database. Use this parameter with caution and only when specifically required.

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.

check_vms_in_affinity_closure

This parameter can be used with migration_target_of to get valid migration targets for the listed virtual machines and all other virtual machines that are in positive enforcing affinity with the listed virtual machines.

This is useful in case the virtual machines will be migrated together with others in positive affinity groups.

The default value is false.

GET /ovirt-engine/api/hosts?migration_target_of=123,456&check_vms_in_affinity_closure=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 hosts to return. If not specified all the hosts are returned.

migration_target_of

Accepts a comma-separated list of virtual machine IDs and returns the hosts that these virtual machines can be migrated to.

For example, to retrieve the list of hosts to which the virtual machine with ID 123 and the virtual machine with ID 456 can be migrated to, send the following request:

GET /ovirt-engine/api/hosts?migration_target_of=123,456

Icon

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

Table 369. Methods summary
Name Summary

get

Get an icon.

get GET

Get an icon.

GET /ovirt-engine/api/icons/123

You will get a XML response like this one:

<icon id="123">
  <data>Some binary data here</data>
  <media_type>image/png</media_type>
</icon>
Table 370. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

icon

Icon

Out

Retrieved icon.

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.

Icons

A service to manage icons.

Table 371. Methods summary
Name Summary

list

Get a list of icons.

list GET

Get a list of icons.

GET /ovirt-engine/api/icons

You will get a XML response which is similar to this one:

<icons>
  <icon id="123">
    <data>...</data>
    <media_type>image/png</media_type>
  </icon>
  ...
</icons>

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

Table 372. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

icons

Icon[]

Out

Retrieved list of icons.

max

Integer

In

Sets the maximum number of icons 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 icons to return. If not specified all the icons are returned.

Image

Table 373. Methods summary
Name Summary

get

import

Imports an image.

get GET

Table 374. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

image

Image

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.

import POST

Imports an image.

If the import_as_template parameter is true then the image will be imported as a template, otherwise it will be imported as a disk.

When imported as a template, the name of the template can be specified by the optional template.name parameter. If that parameter is not specified, then the name of the template will be automatically assigned by the engine as GlanceTemplate-x (where x will be seven random hexadecimal characters).

When imported as a disk, the name of the disk can be specified by the optional disk.name parameter. If that parameter is not specified, then the name of the disk will be automatically assigned by the engine as GlanceDisk-x (where x will be the seven hexadecimal characters of the image identifier).

It is recommended to always explicitly specify the template or disk name, to avoid these automatic names generated by the engine.

Table 375. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the import should be performed asynchronously.

cluster

Cluster

In

The cluster to which the image should be imported if the import_as_template parameter is set to true.

disk

Disk

In

The disk to import.

import_as_template

Boolean

In

Specifies if a template should be created from the imported disk.

storage_domain

StorageDomain

In

The storage domain to which the disk should be imported.

template

Template

In

The name of the template being created if the import_as_template parameter is set to true.

ImageTransfer

This service provides a mechanism to control an image transfer. The client will have to create a transfer by using add of the image transfers service, stating the image to transfer data to/from.

After doing that, the transfer is managed by this service.

Using oVirt’s Python’s SDK:

Uploading a disk with id 123 (on a random host in the data center):

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
   types.ImageTransfer(
      disk=types.Disk(
         id='123'
      )
   )
)

Uploading a disk with id 123 on host id 456:

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
   types.ImageTransfer(
      disk=types.Disk(
         id='123'
      ),
      host=types.Host(
         id='456'
     )
   )
)

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

E.g:

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
   types.ImageTransfer(
      disk=types.Disk(
         id='123'
      ),
      direction=types.ImageTransferDirection.DOWNLOAD
   )
)

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

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

For example:

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

At that stage, if the phase of the transfer is paused_system, the session was not successfully established. This can happen if ovirt-imageio is not running in the selected host.

Table 376. Methods summary
Name Summary

cancel

Cancel the image transfer session.

extend

Extend the image transfer session.

finalize

After finishing to transfer the data, finalize the transfer.

get

Get the image transfer entity.

pause

Pause the image transfer session.

resume

Resume the image transfer session.

cancel POST

Cancel the image transfer session. This terminates the transfer operation and removes the partial image.

extend POST

Extend the image transfer session.

finalize POST

After finishing to transfer the data, finalize the transfer.

This will make sure that the data being transferred is valid and fits the image entity that was targeted in the transfer. Specifically, will verify that if the image entity is a QCOW disk, the data uploaded is indeed a QCOW file, and that the image doesn’t have a backing file.

get GET

Get the image transfer entity.

Table 377. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

image_transfer

ImageTransfer

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.

pause POST

Pause the image transfer session.

resume POST

Resume the image transfer session. The client will need to poll the transfer’s phase until it is different than resuming. For example:

transfer_service = transfers_service.image_transfer_service(transfer.id)
transfer_service.resume()
transfer = transfer_service.get()

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

ImageTransfers

This service manages image transfers, for performing Image I/O API in {product-name}. Please refer to image transfer for further documentation.

Table 378. Methods summary
Name Summary

add

Add a new image transfer.

list

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

add POST

Add a new image transfer. An image, disk or disk snapshot needs to be specified in order to make a new transfer.

The image attribute is deprecated since version 4.2 of the engine. Use the disk or snapshot attributes instead.

Creating a new image transfer for downloading or uploading a disk:

To create an image transfer to download or upload a disk with id 123, send the following request:

POST /ovirt-engine/api/imagetransfers

With a request body like this:

<image_transfer>
  <disk id="123"/>
  <direction>upload|download</direction>
</image_transfer>

Creating a new image transfer for downloading or uploading a disk_snapshot:

To create an image transfer to download or upload a disk_snapshot with id 456, send the following request:

POST /ovirt-engine/api/imagetransfers

With a request body like this:

<image_transfer>
  <snapshot id="456"/>
  <direction>download|upload</direction>
</image_transfer>
Table 379. Parameters summary
Name Type Direction Summary

image_transfer

ImageTransfer

In/Out

The image transfer to add.

list GET

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

The order of the returned list of image transfers is not guaranteed.

Table 380. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

image_transfer

ImageTransfer[]

Out

A list of image transfers that are currently being performed.

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.

Images

Manages the set of images available in an storage domain or in an OpenStack image provider.

Table 381. Methods summary
Name Summary

list

Returns the list of images available in the storage domain or provider.

list GET

Returns the list of images available in the storage domain or provider.

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

Table 382. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

images

Image[]

Out

max

Integer

In

Sets the maximum number of images 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 images to return. If not specified all the images are returned.

InstanceType

Table 383. Methods summary
Name Summary

get

Get a specific instance type and it’s attributes.

remove

Removes a specific instance type from the system.

update

Update a specific instance type and it’s attributes.

get GET

Get a specific instance type and it’s attributes.

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

follow

String

In

Indicates which inner links should be followed.

instance_type

InstanceType

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.

remove DELETE

Removes a specific instance type from the system.

If a virtual machine was created using an instance type X after removal of the instance type the virtual machine’s instance type will be set to custom.

DELETE /ovirt-engine/api/instancetypes/123
Table 385. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update a specific instance type and it’s attributes.

All the attributes are editable after creation. If a virtual machine was created using an instance type X and some configuration in instance type X was updated, the virtual machine’s configuration will be updated automatically by the engine.

PUT /ovirt-engine/api/instancetypes/123

For example, to update the memory of instance type 123 to 1 GiB and set the cpu topology to 2 sockets and 1 core, send a request like this:

<instance_type>
  <memory>1073741824</memory>
  <cpu>
    <topology>
      <cores>1</cores>
      <sockets>2</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
</instance_type>
Table 386. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

instance_type

InstanceType

In/Out

InstanceTypeGraphicsConsole

Table 387. Methods summary
Name Summary

get

Gets graphics console configuration of the instance type.

remove

Remove the graphics console from the instance type.

get GET

Gets graphics console configuration of the instance type.

Table 388. Parameters summary
Name Type Direction Summary

console

GraphicsConsole

Out

The information about the graphics console of the instance type.

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.

remove DELETE

Remove the graphics console from the instance type.

Table 389. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

InstanceTypeGraphicsConsoles

Table 390. Methods summary
Name Summary

add

Add new graphics console to the instance type.

list

Lists all the configured graphics consoles of the instance type.

add POST

Add new graphics console to the instance type.

Table 391. Parameters summary
Name Type Direction Summary

console

GraphicsConsole

In/Out

list GET

Lists all the configured graphics consoles of the instance type.

The order of the returned list of graphics consoles isn’t guaranteed.

Table 392. Parameters summary
Name Type Direction Summary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the instance type.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of consoles 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 consoles to return. If not specified all the consoles are returned.

InstanceTypeNic

Table 393. Methods summary
Name Summary

get

Gets network interface configuration of the instance type.

remove

Remove the network interface from the instance type.

update

Updates the network interface configuration of the instance type.

get GET

Gets network interface configuration of the instance type.

Table 394. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

nic

Nic

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.

remove DELETE

Remove the network interface from the instance type.

Table 395. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates the network interface configuration of the instance type.

Table 396. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

InstanceTypeNics

Table 397. Methods summary
Name Summary

add

Add new network interface to the instance type.

list

Lists all the configured network interface of the instance type.

add POST

Add new network interface to the instance type.

Table 398. Parameters summary
Name Type Direction Summary

nic

Nic

In/Out

list GET

Lists all the configured network interface of the instance type.

The order of the returned list of network interfaces isn’t guaranteed.

Table 399. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

search

String

In

A query string used to restrict the returned templates.

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 NICs to return. If not specified all the NICs are returned.

InstanceTypeWatchdog

Table 400. Methods summary
Name Summary

get

Gets watchdog configuration of the instance type.

remove

Remove a watchdog from the instance type.

update

Updates the watchdog configuration of the instance type.

get GET

Gets watchdog configuration of the instance type.

Table 401. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

watchdog

Watchdog

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.

remove DELETE

Remove a watchdog from the instance type.

Table 402. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates the watchdog configuration of the instance type.

Table 403. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

InstanceTypeWatchdogs

Table 404. Methods summary
Name Summary

add

Add new watchdog to the instance type.

list

Lists all the configured watchdogs of the instance type.

add POST

Add new watchdog to the instance type.

Table 405. Parameters summary
Name Type Direction Summary

watchdog

Watchdog

In/Out

list GET

Lists all the configured watchdogs of the instance type.

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

Table 406. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of watchdogs to return.

search

String

In

A query string used to restrict the returned templates.

watchdogs

Watchdog[]

Out

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 watchdogs to return. If not specified all the watchdogs are returned.

InstanceTypes

Table 407. Methods summary
Name Summary

add

Creates a new instance type.

list

Lists all existing instance types in the system.

add POST

Creates a new instance type.

This requires only a name attribute and can include all hardware configurations of the virtual machine.

POST /ovirt-engine/api/instancetypes

With a request body like this:

<instance_type>
  <name>myinstancetype</name>
</template>

Creating an instance type with all hardware configurations with a request body like this:

<instance_type>
  <name>myinstancetype</name>
  <console>
    <enabled>true</enabled>
  </console>
  <cpu>
    <topology>
      <cores>2</cores>
      <sockets>2</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
  <custom_cpu_model>AMD Opteron_G2</custom_cpu_model>
  <custom_emulated_machine>q35</custom_emulated_machine>
  <display>
    <monitors>1</monitors>
    <single_qxl_pci>true</single_qxl_pci>
    <smartcard_enabled>true</smartcard_enabled>
    <type>spice</type>
  </display>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <io>
    <threads>2</threads>
  </io>
  <memory>4294967296</memory>
  <memory_policy>
    <ballooning>true</ballooning>
    <guaranteed>268435456</guaranteed>
  </memory_policy>
  <migration>
    <auto_converge>inherit</auto_converge>
    <compressed>inherit</compressed>
    <policy id="00000000-0000-0000-0000-000000000000"/>
  </migration>
  <migration_downtime>2</migration_downtime>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
  </os>
  <rng_device>
    <rate>
      <bytes>200</bytes>
      <period>2</period>
    </rate>
    <source>urandom</source>
  </rng_device>
  <soundcard_enabled>true</soundcard_enabled>
  <usb>
    <enabled>true</enabled>
    <type>native</type>
  </usb>
  <virtio_scsi>
    <enabled>true</enabled>
  </virtio_scsi>
</instance_type>
Table 408. Parameters summary
Name Type Direction Summary

instance_type

InstanceType

In/Out

list GET

Lists all existing instance types in the system.

The order of the returned list of instance types isn’t guaranteed.

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

instance_type

InstanceType[]

Out

max

Integer

In

Sets the maximum number of instance types to return.

search

String

In

A query string used to restrict the returned templates.

case_sensitive

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

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 instance types to return. If not specified all the instance types are returned.

IscsiBond

Table 410. Methods summary
Name Summary

get

remove

Removes of an existing iSCSI bond.

update

Updates an iSCSI bond.

get GET

Table 411. Parameters summary
Name Type Direction Summary

bond

IscsiBond

Out

The iSCSI bond.

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.

remove DELETE

Removes of an existing iSCSI bond.

For example, to remove the iSCSI bond 456 send a request like this:

DELETE /ovirt-engine/api/datacenters/123/iscsibonds/456
Table 412. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates an iSCSI bond.

Updating of an iSCSI bond can be done on the name and the description attributes only. For example, to update the iSCSI bond 456 of data center 123, send a request like this:

PUT /ovirt-engine/api/datacenters/123/iscsibonds/1234

The request body should look like this:

<iscsi_bond>
   <name>mybond</name>
   <description>My iSCSI bond</description>
</iscsi_bond>
Table 413. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bond

IscsiBond

In/Out

The iSCSI bond to update.

IscsiBonds

Table 414. Methods summary
Name Summary

add

Create a new iSCSI bond on a data center.

list

Returns the list of iSCSI bonds configured in the data center.

add POST

Create a new iSCSI bond on a data center.

For example, to create a new iSCSI bond on data center 123 using storage connections 456 and 789, send a request like this:

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

The request body should look like this:

<iscsi_bond>
  <name>mybond</name>
  <storage_connections>
    <storage_connection id="456"/>
    <storage_connection id="789"/>
  </storage_connections>
  <networks>
    <network id="abc"/>
  </networks>
</iscsi_bond>
Table 415. Parameters summary
Name Type Direction Summary

bond

IscsiBond

In/Out

list GET

Returns the list of iSCSI bonds configured in the data center.

The order of the returned list of iSCSI bonds isn’t guaranteed.

Table 416. Parameters summary
Name Type Direction Summary

bonds

IscsiBond[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of bonds 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 bonds to return. If not specified all the bonds are returned.

Job

A service to manage a job.

Table 417. Methods summary
Name Summary

clear

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

end

Marks an external job execution as ended.

get

Retrieves a job.

clear POST

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

For example, to set a job with identifier 123 send the following request:

POST /ovirt-engine/api/jobs/clear

With the following request body:

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

async

Boolean

In

Indicates if the action should be performed asynchronously.

end POST

Marks an external job execution as ended.

For example, to terminate a job with identifier 123 send the following request:

POST /ovirt-engine/api/jobs/end

With the following request body:

<action>
  <force>true</force>
  <status>finished</status>
</action>
Table 419. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

Indicates if the job should be forcibly terminated.

succeeded

Boolean

In

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

succeeded

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

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

get GET

Retrieves a job.

GET /ovirt-engine/api/jobs/123

You will receive response in XML like this one:

<job href="/ovirt-engine/api/jobs/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
    <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
  </actions>
  <description>Adding Disk</description>
  <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
  <auto_cleared>true</auto_cleared>
  <end_time>2016-12-12T23:07:29.758+02:00</end_time>
  <external>false</external>
  <last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
  <start_time>2016-12-12T23:07:26.593+02:00</start_time>
  <status>failed</status>
  <owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
Table 420. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

job

Job

Out

Retrieves the representation of the job.

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.

Jobs

A service to manage jobs.

Table 421. Methods summary
Name Summary

add

Add an external job.

list

Retrieves the representation of the jobs.

add POST

Add an external job.

For example, to add a job with the following request:

POST /ovirt-engine/api/jobs

With the following request body:

<job>
  <description>Doing some work</description>
  <auto_cleared>true</auto_cleared>
</job>

The response should look like:

<job href="/ovirt-engine/api/jobs/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
    <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
  </actions>
  <description>Doing some work</description>
  <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
  <auto_cleared>true</auto_cleared>
  <external>true</external>
  <last_updated>2016-12-13T02:15:42.130+02:00</last_updated>
  <start_time>2016-12-13T02:15:42.130+02:00</start_time>
  <status>started</status>
  <owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
Table 422. Parameters summary
Name Type Direction Summary

job

Job

In/Out

Job that will be added.

list GET

Retrieves the representation of the jobs.

GET /ovirt-engine/api/jobs

You will receive response in XML like this one:

<jobs>
  <job href="/ovirt-engine/api/jobs/123" id="123">
    <actions>
      <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
      <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
    </actions>
    <description>Adding Disk</description>
    <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
    <auto_cleared>true</auto_cleared>
    <end_time>2016-12-12T23:07:29.758+02:00</end_time>
    <external>false</external>
    <last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
    <start_time>2016-12-12T23:07:26.593+02:00</start_time>
    <status>failed</status>
    <owner href="/ovirt-engine/api/users/456" id="456"/>
  </job>
  ...
</jobs>

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

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

jobs

Job[]

Out

A representation of jobs.

max

Integer

In

Sets the maximum number of jobs to return.

search

String

In

A query string used to restrict the returned jobs.

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 jobs to return. If not specified all the jobs are returned.

KatelloErrata

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

Table 424. Methods summary
Name Summary

list

Retrieves the representation of the Katello errata.

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

KatelloErratum

A service to manage a Katello erratum.

Table 426. Methods summary
Name Summary

get

Retrieves a Katello erratum.

get GET

Retrieves a Katello erratum.

GET /ovirt-engine/api/katelloerrata/123

You will receive response in XML like this one:

<katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123">
  <name>RHBA-2013:XYZ</name>
  <description>The description of the erratum</description>
  <title>some bug fix update</title>
  <type>bugfix</type>
  <issued>2013-11-20T02:00:00.000+02:00</issued>
  <solution>Few guidelines regarding the solution</solution>
  <summary>Updated packages that fix one bug are now available for XYZ</summary>
  <packages>
    <package>
      <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
    </package>
    ...
  </packages>
</katello_erratum>
Table 427. Parameters summary
Name Type Direction Summary

erratum

KatelloErratum

Out

Retrieves the representation of the Katello erratum.

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.

A service to fetch information elements received by Link Layer Discovery Protocol (LLDP).

Table 428. Methods summary
Name Summary

list

Fetches information elements received by LLDP.

Fetches information elements received by LLDP.

Table 429. Parameters summary
Name Type Direction Summary

elements

LinkLayerDiscoveryProtocolElement[]

Out

Retrieves a list of information elements received by LLDP.

follow

String

In

Indicates which inner links should be followed.

Retrieves a list of information elements received by LLDP.

For example, to retrieve the information elements received on the NIC 321 on host 123, send a request like this:

GET ovirt-engine/api/hosts/123/nics/321/linklayerdiscoveryprotocolelements

It will return a response like this:

<link_layer_discovery_protocol_elements>
    ...
  <link_layer_discovery_protocol_element>
    <name>Port Description</name>
    <properties>
      <property>
        <name>port description</name>
        <value>Summit300-48-Port 1001</value>
      </property>
    </properties>
    <type>4</type>
  </link_layer_discovery_protocol_element>
  ...
<link_layer_discovery_protocol_elements>

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.

MacPool

Table 430. Methods summary
Name Summary

get

remove

Removes a MAC address pool.

update

Updates a MAC address pool.

get GET

Table 431. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

pool

MacPool

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.

remove DELETE

Removes a MAC address pool.

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

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates a MAC address pool.

The name, description, allow_duplicates, and ranges attributes can be updated.

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

PUT /ovirt-engine/api/macpools/123

With a request body like this:

<mac_pool>
  <name>UpdatedMACPool</name>
  <description>An updated MAC address pool</description>
  <allow_duplicates>false</allow_duplicates>
  <ranges>
    <range>
      <from>00:1A:4A:16:01:51</from>
      <to>00:1A:4A:16:01:e6</to>
    </range>
    <range>
      <from>02:1A:4A:01:00:00</from>
      <to>02:1A:4A:FF:FF:FF</to>
    </range>
  </ranges>
</mac_pool>
Table 433. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

pool

MacPool

In/Out

MacPools

Table 434. Methods summary
Name Summary

add

Creates a new MAC address pool.

list

Return the list of MAC address pools of the system.

add POST

Creates a new MAC address pool.

Creation of a MAC address pool requires values for the name and ranges attributes.

For example, to create MAC address pool send a request like this:

POST /ovirt-engine/api/macpools

With a request body like this:

<mac_pool>
  <name>MACPool</name>
  <description>A MAC address pool</description>
  <allow_duplicates>true</allow_duplicates>
  <default_pool>false</default_pool>
  <ranges>
    <range>
      <from>00:1A:4A:16:01:51</from>
      <to>00:1A:4A:16:01:e6</to>
    </range>
  </ranges>
</mac_pool>
Table 435. Parameters summary
Name Type Direction Summary

pool

MacPool

In/Out

list GET

Return the list of MAC address pools of the system.

The returned list of MAC address pools isn’t guaranteed.

Table 436. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of pools to return.

pools

MacPool[]

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 pools to return. If not specified all the pools are returned.

Measurable

Moveable

Table 437. Methods summary
Name Summary

move

move POST

Table 438. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the move should be performed asynchronously.

Network

A service managing a network

Table 439. Methods summary
Name Summary

get

Gets a logical network.

remove

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

update

Updates a logical network.

get GET

Gets a logical network.

For example:

GET /ovirt-engine/api/networks/123

Will respond:

<network href="/ovirt-engine/api/networks/123" id="123">
  <name>ovirtmgmt</name>
  <description>Default Management Network</description>
  <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/>
  <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/>
  <mtu>0</mtu>
  <stp>false</stp>
  <usages>
    <usage>vm</usage>
  </usages>
  <data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
</network>
Table 440. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

network

Network

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.

remove DELETE

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

For example, to remove the logical network 123 send a request like this:

DELETE /ovirt-engine/api/networks/123

Each network is bound exactly to one data center. So if we disassociate network with data center it has the same result as if we would just remove that network. However it might be more specific to say we’re removing network 456 of data center 123.

For example, to remove the association of network 456 to data center 123 send a request like this:

DELETE /ovirt-engine/api/datacenters/123/networks/456
To remove an external logical network, the network has to be removed directly from its provider by OpenStack Networking API. The entity representing the external network inside {product-name} is removed automatically, if auto_sync is enabled for the provider, otherwise the entity has to be removed using this method.
Table 441. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates a logical network.

The name, description, ip, vlan, stp and display attributes can be updated.

For example, to update the description of the logical network 123 send a request like this:

PUT /ovirt-engine/api/networks/123

With a request body like this:

<network>
  <description>My updated description</description>
</network>

The maximum transmission unit of a network is set using a PUT request to specify the integer value of the mtu attribute.

For example, to set the maximum transmission unit send a request like this:

PUT /ovirt-engine/api/datacenters/123/networks/456

With a request body like this:

<network>
  <mtu>1500</mtu>
</network>
Updating external networks is not propagated to the provider.
Table 442. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

network

Network

In/Out

NetworkAttachment

Table 443. Methods summary
Name Summary

get

remove

update

Update the specified network attachment on the host.

get GET

Table 444. Parameters summary
Name Type Direction Summary

attachment

NetworkAttachment

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.

remove DELETE

Table 445. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update the specified network attachment on the host.

Table 446. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

attachment

NetworkAttachment

In/Out

NetworkAttachments

Manages the set of network attachments of a host or host NIC.

Table 447. Methods summary
Name Summary

add

Add a new network attachment to the network interface.

list

Returns the list of network attachments of the host or host NIC.

add POST

Add a new network attachment to the network interface.

Table 448. Parameters summary
Name Type Direction Summary

attachment

NetworkAttachment

In/Out

list GET

Returns the list of network attachments of the host or host NIC.

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

Table 449. Parameters summary
Name Type Direction Summary

attachments

NetworkAttachment[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of attachments 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 attachments to return. If not specified all the attachments are returned.

NetworkFilter

Manages a network filter.

<network_filter id="00000019-0019-0019-0019-00000000026b">
  <name>example-network-filter-b</name>
  <version>
    <major>4</major>
    <minor>0</minor>
    <build>-1</build>
    <revision>-1</revision>
  </version>
</network_filter>

Please note that version is referring to the minimal support version for the specific filter.

Table 450. Methods summary
Name Summary

get

Retrieves a representation of the network filter.

get GET

Retrieves a representation of the network filter.

Table 451. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

network_filter

NetworkFilter

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.

NetworkFilters

Represents a readonly network filters sub-collection.

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

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

A network filter is defined for each vnic profile.

A vnic profile is defined for a specific network.

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

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

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

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

Output:

<network_filters>
  <network_filter id="00000019-0019-0019-0019-00000000026c">
    <name>example-network-filter-a</name>
    <version>
      <major>4</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
  <network_filter id="00000019-0019-0019-0019-00000000026b">
    <name>example-network-filter-b</name>
    <version>
      <major>4</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
  <network_filter id="00000019-0019-0019-0019-00000000026a">
    <name>example-network-filter-a</name>
    <version>
      <major>3</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
</network_filters>
Table 452. Methods summary
Name Summary

list

Retrieves the representations of the network filters.

list GET

Retrieves the representations of the network filters.

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

Table 453. Parameters summary
Name Type Direction Summary

filters

NetworkFilter[]

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.

NetworkLabel

Table 454. Methods summary
Name Summary

get

remove

Removes a label from a logical network.

get GET

Table 455. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

label

NetworkLabel

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.

remove DELETE

Removes a label from a logical network.

For example, to remove the label exemplary from a logical network having id 123 send the following request:

DELETE /ovirt-engine/api/networks/123/networklabels/exemplary
Table 456. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

NetworkLabels

Manages the ser of labels attached to a network or to a host NIC.

Table 457. Methods summary
Name Summary

add

Attaches label to logical network.

list

Returns the list of labels attached to the network or host NIC.

add POST

Attaches label to logical network.

You can attach labels to a logical network to automate the association of that logical network with physical host network interfaces to which the same label has been attached.

For example, to attach the label mylabel to a logical network having id 123 send a request like this:

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

With a request body like this:

<network_label id="mylabel"/>
Table 458. Parameters summary
Name Type Direction Summary

label

NetworkLabel

In/Out

list GET

Returns the list of labels attached to the network or host NIC.

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

Table 459. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

labels

NetworkLabel[]

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.

Networks

Manages logical networks.

The engine creates a default ovirtmgmt network on installation. This network acts as the management network for access to hypervisor hosts. This network is associated with the Default cluster and is a member of the Default data center.

Table 460. Methods summary
Name Summary

add

Creates a new logical network, or associates an existing network with a data center.

list

List logical networks.

add POST

Creates a new logical network, or associates an existing network with a data center.

Creation of a new network requires the name and data_center elements.

For example, to create a network named mynetwork for data center 123 send a request like this:

POST /ovirt-engine/api/networks

With a request body like this:

<network>
  <name>mynetwork</name>
  <data_center id="123"/>
</network>

To associate the existing network 456 with the data center 123 send a request like this:

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

With a request body like this:

<network>
  <name>ovirtmgmt</name>
</network>

To create a network named exnetwork on top of an external OpenStack network provider 456 send a request like this:

POST /ovirt-engine/api/networks
<network>
  <name>exnetwork</name>
  <external_provider id="456"/>
  <data_center id="123"/>
</network>
Table 461. Parameters summary
Name Type Direction Summary

network

Network

In/Out

list GET

List logical networks.

For example:

GET /ovirt-engine/api/networks

Will respond:

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

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

Table 462. 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 networks to return.

networks

Network[]

Out

search

String

In

A query string used to restrict the returned networks.

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 networks to return. If not specified all the networks are returned.

NicNetworkFilterParameter

This service manages a parameter for a network filter.

Table 463. Methods summary
Name Summary

get

Retrieves a representation of the network filter parameter.

remove

Removes the filter parameter.

update

Updates the network filter parameter.

get GET

Retrieves a representation of the network filter parameter.

Table 464. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

parameter

NetworkFilterParameter

Out

The representation of the network filter parameter.

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.

remove DELETE

Removes the filter parameter.

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

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

update PUT

Updates the network filter parameter.

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

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

With a request body like this:

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

parameter

NetworkFilterParameter

In/Out

The network filter parameter that is being updated.

NicNetworkFilterParameters

This service manages a collection of parameters for network filters.

Table 466. Methods summary
Name Summary

add

Add a network filter parameter.

list

Retrieves the representations of the network filter parameters.

add POST

Add a network filter parameter.

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

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

With a request body like this:

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

parameter

NetworkFilterParameter

In/Out

The network filter parameter that is being added.

list GET

Retrieves the representations of the network filter parameters.

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

Table 468. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

parameters

NetworkFilterParameter[]

Out

The list of the network filter parameters.

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.

OpenstackImage

Table 469. Methods summary
Name Summary

get

import

Imports a virtual machine from a Glance image storage domain.

get GET

Table 470. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

image

OpenStackImage

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.

import POST

Imports a virtual machine from a Glance image storage domain.

For example, to import the image with identifier 456 from the storage domain with identifier 123 send a request like this:

POST /ovirt-engine/api/openstackimageproviders/123/images/456/import

With a request body like this:

<action>
  <storage_domain>
    <name>images0</name>
  </storage_domain>
  <cluster>
    <name>images0</name>
  </cluster>
</action>
Table 471. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the import should be performed asynchronously.

cluster

Cluster

In

This parameter is mandatory in case of using import_as_template and indicates which cluster should be used for import glance image as template.

disk

Disk

In

import_as_template

Boolean

In

Indicates whether the image should be imported as a template.

storage_domain

StorageDomain

In

template

Template

In

OpenstackImageProvider

Table 472. Methods summary
Name Summary

get

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 OpenStack image provider in the system.

get GET

Table 473. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

provider

OpenStackImageProvider

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.

importcertificates POST

Import the SSL certificates of the external host provider.

Table 474. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

remove DELETE

Table 475. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the test should be performed asynchronously.

update PUT

Update the specified OpenStack image provider in the system.

Table 477. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackImageProvider

In/Out

OpenstackImageProviders

Table 478. Methods summary
Name Summary

add

Add a new OpenStack image provider to the system.

list

Returns the list of providers.

add POST

Add a new OpenStack image provider to the system.

Table 479. Parameters summary
Name Type Direction Summary

provider

OpenStackImageProvider

In/Out

list GET

Returns the list of providers.

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

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

OpenStackImageProvider[]

Out

search

String

In

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

OpenstackImages

Table 481. Methods summary
Name Summary

list

Lists the images of a Glance image storage domain.

list GET

Lists the images of a Glance image storage domain.

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

Table 482. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

images

OpenStackImage[]

Out

max

Integer

In

Sets the maximum number of images 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 images to return. If not specified all the images are returned.

OpenstackNetwork

Table 483. Methods summary
Name Summary

get

import

This operation imports an external network into {product-name}.

get GET

Table 484. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

network

OpenStackNetwork

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.

import POST

This operation imports an external network into {product-name}. The network will be added to the specified data center.

Table 485. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the import should be performed asynchronously.

data_center

DataCenter

In

The data center into which the network is to be imported.

data_center

The data center into which the network is to be imported. Data center is mandatory, and can be specified using the id or name attributes. The rest of the attributes will be ignored.

If auto_sync is enabled for the provider, the network might be imported automatically. To prevent this, automatic import can be disabled by setting the auto_sync to false, and enabling it again after importing the network.

OpenstackNetworkProvider

This service manages the OpenStack network provider.

Table 486. Methods summary
Name Summary

get

Returns the representation of the object managed by this service.

importcertificates

Import the SSL certificates of the external host provider.

remove

Removes the provider.

testconnectivity

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

update

Updates the provider.

get GET

Returns the representation of the object managed by this service.

For example, to get the OpenStack network provider with identifier 1234, send a request like this:

GET /ovirt-engine/api/openstacknetworkproviders/1234
Table 487. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

provider

OpenStackNetworkProvider

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.

importcertificates POST

Import the SSL certificates of the external host provider.

Table 488. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

remove DELETE

Removes the provider.

For example, to remove the OpenStack network provider with identifier 1234, send a request like this:

DELETE /ovirt-engine/api/openstacknetworkproviders/1234
Table 489. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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

async

Boolean

In

Indicates if the test should be performed asynchronously.

update PUT

Updates the provider.

For example, to update provider_name, requires_authentication, url, tenant_name and type properties, for the OpenStack network provider with identifier 1234, send a request like this:

PUT /ovirt-engine/api/openstacknetworkproviders/1234

With a request body like this:

<openstack_network_provider>
  <name>ovn-network-provider</name>
  <requires_authentication>false</requires_authentication>
  <url>http://some_server_url.domain.com:9696</url>
  <tenant_name>oVirt</tenant_name>
  <type>external</type>
</openstack_network_provider>
Table 491. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackNetworkProvider

In/Out

The provider to update.

OpenstackNetworkProviders

This service manages OpenStack network providers.

Table 492. Methods summary
Name Summary

add

The operation adds a new network provider to the system.

list

Returns the list of providers.

add POST

The operation adds a new network provider to the system. If the type property is not present, a default value of NEUTRON will be used.

Table 493. Parameters summary
Name Type Direction Summary

provider

OpenStackNetworkProvider

In/Out

list GET

Returns the list of providers.

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

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

OpenStackNetworkProvider[]

Out

search

String

In

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

OpenstackNetworks

Table 495. Methods summary
Name Summary

list

Returns the list of networks.

list GET

Returns the list of networks.

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

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

OpenStackNetwork[]

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 networks to return. If not specified all the networks are returned.

OpenstackSubnet

Table 497. Methods summary
Name Summary

get

remove

get GET

Table 498. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

subnet

OpenStackSubnet

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.

remove DELETE

Table 499. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

OpenstackSubnets

Table 500. Methods summary
Name Summary

add

list

Returns the list of sub-networks.

add POST

Table 501. Parameters summary
Name Type Direction Summary

subnet

OpenStackSubnet

In/Out

list GET

Returns the list of sub-networks.

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

Table 502. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of sub-networks to return.

subnets

OpenStackSubnet[]

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 sub-networks to return. If not specified all the sub-networks are returned.

OpenstackVolumeAuthenticationKey

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 503. Methods summary
Name Summary

get

remove

update

Update the specified authentication key.

get GET

Table 504. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

key

OpenstackVolumeAuthenticationKey

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.

remove DELETE

Table 505. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update the specified authentication key.

Table 506. Parameters summary
Name Type Direction Summary

key

OpenstackVolumeAuthenticationKey

In/Out

OpenstackVolumeAuthenticationKeys

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 507. Methods summary
Name Summary

add

Add a new authentication key to the OpenStack volume provider.

list

Returns the list of authentication keys.

add POST

Add a new authentication key to the OpenStack volume provider.

Table 508. Parameters summary
Name Type Direction Summary

key

OpenstackVolumeAuthenticationKey

In/Out

list GET

Returns the list of authentication keys.

The order of the returned list of authentication keys isn’t guaranteed.

Table 509. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

keys

OpenstackVolumeAuthenticationKey[]

Out

max

Integer

In

Sets the maximum number of keys 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 keys to return. If not specified all the keys are returned.

OpenstackVolumeProvider

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 510. Methods summary
Name Summary

get

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 OpenStack volume provider in the system.

get GET

Table 511. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

provider

OpenStackVolumeProvider

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.

importcertificates POST

Import the SSL certificates of the external host provider.

Table 512. Parameters summary
Name Type Direction Summary

certificates

Certificate[]

In

remove DELETE

Table 513. 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 provider removed from the database, even if something fails during the operation.

force

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

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

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

async

Boolean

In

Indicates if the test should be performed asynchronously.

update PUT

Update the specified OpenStack volume provider in the system.

Table 515. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackVolumeProvider

In/Out

OpenstackVolumeProviders

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 516. Methods summary
Name Summary

add

Adds a new volume provider.

list

Retrieves the list of volume providers.

add POST

Adds a new volume provider.

For example:

POST /ovirt-engine/api/openstackvolumeproviders

With a request body like this:

<openstack_volume_provider>
  <name>mycinder</name>
  <url>https://mycinder.example.com:8776</url>
  <data_center>
    <name>mydc</name>
  </data_center>
  <requires_authentication>true</requires_authentication>
  <username>admin</username>
  <password>mypassword</password>
  <tenant_name>mytenant</tenant_name>
</openstack_volume_provider>
Table 517. Parameters summary
Name Type Direction Summary

provider

OpenStackVolumeProvider

In/Out

list GET

Retrieves the list of volume providers.

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

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

OpenStackVolumeProvider[]

Out

search

String

In

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

OpenstackVolumeType

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 519. Methods summary
Name Summary

get

get GET

Table 520. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

type

OpenStackVolumeType

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.

OpenstackVolumeTypes

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 521. Methods summary
Name Summary

list

Returns the list of volume types.

list GET

Returns the list of volume types.

The order of the returned list of volume types isn’t guaranteed.

Table 522. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of volume types to return.

types

OpenStackVolumeType[]

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 volume types to return. If not specified all the volume types are returned.

OperatingSystem

Table 523. Methods summary
Name Summary

get

get GET

Table 524. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

operating_system

OperatingSystemInfo

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.

OperatingSystems

Manages the set of types of operating systems available in the system.

Table 525. Methods summary
Name Summary

list

Returns the list of types of operating system available in the system.

list GET

Returns the list of types of operating system available in the system.

The order of the returned list of operating systems isn’t guaranteed.

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

operating_system

OperatingSystemInfo[]

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 networks to return. If not specified all the networks are returned.

Permission

Table 527. Methods summary
Name Summary

get

remove

get GET

Table 528. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

permission

Permission

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.

remove DELETE

Table 529. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

Permit

A service to manage a specific permit of the role.

Table 530. Methods summary
Name Summary

get

Gets the information about the permit of the role.

remove

Removes the permit from the role.

get GET

Gets the information about the permit of the role.

For example to retrieve the information about the permit with the id 456 of the role with the id 123 send a request like this:

GET /ovirt-engine/api/roles/123/permits/456
<permit href="/ovirt-engine/api/roles/123/permits/456" id="456">
  <name>change_vm_cd</name>
  <administrative>false</administrative>
  <role href="/ovirt-engine/api/roles/123" id="123"/>
</permit>
Table 531. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

permit

Permit

Out

The permit of the role.

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.

remove DELETE

Removes the permit from the role.

For example to remove the permit with id 456 from the role with id 123 send a request like this:

DELETE /ovirt-engine/api/roles/123/permits/456
Table 532. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

Permits

Represents a permits sub-collection of the specific role.

Table 533. Methods summary
Name Summary

add

Adds a permit to the role.

list

List the permits of the role.

add POST

Adds a permit to the role. The permit name can be retrieved from the cluster_levels service.

For example to assign a permit create_vm to the role with id 123 send a request like this:

POST /ovirt-engine/api/roles/123/permits

With a request body like this:

<permit>
  <name>create_vm</name>
</permit>
Table 534. Parameters summary
Name Type Direction Summary

permit

Permit

In/Out

The permit to add.

list GET

List the permits of the role.

For example to list the permits of the role with the id 123 send a request like this:

GET /ovirt-engine/api/roles/123/permits
<permits>
  <permit href="/ovirt-engine/api/roles/123/permits/5" id="5">
    <name>change_vm_cd</name>
    <administrative>false</administrative>
    <role href="/ovirt-engine/api/roles/123" id="123"/>
  </permit>
  <permit href="/ovirt-engine/api/roles/123/permits/7" id="7">
    <name>connect_to_vm</name>
    <administrative>false</administrative>
    <role href="/ovirt-engine/api/roles/123" id="123"/>
  </permit>
</permits>

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

Table 535. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of permits to return.

permits

Permit[]

Out

List of permits.

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 permits to return. If not specified all the permits are returned.

Qos

Table 536. Methods summary
Name Summary

get

Get specified QoS in the data center.

remove

Remove specified QoS from datacenter.

update

Update the specified QoS in the dataCenter.

get GET

Get specified QoS in the data center.

GET /ovirt-engine/api/datacenters/123/qoss/123

You will get response like this one below:

<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123">
  <name>123</name>
  <description>123</description>
  <max_iops>1</max_iops>
  <max_throughput>1</max_throughput>
  <type>storage</type>
  <data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
</qos>
Table 537. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

qos

Qos

Out

Queried QoS object.

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.

remove DELETE

Remove specified QoS from datacenter.

DELETE /ovirt-engine/api/datacenters/123/qoss/123
Table 538. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update the specified QoS in the dataCenter.

PUT /ovirt-engine/api/datacenters/123/qoss/123

For example with curl:

curl -u admin@internal:123456 -X PUT -H "content-type: application/xml" -d \
"<qos><name>321</name><description>321</description><max_iops>10</max_iops></qos>" \
https://engine/ovirt-engine/api/datacenters/123/qoss/123

You will receive response like this:

<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123">
  <name>321</name>
  <description>321</description>
  <max_iops>10</max_iops>
  <max_throughput>1</max_throughput>
  <type>storage</type>
  <data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
</qos>
Table 539. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

qos

Qos

In/Out

Updated QoS object.

Qoss

Manages the set of quality of service configurations available in a data center.

Table 540. Methods summary
Name Summary

add

Add a new QoS to the dataCenter.

list

Returns the list of quality of service configurations available in the data center.

add POST

Add a new QoS to the dataCenter.

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

The response will look as follows:

<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123">
  <name>123</name>
  <description>123</description>
  <max_iops>10</max_iops>
  <type>storage</type>
  <data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
</qos>
Table 541. Parameters summary
Name Type Direction Summary

qos

Qos

In/Out

Added QoS object.

list GET

Returns the list of quality of service configurations available in the data center.

GET /ovirt-engine/api/datacenter/123/qoss

You will get response which will look like this:

<qoss>
  <qos href="/ovirt-engine/api/datacenters/123/qoss/1" id="1">...</qos>
  <qos href="/ovirt-engine/api/datacenters/123/qoss/2" id="2">...</qos>
  <qos href="/ovirt-engine/api/datacenters/123/qoss/3" id="3">...</qos>
</qoss>

The returned list of quality of service configurations isn’t guaranteed.

Table 542. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of QoS descriptors to return.

qoss

Qos[]

Out

List of queried QoS objects.

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 QoS descriptors to return. If not specified all the descriptors are returned.

Quota

Table 543. Methods summary
Name Summary

get

Retrieves a quota.

remove

Delete a quota.

update

Updates a quota.

get GET

Retrieves a quota.

An example of retrieving a quota:

GET /ovirt-engine/api/datacenters/123/quotas/456
<quota id="456">
  <name>myquota</name>
  <description>My new quota for virtual machines</description>
  <cluster_hard_limit_pct>20</cluster_hard_limit_pct>
  <cluster_soft_limit_pct>80</cluster_soft_limit_pct>
  <storage_hard_limit_pct>20</storage_hard_limit_pct>
  <storage_soft_limit_pct>80</storage_soft_limit_pct>
</quota>
Table 544. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

quota

Quota

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.

remove DELETE

Delete a quota.

An example of deleting a quota:

DELETE /ovirt-engine/api/datacenters/123-456/quotas/654-321
-0472718ab224 HTTP/1.1
Accept: application/xml
Content-type: application/xml
Table 545. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates a quota.

An example of updating a quota:

PUT /ovirt-engine/api/datacenters/123/quotas/456
<quota>
  <cluster_hard_limit_pct>30</cluster_hard_limit_pct>
  <cluster_soft_limit_pct>70</cluster_soft_limit_pct>
  <storage_hard_limit_pct>20</storage_hard_limit_pct>
  <storage_soft_limit_pct>80</storage_soft_limit_pct>
</quota>
Table 546. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

quota

Quota

In/Out

QuotaClusterLimit

Table 547. Methods summary
Name Summary

get

remove

get GET

Table 548. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

limit

QuotaClusterLimit

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.

remove DELETE

Table 549. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

QuotaClusterLimits

Manages the set of quota limits configured for a cluster.

Table 550. Methods summary
Name Summary

add

Add a cluster limit to a specified Quota.

list

Returns the set of quota limits configured for the cluster.

add POST

Add a cluster limit to a specified Quota.

Table 551. Parameters summary
Name Type Direction Summary

limit

QuotaClusterLimit

In/Out

list GET

Returns the set of quota limits configured for the cluster.

The returned list of quota limits isn’t guaranteed.

Table 552. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

limits

QuotaClusterLimit[]

Out

max

Integer

In

Sets the maximum number of limits 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 limits to return. If not specified all the limits are returned.

QuotaStorageLimit

Table 553. Methods summary
Name Summary

get

remove

get GET

Table 554. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

limit

QuotaStorageLimit

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.

remove DELETE

Table 555. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

QuotaStorageLimits

Manages the set of storage limits configured for a quota.

Table 556. Methods summary
Name Summary

add

Adds a storage limit to a specified quota.

list

Returns the list of storage limits configured for the quota.

add POST

Adds a storage limit to a specified quota.

To create a 100GiB storage limit for all storage domains in a data center, send a request like this:

POST /ovirt-engine/api/datacenters/123/quotas/456/quotastoragelimits

With a request body like this:

<quota_storage_limit>
  <limit>100</limit>
</quota_storage_limit>

To create a 50GiB storage limit for a storage domain with the ID 000, send a request like this:

POST /ovirt-engine/api/datacenters/123/quotas/456/quotastoragelimits

With a request body like this:

<quota_storage_limit>
  <limit>50</limit>
  <storage_domain id="000"/>
</quota_storage_limit>
Table 557. Parameters summary
Name Type Direction Summary

limit

QuotaStorageLimit

In/Out

list GET

Returns the list of storage limits configured for the quota.

The order of the returned list of storage limits is not guaranteed.

Table 558. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

limits

QuotaStorageLimit[]

Out

max

Integer

In

Sets the maximum number of limits 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 limits to return. If not specified, all the limits are returned.

Quotas

Manages the set of quotas configured for a data center.

Table 559. Methods summary
Name Summary

add

Creates a new quota.

list

Lists quotas of a data center.

add POST

Creates a new quota.

An example of creating a new quota:

POST /ovirt-engine/api/datacenters/123/quotas
<quota>
  <name>myquota</name>
  <description>My new quota for virtual machines</description>
</quota>
Table 560. Parameters summary
Name Type Direction Summary

quota

Quota

In/Out

list GET

Lists quotas of a data center.

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

Table 561. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of quota descriptors to return.

quotas

Quota[]

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 quota descriptors to return. If not specified all the descriptors are returned.

Role

Table 562. Methods summary
Name Summary

get

Get the role.

remove

Removes the role.

update

Updates a role.

get GET

Get the role.

GET /ovirt-engine/api/roles/123

You will receive XML response like this one:

<role id="123">
  <name>MyRole</name>
  <description>MyRole description</description>
  <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/>
  <administrative>true</administrative>
  <mutable>false</mutable>
</role>
Table 563. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

role

Role

Out

Retrieved role.

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.

remove DELETE

Removes the role.

To remove the role you need to know its id, then send request like this:

DELETE /ovirt-engine/api/roles/{role_id}
Table 564. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates a role. You are allowed to update name, description and administrative attributes after role is created. Within this endpoint you can’t add or remove roles permits you need to use service that manages permits of role.

For example to update role’s name, description and administrative attributes send a request like this:

PUT /ovirt-engine/api/roles/123

With a request body like this:

<role>
  <name>MyNewRoleName</name>
  <description>My new description of the role</description>
  <administrative>true</administrative>
</group>
Table 565. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

role

Role

In/Out

Updated role.

Roles

Provides read-only access to the global set of roles

Table 566. Methods summary
Name Summary

add

Create a new role.

list

List roles.

add POST

Create a new role. The role can be administrative or non-administrative and can have different permits.

For example, to add the MyRole non-administrative role with permits to login and create virtual machines send a request like this (note that you have to pass permit id):

POST /ovirt-engine/api/roles

With a request body like this:

<role>
  <name>MyRole</name>
  <description>My custom role to create virtual machines</description>
  <administrative>false</administrative>
  <permits>
    <permit id="1"/>
    <permit id="1300"/>
  </permits>
</group>
Table 567. Parameters summary
Name Type Direction Summary

role

Role

In/Out

Role that will be added.

list GET

List roles.

GET /ovirt-engine/api/roles

You will receive response in XML like this one:

<roles>
  <role id="123">
     <name>SuperUser</name>
     <description>Roles management administrator</description>
     <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/>
     <administrative>true</administrative>
     <mutable>false</mutable>
  </role>
  ...
</roles>

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

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

Retrieved list of roles.

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.

SchedulingPolicies

Manages the set of scheduling policies available in the system.

Table 569. Methods summary
Name Summary

add

Add a new scheduling policy to the system.

list

Returns the list of scheduling policies available in the system.

add POST

Add a new scheduling policy to the system.

Table 570. Parameters summary
Name Type Direction Summary

policy

SchedulingPolicy

In/Out

list GET

Returns the list of scheduling policies available in the system.

The order of the returned list of scheduling policies isn’t guaranteed.

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

max

Integer

In

Sets the maximum number of policies to return.

policies

SchedulingPolicy[]

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 policies to return. If not specified all the policies are returned.

SchedulingPolicy

Table 572. Methods summary
Name Summary

get

remove

update

Update the specified user defined scheduling policy in the system.

get GET

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

policy

SchedulingPolicy

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.

remove DELETE

Table 574. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update the specified user defined scheduling policy in the system.

Table 575. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

policy

SchedulingPolicy

In/Out

SchedulingPolicyUnit

Table 576. Methods summary
Name Summary

get

remove

get GET

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

unit

SchedulingPolicyUnit

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.

remove DELETE

Table 578. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

SchedulingPolicyUnits

Manages the set of scheduling policy units available in the system.

Table 579. Methods summary
Name Summary

list

Returns the list of scheduling policy units available in the system.

list GET

Returns the list of scheduling policy units available in the system.

The order of the returned list of scheduling policy units isn’t guaranteed.

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

max

Integer

In

Sets the maximum number of policy units to return.

units

SchedulingPolicyUnit[]

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 policy units to return. If not specified all the policy units are returned.

Snapshot

Table 581. Methods summary
Name Summary

get

remove

restore

Restores a virtual machine snapshot.

get GET

Table 582. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

snapshot

Snapshot

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.

remove DELETE

Table 583. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

Indicates if all the attributes of the virtual machine snapshot should be included in the response.

async

Boolean

In

Indicates if the remove should be performed asynchronously.

all_content

Indicates if all the attributes of the virtual machine snapshot should be included in the response.

By default the attribute initialization.configuration.data is excluded.

For example, to retrieve the complete representation of the snapshot with id 456 of the virtual machine with id 123 send a request like this:

GET /ovirt-engine/api/vms/123/snapshots/456?all_content=true

restore POST

Restores a virtual machine snapshot.

For example, to restore the snapshot with identifier 456 of virtual machine with identifier 123 send a request like this:

POST /ovirt-engine/api/vms/123/snapshots/456/restore

With an empty action in the body:

<action/>
Confirm that the commit operation is finished and the virtual machine is down before running the virtual machine.
Table 584. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the restore should be performed asynchronously.

disks

Disk[]

In

Specify the disks included in the snapshot’s restore.

restore_memory

Boolean

In

disks

Specify the disks included in the snapshot’s restore.

For each disk parameter, it is also required to specify its image_id.

For example, to restore a snapshot with an identifier 456 of a virtual machine with identifier 123, including a disk with identifier 111 and image_id of 222, send a request like this:

POST /ovirt-engine/api/vms/123/snapshots/456/restore

Request body:

<action>
  <disks>
    <disk id="111">
      <image_id>222</image_id>
    </disk>
  </disks>
</action>

SnapshotCdrom

Table 585. Methods summary
Name Summary

get

get GET

Table 586. Parameters summary
Name Type Direction Summary

cdrom

Cdrom

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.

SnapshotCdroms

Manages the set of CD-ROM devices of a virtual machine snapshot.

Table 587. Methods summary
Name Summary

list

Returns the list of CD-ROM devices of the snapshot.

list GET

Returns the list of CD-ROM devices of the snapshot.

The order of the returned list of CD-ROM devices isn’t guaranteed.

Table 588. Parameters summary
Name Type Direction Summary

cdroms

Cdrom[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of CDROMS 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 CDROMS to return. If not specified all the CDROMS are returned.

SnapshotDisk

Table 589. Methods summary
Name Summary

get

get GET

Table 590. Parameters summary
Name Type Direction Summary

disk

Disk

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.

SnapshotDisks

Manages the set of disks of an snapshot.

Table 591. Methods summary
Name Summary

list

Returns the list of disks of the snapshot.

list GET

Returns the list of disks of the snapshot.

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

Table 592. Parameters summary
Name Type Direction Summary

disks

Disk[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of disks 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 disks to return. If not specified all the disks are returned.

SnapshotNic

Table 593. Methods summary
Name Summary

get

get GET

Table 594. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

nic

Nic

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.

SnapshotNics

Manages the set of NICs of an snapshot.

Table 595. Methods summary
Name Summary

list

Returns the list of NICs of the snapshot.

list GET

Returns the list of NICs of the snapshot.

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

Table 596. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

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 NICs to return. If not specified all the NICs are returned.

Snapshots

Manages the set of snapshots of a storage domain or virtual machine.

Table 597. Methods summary
Name Summary

add

Creates a virtual machine snapshot.

list

Returns the list of snapshots of the storage domain or virtual machine.

add POST

Creates a virtual machine snapshot.

For example, to create a new snapshot for virtual machine 123 send a request like this:

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

With a request body like this:

<snapshot>
  <description>My snapshot</description>
</snapshot>

For including only a sub-set of disks in the snapshots, add disk_attachments element to the request body. Note that disks which are not specified in disk_attachments element will not be a part of the snapshot. If an empty disk_attachments element is passed, the snapshot will include only the virtual machine configuration. If no disk_attachments element is passed, then all the disks will be included in the snapshot.

For each disk, image_id element can be specified for setting the new active image id. This is used in order to restore a chain of images from backup. I.e. when restoring a disk with snapshots, the relevant image_id should be specified for each snapshot (so the identifiers of the disk snapshots are identical to the backup).

<snapshot>
  <description>My snapshot</description>
  <disk_attachments>
    <disk_attachment>
      <disk id="123">
        <image_id>456</image_id>
      </disk>
    </disk_attachment>
  </disk_attachments>
</snapshot>

When a snapshot is created, the default value for the persist_memorystate attribute is true. That means that the content of the memory of the virtual machine will be included in the snapshot, and it also means that the virtual machine will be paused for a longer time. That can negatively affect applications that are very sensitive to timing (NTP servers, for example). In those cases make sure that you set the attribute to false:

<snapshot>
  <description>My snapshot</description>
  <persist_memorystate>false</persist_memorystate>
</snapshot>
Table 598. Parameters summary
Name Type Direction Summary

snapshot

Snapshot

In/Out

list GET

Returns the list of snapshots of the storage domain or virtual machine.

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

Table 599. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

Indicates if all the attributes of the virtual machine snapshot should be included in the response.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

Snapshot[]

Out

all_content

Indicates if all the attributes of the virtual machine snapshot should be included in the response.

By default the attribute initialization.configuration.data is excluded.

For example, to retrieve the complete representation of the virtual machine with id 123 snapshots send a request like this:

GET /ovirt-engine/api/vms/123/snapshots?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.

max

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

SshPublicKey

Table 600. Methods summary
Name Summary

get

remove

update

Replaces the key with a new resource.

get GET

Table 601. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

key

SshPublicKey

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.

remove DELETE

Table 602. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Replaces the key with a new resource.

Since version 4.4.8 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. Instead please use DELETE followed by add operation.
Table 603. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

key

SshPublicKey

In/Out

SshPublicKeys

Table 604. Methods summary
Name Summary

add

list

Returns a list of SSH public keys of the user.

add POST

Table 605. Parameters summary
Name Type Direction Summary

key

SshPublicKey

In/Out

list GET

Returns a list of SSH public keys of the user.

For example, to retrieve the list of SSH keys of user with identifier 123, send a request like this:

GET /ovirt-engine/api/users/123/sshpublickeys

The result will be the following XML document:

<ssh_public_keys>
  <ssh_public_key href="/ovirt-engine/api/users/123/sshpublickeys/456" id="456">
    <content>ssh-rsa ...</content>
    <user href="/ovirt-engine/api/users/123" id="123"/>
  </ssh_public_key>
</ssh_public_keys>

Or the following JSON object

{
  "ssh_public_key": [
    {
      "content": "ssh-rsa ...",
      "user": {
        "href": "/ovirt-engine/api/users/123",
        "id": "123"
      },
      "href": "/ovirt-engine/api/users/123/sshpublickeys/456",
      "id": "456"
    }
  ]
}

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

Table 606. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

keys

SshPublicKey[]

Out

max

Integer

In

Sets the maximum number of keys 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 keys to return. If not specified all the keys are returned.

Statistic

Table 607. Methods summary
Name Summary

get

get GET

Table 608. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

statistic

Statistic

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.

Statistics

Table 609. Methods summary
Name Summary

list

Retrieves a list of statistics.

list GET

Retrieves a list of statistics.

For example, to retrieve the statistics for virtual machine 123 send a request like this:

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

The result will be like this:

<statistics>
  <statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456">
    <name>memory.installed</name>
    <description>Total memory configured</description>
    <kind>gauge</kind>
    <type>integer</type>
    <unit>bytes</unit>
    <values>
      <value>
        <datum>1073741824</datum>
      </value>
    </values>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </statistic>
  ...
</statistics>

Just a single part of the statistics can be retrieved by specifying its id at the end of the URI. That means:

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

Outputs:

<statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456">
  <name>memory.installed</name>
  <description>Total memory configured</description>
  <kind>gauge</kind>
  <type>integer</type>
  <unit>bytes</unit>
  <values>
    <value>
      <datum>1073741824</datum>
    </value>
  </values>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</statistic>

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

Table 610. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of statistics to return.

statistics

Statistic[]

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 statistics to return. If not specified all the statistics are returned.

Step

A service to manage a step.

Table 611. Methods summary
Name Summary

end

Marks an external step execution as ended.

get

Retrieves a step.

end POST

Marks an external step execution as ended.

For example, to terminate a step with identifier 456 which belongs to a job with identifier 123 send the following request:

POST /ovirt-engine/api/jobs/123/steps/456/end

With the following request body:

<action>
  <force>true</force>
  <succeeded>true</succeeded>
</action>
Table 612. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

Indicates if the step should be forcibly terminated.

succeeded

Boolean

In

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

succeeded

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

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

get GET

Retrieves a step.

GET /ovirt-engine/api/jobs/123/steps/456

You will receive response in XML like this one:

<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
  </actions>
  <description>Validating</description>
  <end_time>2016-12-12T23:07:26.627+02:00</end_time>
  <external>false</external>
  <number>0</number>
  <start_time>2016-12-12T23:07:26.605+02:00</start_time>
  <status>finished</status>
  <type>validating</type>
  <job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>
Table 613. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

step

Step

Out

Retrieves the representation of the step.

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.

Steps

A service to manage steps.

Table 614. Methods summary
Name Summary

add

Add an external step to an existing job or to an existing step.

list

Retrieves the representation of the steps.

add POST

Add an external step to an existing job or to an existing step.

For example, to add a step to job with identifier 123 send the following request:

POST /ovirt-engine/api/jobs/123/steps

With the following request body:

<step>
  <description>Validating</description>
  <start_time>2016-12-12T23:07:26.605+02:00</start_time>
  <status>started</status>
  <type>validating</type>
</step>

The response should look like:

<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
  </actions>
  <description>Validating</description>
  <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/>
  <external>true</external>
  <number>2</number>
  <start_time>2016-12-13T01:06:15.380+02:00</start_time>
  <status>started</status>
  <type>validating</type>
  <job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>
Table 615. Parameters summary
Name Type Direction Summary

step

Step

In/Out

Step that will be added.

list GET

Retrieves the representation of the steps.

GET /ovirt-engine/api/job/123/steps

You will receive response in XML like this one:

<steps>
  <step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
    <actions>
      <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
    </actions>
    <description>Validating</description>
    <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/>
    <external>true</external>
    <number>2</number>
    <start_time>2016-12-13T01:06:15.380+02:00</start_time>
    <status>started</status>
    <type>validating</type>
    <job href="/ovirt-engine/api/jobs/123" id="123"/>
  </step>
  ...
</steps>

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

Table 616. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of steps to return.

steps

Step[]

Out

A representation of steps.

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 steps to return. If not specified all the steps are returned.

Storage

Table 617. Methods summary
Name Summary

get

get GET

Table 618. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

report_status

Boolean

In

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

storage

HostStorage

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.

report_status

Indicates if the status of the LUNs in the storage should be checked. Checking the status of the LUN is an heavy weight operation and this data is not always needed by the user. This parameter will give the option to not perform the status check of the LUNs.

The default is true for backward compatibility.

Here an example with the LUN status :

<host_storage id="360014051136c20574f743bdbd28177fd">
  <logical_units>
    <logical_unit id="360014051136c20574f743bdbd28177fd">
      <lun_mapping>0</lun_mapping>
      <paths>1</paths>
      <product_id>lun0</product_id>
      <serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial>
      <size>10737418240</size>
      <status>used</status>
      <vendor_id>LIO-ORG</vendor_id>
      <volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-MNzIBZ</volume_group_id>
    </logical_unit>
  </logical_units>
  <type>iscsi</type>
  <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/>
</host_storage>

Here an example without the LUN status :

<host_storage id="360014051136c20574f743bdbd28177fd">
  <logical_units>
    <logical_unit id="360014051136c20574f743bdbd28177fd">
      <lun_mapping>0</lun_mapping>
      <paths>1</paths>
      <product_id>lun0</product_id>
      <serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial>
      <size>10737418240</size>
      <vendor_id>LIO-ORG</vendor_id>
      <volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-MNzIBZ</volume_group_id>
    </logical_unit>
  </logical_units>
  <type>iscsi</type>
  <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/>
</host_storage>

StorageDomain

Table 619. Methods summary
Name Summary

get

Retrieves the description of the storage domain.

isattached

Used for querying if the storage domain is already attached to a data center using the is_attached boolean field, which is part of the storage server.

reduceluns

This operation reduces logical units from the storage domain.

refreshluns

This operation refreshes the LUN size.

remove

Removes the storage domain.

update

Updates a storage domain.

updateovfstore

This operation forces the update of the OVF_STORE of this storage domain.

get GET

Retrieves the description of the storage domain.

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

storage_domain

StorageDomain

Out

The description of the storage domain.

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.

isattached POST

Used for querying if the storage domain is already attached to a data center using the is_attached boolean field, which is part of the storage server. IMPORTANT: Executing this API will cause the host to disconnect from the storage domain.

Table 621. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

host

Host

In

Indicates the data center’s host.

is_attached

Boolean

Out

Indicates whether the storage domain is attached to the data center.

reduceluns POST

This operation reduces logical units from the storage domain.

In order to do so the data stored on the provided logical units will be moved to other logical units of the storage domain and only then they will be reduced from the storage domain.

For example, in order to reduce two logical units from a storage domain send a request like this:

POST /ovirt-engine/api/storageDomains/123/reduceluns

With a request body like this:

 <action>
   <logical_units>
     <logical_unit id="1IET_00010001"/>
     <logical_unit id="1IET_00010002"/>
   </logical_units>
 </action>
Note that this operation is only applicable to block storage domains (i.e., storage domains with the
xref:types-storage_type[storage type] of iSCSI or FCP).
Table 622. Parameters summary
Name Type Direction Summary

logical_units

LogicalUnit[]

In

The logical units that need to be reduced from the storage domain.

refreshluns POST

This operation refreshes the LUN size.

After increasing the size of the underlying LUN on the storage server, the user can refresh the LUN size. This action forces a rescan of the provided LUNs and updates the database with the new size, if required.

For example, in order to refresh the size of two LUNs send a request like this:

POST /ovirt-engine/api/storageDomains/262b056b-aede-40f1-9666-b883eff59d40/refreshluns

With a request body like this:

 <action>
   <logical_units>
     <logical_unit id="1IET_00010001"/>
     <logical_unit id="1IET_00010002"/>
   </logical_units>
 </action>
Table 623. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the refresh should be performed asynchronously.

logical_units

LogicalUnit[]

In

The LUNs that need to be refreshed.

remove DELETE

Removes the storage domain.

Without any special parameters, the storage domain is detached from the system and removed from the database. The storage domain can then be imported to the same or to a different setup, with all the data on it. If the storage is not accessible the operation will fail.

If the destroy parameter is true then the operation will always succeed, even if the storage is not accessible, the failure is just ignored and the storage domain is removed from the database anyway.

If the format parameter is true then the actual storage is formatted, and the metadata is removed from the LUN or directory, so it can no longer be imported to the same or to a different setup.

Table 624. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

destroy

Boolean

In

Indicates if the operation should succeed, and the storage domain removed from the database, even if the storage is not accessible.

format

Boolean

In

Indicates if the actual storage should be formatted, removing all the metadata from the underlying LUN or directory:

[source] ---- DELETE /ovirt-engine/api/storageDomains/123?format=true ----

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

host

String

In

Indicates which host should be used to remove the storage domain.

destroy

Indicates if the operation should succeed, and the storage domain removed from the database, even if the storage is not accessible.

DELETE /ovirt-engine/api/storageDomains/123?destroy=true

This parameter is optional, and the default value is false. When the value of destroy is true the host parameter will be ignored.

host

Indicates which host should be used to remove the storage domain.

This parameter is mandatory, except if the destroy parameter is included and its value is true, in that case the host parameter will be ignored.

The value should contain the name or the identifier of the host. For example, to use the host named myhost to remove the storage domain with identifier 123 send a request like this:

DELETE /ovirt-engine/api/storageDomains/123?host=myhost

update PUT

Updates a storage domain.

Not all of the StorageDomain's attributes are updatable after creation. Those that can be updated are: name, description, comment, warning_low_space_indicator, critical_space_action_blocker and wipe_after_delete. (Note that changing the wipe_after_delete attribute will not change the wipe after delete property of disks that already exist).

To update the name and wipe_after_delete attributes of a storage domain with an identifier 123, send a request as follows:

PUT /ovirt-engine/api/storageDomains/123

With a request body as follows:

<storage_domain>
  <name>data2</name>
  <wipe_after_delete>true</wipe_after_delete>
</storage_domain>
Table 625. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

storage_domain

StorageDomain

In/Out

The updated storage domain.

updateovfstore POST

This operation forces the update of the OVF_STORE of this storage domain.

The OVF_STORE is a disk image that contains the metadata of virtual machines and disks that reside in the storage domain. This metadata is used in case the domain is imported or exported to or from a different data center or a different installation.

By default the OVF_STORE is updated periodically (set by default to 60 minutes) but users might want to force an update after an important change, or when the they believe the OVF_STORE is corrupt.

When initiated by the user, OVF_STORE update will be performed whether an update is needed or not.

Table 626. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the OVF_STORE update should be performed asynchronously.

StorageDomainContentDisk

Table 627. Methods summary
Name Summary

get

get GET

Table 628. Parameters summary
Name Type Direction Summary

disk

Disk

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.

StorageDomainContentDisks

Manages the set of disks available in a storage domain.

Table 629. Methods summary
Name Summary

list

Returns the list of disks available in the storage domain.

list GET

Returns the list of disks available in the storage domain.

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

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

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.

StorageDomainDisk

Manages a single disk available in a storage domain.

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 a specific disk.
Table 631. 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.

reduce

Reduces the size of the disk image.

remove

Removes a disk.

sparsify

Sparsify the disk.

update

Updates the disk.

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

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

storage_domain

StorageDomain

In

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

get GET

Retrieves the description of the disk.

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

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

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

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.

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.

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

disk

Disk

In/Out

The update to apply to the disk.

StorageDomainDisks

Manages the collection of disks available inside a specific storage domain.

Table 638. Methods summary
Name Summary

add

Adds or registers a disk.

list

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

add POST

Adds or registers a disk.

Since version 4.2 of the {engine-name} 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 639. 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.

This parameter has been deprecated since version 4.2 of the {engine-name}.

list GET

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

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

Table 640. Parameters summary
Name Type Direction Summary

disks

Disk[]

Out

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

unregistered

Boolean

In

Indicates whether to retrieve a list of registered or unregistered disks in the storage domain.

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.

unregistered

Indicates whether to retrieve a list of registered or unregistered disks in the storage domain. To get a list of unregistered disks in the storage domain the call should indicate the unregistered flag. For example, to get a list of unregistered disks the REST API call should look like this:

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

The default value of the unregistered flag is false. The request only applies to storage domains that are attached.

StorageDomainServerConnection

Table 641. Methods summary
Name Summary

get

remove

Detaches a storage connection from storage.

get GET

Table 642. Parameters summary
Name Type Direction Summary

connection

StorageConnection

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.

remove DELETE

Detaches a storage connection from storage.

Table 643. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

StorageDomainServerConnections

Manages the set of connections to storage servers that exist in a storage domain.

Table 644. Methods summary
Name Summary

add

list

Returns the list of connections to storage servers that existin the storage domain.

add POST

Table 645. Parameters summary
Name Type Direction Summary

connection

StorageConnection

In/Out

list GET

Returns the list of connections to storage servers that existin the storage domain.

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

Table 646. Parameters summary
Name Type Direction Summary

connections

StorageConnection[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of connections 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 connections to return. If not specified all the connections are returned.

StorageDomainTemplate

Table 647. Methods summary
Name Summary

get

import

Action to import a template from an export storage domain.

register

Register the Template means importing the Template from the data domain by inserting the configuration of the Template and disks into the database without the copy process.

remove

get GET

Table 648. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

template

Template

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.

import POST

Action to import a template from an export storage domain.

For example, to import the template 456 from the storage domain 123 send the following request:

POST /ovirt-engine/api/storagedomains/123/templates/456/import

With the following request body:

<action>
  <storage_domain>
    <name>myexport</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
</action>

If you register an entity without specifying the cluster ID or name, the cluster name from the entity’s OVF will be used (unless the register request also includes the cluster mapping).

Table 649. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the import should be performed asynchronously.

clone

Boolean

In

Use the optional clone parameter to generate new UUIDs for the imported template and its entities.

cluster

Cluster

In

exclusive

Boolean

In

storage_domain

StorageDomain

In

template

Template

In

vm

Vm

In

clone

Use the optional clone parameter to generate new UUIDs for the imported template and its entities.

You can import a template with the clone parameter set to false when importing a template from an export domain, with templates that were exported by a different {product-name} environment.

register POST

Register the Template means importing the Template from the data domain by inserting the configuration of the Template and disks into the database without the copy process.

Table 650. Parameters summary
Name Type Direction Summary

allow_partial_import

Boolean

In

Indicates whether a template is allowed to be registered with only some of its disks.

async

Boolean

In

Indicates if the registration should be performed asynchronously.

clone

Boolean

In

cluster

Cluster

In

exclusive

Boolean

In

registration_configuration

RegistrationConfiguration

In

This parameter describes how the template should be registered.

template

Template

In

vnic_profile_mappings

VnicProfileMapping[]

In

Deprecated attribute describing mapping rules for virtual NIC profiles that will be applied during the import\register process.

allow_partial_import

Indicates whether a template is allowed to be registered with only some of its disks.

If this flag is true, the system will not fail in the validation process if an image is not found, but instead it will allow the template to be registered without the missing disks. This is mainly used during registration of a template when some of the storage domains are not available. The default value is false.

registration_configuration

This parameter describes how the template should be registered.

This parameter is optional. If the parameter is not specified, the template will be registered with the same configuration that it had in the original environment where it was created.

vnic_profile_mappings

Deprecated attribute describing mapping rules for virtual NIC profiles that will be applied during the import\register process.

Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future. To specify vnic_profile_mappings use the vnic_profile_mappings attribute inside the RegistrationConfiguration type.

remove DELETE

Table 651. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

StorageDomainTemplates

Manages the set of templates available in a storage domain.

Table 652. Methods summary
Name Summary

list

Returns the list of templates availalbe in the storage domain.

list GET

Returns the list of templates availalbe in the storage domain.

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

Table 653. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of templates to return.

templates

Template[]

Out

unregistered

Boolean

In

Indicates whether to retrieve a list of registered or unregistered templates which contain disks on the storage domain.

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 templates to return. If not specified all the templates are returned.

unregistered

Indicates whether to retrieve a list of registered or unregistered templates which contain disks on the storage domain. To get a list of unregistered templates the call should indicate the unregistered flag. For example, to get a list of unregistered templates the REST API call should look like this:

GET /ovirt-engine/api/storagedomains/123/templates?unregistered=true

The default value of the unregisterd flag is false. The request only apply to storage domains that are attached.

StorageDomainVm

Table 654. Methods summary
Name Summary

get

import

Imports a virtual machine from an export storage domain.

register

remove

Deletes a virtual machine from an export storage domain.

get GET

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

import POST

Imports a virtual machine from an export storage domain.

For example, send a request like this:

POST /ovirt-engine/api/storagedomains/123/vms/456/import

With a request body like this:

<action>
  <storage_domain>
    <name>mydata</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
</action>

To import a virtual machine as a new entity add the clone parameter:

<action>
  <storage_domain>
    <name>mydata</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
  <clone>true</clone>
  <vm>
    <name>myvm</name>
  </vm>
</action>

Include an optional disks parameter to choose which disks to import. For example, to import the disks of the template that have the identifiers 123 and 456 send the following request body:

<action>
  <cluster>
    <name>mycluster</name>
  </cluster>
  <vm>
    <name>myvm</name>
  </vm>
  <disks>
    <disk id="123"/>
    <disk id="456"/>
  </disks>
</action>

If you register an entity without specifying the cluster ID or name, the cluster name from the entity’s OVF will be used (unless the register request also includes the cluster mapping).

Table 656. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the import should be performed asynchronously.

clone

Boolean

In

Indicates if the identifiers of the imported virtual machine should be regenerated.

cluster

Cluster

In

collapse_snapshots

Boolean

In

Indicates of the snapshots of the virtual machine that is imported should be collapsed, so that the result will be a virtual machine without snapshots.

exclusive

Boolean

In

storage_domain

StorageDomain

In

vm

Vm

In

clone

Indicates if the identifiers of the imported virtual machine should be regenerated.

By default when a virtual machine is imported the identifiers are preserved. This means that the same virtual machine can’t be imported multiple times, as that identifiers needs to be unique. To allow importing the same machine multiple times set this parameter to true, as the default is false.

collapse_snapshots

Indicates of the snapshots of the virtual machine that is imported should be collapsed, so that the result will be a virtual machine without snapshots.

This parameter is optional, and if it isn’t explicitly specified the default value is false.

register POST

Table 657. Parameters summary
Name Type Direction Summary

allow_partial_import

Boolean

In

Indicates whether a virtual machine is allowed to be registered with only some of its disks.

async

Boolean

In

Indicates if the registration should be performed asynchronously.

clone

Boolean

In

cluster

Cluster

In

reassign_bad_macs

Boolean

In

Indicates if the problematic MAC addresses should be re-assigned during the import process by the engine.

registration_configuration

RegistrationConfiguration

In

This parameter describes how the virtual machine should be registered.

vm

Vm

In

vnic_profile_mappings

VnicProfileMapping[]

In

Deprecated attribute describing mapping rules for virtual NIC profiles that will be applied during the import\register process.

allow_partial_import

Indicates whether a virtual machine is allowed to be registered with only some of its disks.

If this flag is true, the engine will not fail in the validation process if an image is not found, but instead it will allow the virtual machine to be registered without the missing disks. This is mainly used during registration of a virtual machine when some of the storage domains are not available. The default value is false.

reassign_bad_macs

Indicates if the problematic MAC addresses should be re-assigned during the import process by the engine.

A MAC address would be considered as a problematic one if one of the following is true:

  • It conflicts with a MAC address that is already allocated to a virtual machine in the target environment.

  • It’s out of the range of the target MAC address pool.

registration_configuration

This parameter describes how the virtual machine should be registered.

This parameter is optional. If the parameter is not specified, the virtual machine will be registered with the same configuration that it had in the original environment where it was created.

vnic_profile_mappings

Deprecated attribute describing mapping rules for virtual NIC profiles that will be applied during the import\register process.

Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future. To specify vnic_profile_mappings use the vnic_profile_mappings attribute inside the RegistrationConfiguration type.

remove DELETE

Deletes a virtual machine from an export storage domain.

For example, to delete the virtual machine 456 from the storage domain 123, send a request like this:

DELETE /ovirt-engine/api/storagedomains/123/vms/456
Table 658. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

StorageDomainVmDiskAttachment

Returns the details of the disks attached to a virtual machine in the export domain.

Table 659. Methods summary
Name Summary

get

Returns the details of the attachment with all its properties and a link to the disk.

get GET

Returns the details of the attachment with all its properties and a link to the disk.

Table 660. Parameters summary
Name Type Direction Summary

attachment

DiskAttachment

Out

The disk attachment.

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.

StorageDomainVmDiskAttachments

Returns the details of a disk attached to a virtual machine in the export domain.

Table 661. Methods summary
Name Summary

list

List the disks that are attached to the virtual machine.

list GET

List the disks that are attached to the virtual machine.

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

Table 662. Parameters summary
Name Type Direction Summary

attachments

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.

StorageDomainVms

Lists the virtual machines of an export storage domain.

For example, to retrieve the virtual machines that are available in the storage domain with identifier 123 send the following request:

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

This will return the following response body:

<vms>
  <vm id="456" href="/api/storagedomains/123/vms/456">
    <name>vm1</name>
    ...
    <storage_domain id="123" href="/api/storagedomains/123"/>
    <actions>
      <link rel="import" href="/api/storagedomains/123/vms/456/import"/>
    </actions>
  </vm>
</vms>

Virtual machines and templates in these collections have a similar representation to their counterparts in the top-level Vm and Template collections, except they also contain a StorageDomain reference and an import action.

Table 663. Methods summary
Name Summary

list

Returns the list of virtual machines of the export storage domain.

list GET

Returns the list of virtual machines of the export storage domain.

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

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

unregistered

Boolean

In

Indicates whether to retrieve a list of registered or unregistered virtual machines which contain disks on the storage domain.

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.

max

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

unregistered

Indicates whether to retrieve a list of registered or unregistered virtual machines which contain disks on the storage domain. To get a list of unregistered virtual machines the call should indicate the unregistered flag. For example, to get a list of unregistered virtual machines the REST API call should look like this:

GET /ovirt-engine/api/storagedomains/123/vms?unregistered=true

The default value of the unregisterd flag is false. The request only apply to storage domains that are attached.

StorageDomains

Manages the set of storage domains in the system.

Table 665. Methods summary
Name Summary

add

Adds a new storage domain.

list

Returns the list of storage domains in the system.

add POST

Adds a new storage domain.

Creation of a new StorageDomain requires the name, type, host, and storage attributes. Identify the host attribute with the id or name attributes. In {product-name} 3.6 and later you can enable the wipe after delete option by default on the storage domain. To configure this, specify wipe_after_delete in the POST request. This option can be edited after the domain is created, but doing so will not change the wipe after delete property of disks that already exist.

To add a new storage domain with specified name, type, storage.type, storage.address, and storage.path, and using a host with an id 123, send a request like this:

POST /ovirt-engine/api/storageDomains

With a request body like this:

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

To create a new NFS ISO storage domain send a request like this:

<storage_domain>
  <name>myisos</name>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/export/myisos</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>

To create a new iSCSI storage domain send a request like this:

<storage_domain>
  <name>myiscsi</name>
  <type>data</type>
  <storage>
    <type>iscsi</type>
    <logical_units>
      <logical_unit id="3600144f09dbd050000004eedbd340001"/>
      <logical_unit id="3600144f09dbd050000004eedbd340002"/>
    </logical_units>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
Table 666. Parameters summary
Name Type Direction Summary

storage_domain

StorageDomain

In/Out

The storage domain to add.

list GET

Returns the list of storage domains in the system.

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

Table 667. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

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

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 storage domains to return.

search

String

In

A query string used to restrict the returned storage domains.

storage_domains

StorageDomain[]

Out

A list of the storage domains in the system.

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. 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 storage domains to return. If not specified, all the storage domains are returned.

StorageServerConnection

Table 668. Methods summary
Name Summary

get

remove

Removes a storage connection.

update

Updates the storage connection.

get GET

Table 669. Parameters summary
Name Type Direction Summary

conection

StorageConnection

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.

remove DELETE

Removes a storage connection.

A storage connection can only be deleted if neither storage domain nor LUN disks reference it. The host name or id is optional; providing it disconnects (unmounts) the connection from that host.

Table 670. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

host

String

In

The name or identifier of the host from which the connection would be unmounted (disconnected).

host

The name or identifier of the host from which the connection would be unmounted (disconnected). If not provided, no host will be disconnected.

For example, to use the host with identifier 456 to delete the storage connection with identifier 123 send a request like this:

DELETE /ovirt-engine/api/storageconnections/123?host=456

update PUT

Updates the storage connection.

For example, to change the address of an NFS storage server, send a request like this:

PUT /ovirt-engine/api/storageconnections/123

With a request body like this:

<storage_connection>
  <address>mynewnfs.example.com</address>
</storage_connection>

To change the connection of an iSCSI storage server, send a request like this:

PUT /ovirt-engine/api/storageconnections/123

With a request body like this:

<storage_connection>
  <port>3260</port>
  <target>iqn.2017-01.com.myhost:444</target>
</storage_connection>
Table 671. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

connection

StorageConnection

In/Out

force

Boolean

In

Indicates if the operation should succeed regardless to the relevant storage domain’s status (i.

force

Indicates if the operation should succeed regardless to the relevant storage domain’s status (i.e. updating is also applicable when storage domain’s status is not maintenance).

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

StorageServerConnectionExtension

Table 672. Methods summary
Name Summary

get

remove

update

Update a storage server connection extension for the given host.

get GET

Table 673. Parameters summary
Name Type Direction Summary

extension

StorageConnectionExtension

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.

remove DELETE

Table 674. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update a storage server connection extension for the given host.

To update the storage connection 456 of host 123 send a request like this:

PUT /ovirt-engine/api/hosts/123/storageconnectionextensions/456

With a request body like this:

<storage_connection_extension>
  <target>iqn.2016-01.com.example:mytarget</target>
  <username>myuser</username>
  <password>mypassword</password>
</storage_connection_extension>
Table 675. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

extension

StorageConnectionExtension

In/Out

StorageServerConnectionExtensions

Table 676. Methods summary
Name Summary

add

Creates a new storage server connection extension for the given host.

list

Returns the list os storage connection extensions.

add POST

Creates a new storage server connection extension for the given host.

The extension lets the user define credentials for an iSCSI target for a specific host. For example to use myuser and mypassword as the credentials when connecting to the iSCSI target from host 123 send a request like this:

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

With a request body like this:

<storage_connection_extension>
  <target>iqn.2016-01.com.example:mytarget</target>
  <username>myuser</username>
  <password>mypassword</password>
</storage_connection_extension>
Table 677. Parameters summary
Name Type Direction Summary

extension

StorageConnectionExtension

In/Out

list GET

Returns the list os storage connection extensions.

The order of the returned list of storage connections isn’t guaranteed.

Table 678. Parameters summary
Name Type Direction Summary

extensions

StorageConnectionExtension[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of extensions 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 extensions to return. If not specified all the extensions are returned.

StorageServerConnections

Table 679. Methods summary
Name Summary

add

Creates a new storage connection.

list

Returns the list of storage connections.

add POST

Creates a new storage connection.

For example, to create a new storage connection for the NFS server mynfs.example.com and NFS share /export/mydata send a request like this:

POST /ovirt-engine/api/storageconnections

With a request body like this:

<storage_connection>
  <type>nfs</type>
  <address>mynfs.example.com</address>
  <path>/export/mydata</path>
  <host>
    <name>myhost</name>
  </host>
</storage_connection>
Table 680. Parameters summary
Name Type Direction Summary

connection

StorageConnection

In/Out

list GET

Returns the list of storage connections.

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

Table 681. Parameters summary
Name Type Direction Summary

connections

StorageConnection[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of connections 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 connections to return. If not specified all the connections are returned.

System

Table 682. Methods summary
Name Summary

get

Returns basic information describing the API, like the product name, the version number and a summary of the number of relevant objects.

reloadconfigurations

get GET

Returns basic information describing the API, like the product name, the version number and a summary of the number of relevant objects.

GET /ovirt-engine/api

We get following response:

<api>
  <link rel="capabilities" href="/api/capabilities"/>
  <link rel="clusters" href="/api/clusters"/>
  <link rel="clusters/search" href="/api/clusters?search={query}"/>
  <link rel="datacenters" href="/api/datacenters"/>
  <link rel="datacenters/search" href="/api/datacenters?search={query}"/>
  <link rel="events" href="/api/events"/>
  <link rel="events/search" href="/api/events?search={query}"/>
  <link rel="hosts" href="/api/hosts"/>
  <link rel="hosts/search" href="/api/hosts?search={query}"/>
  <link rel="networks" href="/api/networks"/>
  <link rel="roles" href="/api/roles"/>
  <link rel="storagedomains" href="/api/storagedomains"/>
  <link rel="storagedomains/search" href="/api/storagedomains?search={query}"/>
  <link rel="tags" href="/api/tags"/>
  <link rel="templates" href="/api/templates"/>
  <link rel="templates/search" href="/api/templates?search={query}"/>
  <link rel="users" href="/api/users"/>
  <link rel="groups" href="/api/groups"/>
  <link rel="domains" href="/api/domains"/>
  <link rel="vmpools" href="/api/vmpools"/>
  <link rel="vmpools/search" href="/api/vmpools?search={query}"/>
  <link rel="vms" href="/api/vms"/>
  <link rel="vms/search" href="/api/vms?search={query}"/>
  <product_info>
    <name>oVirt Engine</name>
    <vendor>ovirt.org</vendor>
    <version>
      <build>4</build>
      <full_version>4.0.4</full_version>
      <major>4</major>
      <minor>0</minor>
      <revision>0</revision>
    </version>
  </product_info>
  <special_objects>
    <blank_template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <root_tag href="/ovirt-engine/api/tags/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
  </special_objects>
  <summary>
    <hosts>
      <active>0</active>
      <total>0</total>
    </hosts>
    <storage_domains>
      <active>0</active>
      <total>1</total>
    </storage_domains>
    <users>
      <active>1</active>
      <total>1</total>
    </users>
    <vms>
      <active>0</active>
      <total>0</total>
    </vms>
  </summary>
  <time>2016-09-14T12:00:48.132+02:00</time>
</api>

The entry point provides a user with links to the collections in a virtualization environment. The rel attribute of each collection link provides a reference point for each link.

The entry point also contains other data such as product_info, special_objects and summary.

Table 683. Parameters summary
Name Type Direction Summary

api

Api

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.

reloadconfigurations POST

Table 684. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the reload should be performed asynchronously.

SystemOption

A service that provides values of specific configuration option of the system.

Table 685. Methods summary
Name Summary

get

Get the values of specific configuration option.

get GET

Get the values of specific configuration option.

For example to retrieve the values of configuration option MigrationPolicies send a request like this:

GET /ovirt-engine/api/options/MigrationPolicies

The response to that request will be the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<system_option href="/ovirt-engine/api/options/MigrationPolicies" id="MigrationPolicies">
    <name>MigrationPolicies</name>
    <values>
        <system_option_value>
            <value>[{"id":{"uuid":"80554327-0569-496b-bdeb-fcbbf52b827b"},...}]</value>
            <version>4.2</version>
        </system_option_value>
        <system_option_value>
            <value>[{"id":{"uuid":"80554327-0569-496b-bdeb-fcbbf52b827b"},...}]</value>
            <version>4.3</version>
        </system_option_value>
        <system_option_value>
            <value>[{"id":{"uuid":"80554327-0569-496b-bdeb-fcbbf52b827b"},...}]</value>
            <version>4.4</version>
        </system_option_value>
        <system_option_value>
            <value>[{"id":{"uuid":"80554327-0569-496b-bdeb-fcbbf52b827b"},...}]</value>
            <version>4.5</version>
        </system_option_value>
        <system_option_value>
            <value>[{"id":{"uuid":"80554327-0569-496b-bdeb-fcbbf52b827b"},...}]</value>
            <version>4.6</version>
        </system_option_value>
        <system_option_value>
            <value>[{"id":{"uuid":"80554327-0569-496b-bdeb-fcbbf52b827b"},...}]</value>
            <version>4.7</version>
        </system_option_value>
    </values>
</system_option>
The appropriate permissions are required to query configuration options. Some options can be queried only by users with administrator permissions.

There is NO backward compatibility and no guarantee about the names or values of the options. Options may be removed and their meaning can be changed at any point.

We strongly discourage the use of this service for applications other than the ones that are released simultaneously with the engine. Usage by other applications is not supported. Therefore there will be no documentation listing accessible configuration options.
Table 686. Parameters summary
Name Type Direction Summary

option

SystemOption

Out

The returned configuration option of the system.

version

String

In

Optional version parameter that specifies that only particular version of the configuration option should be returned.

version

Optional version parameter that specifies that only particular version of the configuration option should be returned. If this parameter isn’t used then all the versions will be returned.

For example, to get the value of the MigrationPolicies option but only for version 4.2 send a request like this:

GET /ovirt-engine/api/options/MigrationPolicies?version=4.2

The response to that request will be like this:

<system_option href="/ovirt-engine/api/options/MigrationPolicies" id="MigrationPolicies">
    <name>MigrationPolicies</name>
    <values>
        <system_option_value>
            <value>[{"id":{"uuid":"80554327-0569-496b-bdeb-fcbbf52b827b"},...}]</value>
            <version>4.2</version>
        </system_option_value>
    </values>
</system_option>

SystemOptions

Service that provides values of configuration options of the system.

SystemPermissions

This service doesn’t add any new methods, it is just a placeholder for the annotation that specifies the path of the resource that manages the permissions assigned to the system object.

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

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

permission

Permission

In/Out

The permission.

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

Tag

A service to manage a specific tag in the system.

Table 690. Methods summary
Name Summary

get

Gets the information about the tag.

remove

Removes the tag from the system.

update

Updates the tag entity.

get GET

Gets the information about the tag.

For example to retrieve the information about the tag with the id 123 send a request like this:

GET /ovirt-engine/api/tags/123
<tag href="/ovirt-engine/api/tags/123" id="123">
  <name>root</name>
  <description>root</description>
</tag>
Table 691. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

tag

Tag

Out

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

remove DELETE

Removes the tag from the system.

For example to remove the tag with id 123 send a request like this:

DELETE /ovirt-engine/api/tags/123
Table 692. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates the tag entity.

For example to update parent tag to tag with id 456 of the tag with id 123 send a request like this:

PUT /ovirt-engine/api/tags/123

With request body like:

<tag>
  <parent id="456"/>
</tag>

You may also specify a tag name instead of id. For example to update parent tag to tag with name mytag of the tag with id 123 send a request like this:

<tag>
  <parent>
    <name>mytag</name>
  </parent>
</tag>
Table 693. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

tag

Tag

In/Out

The updated tag.

Tags

Represents a service to manage collection of the tags in the system.

Table 694. Methods summary
Name Summary

add

Add a new tag to the system.

list

List the tags in the system.

add POST

Add a new tag to the system.

For example, to add new tag with name mytag to the system send a request like this:

POST /ovirt-engine/api/tags

With a request body like this:

<tag>
  <name>mytag</name>
</tag>
The root tag is a special pseudo-tag assumed as the default parent tag if no parent tag is specified. The root tag cannot be deleted nor assigned a parent tag.

To create new tag with specific parent tag send a request body like this:

<tag>
  <name>mytag</name>
  <parent>
    <name>myparenttag</name>
  </parent>
</tag>
Table 695. Parameters summary
Name Type Direction Summary

tag

Tag

In/Out

The added tag.

list GET

List the tags in the system.

For example to list the full hierarchy of the tags in the system send a request like this:

GET /ovirt-engine/api/tags
<tags>
  <tag href="/ovirt-engine/api/tags/222" id="222">
    <name>root2</name>
    <description>root2</description>
    <parent href="/ovirt-engine/api/tags/111" id="111"/>
  </tag>
  <tag href="/ovirt-engine/api/tags/333" id="333">
    <name>root3</name>
    <description>root3</description>
    <parent href="/ovirt-engine/api/tags/222" id="222"/>
  </tag>
  <tag href="/ovirt-engine/api/tags/111" id="111">
    <name>root</name>
    <description>root</description>
  </tag>
</tags>

In the previous XML output you can see the following hierarchy of the tags:

root:        (id: 111)
  - root2    (id: 222)
    - root3  (id: 333)

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

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

List of all tags in the system.

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.

Template

Manages the virtual machine template and template versions.

Table 697. Methods summary
Name Summary

export

Exports a template to the data center export domain.

get

Returns the information about this template or template version.

remove

Removes a virtual machine template.

update

Updates the template.

export POST

Exports a template to the data center export domain.

For example, send the following request:

POST /ovirt-engine/api/templates/123/export

With a request body like this:

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

Since version 4.2 of the engine it is also possible to export a template as a virtual appliance (OVA). For example, to export template 123 as an OVA file named myvm.ova that is placed in the directory /home/ovirt/ on host myhost:

POST /ovirt-engine/api/templates/123/export

With a request body like this:

<action>
  <host>
    <name>myhost</name>
  </host>
  <directory>/home/ovirt</directory>
  <filename>myvm.ova</filename>
</action>
Table 698. Parameters summary
Name Type Direction Summary

exclusive

Boolean

In

Indicates if the existing templates with the same name should be overwritten.

storage_domain

StorageDomain

In

Specifies the destination export storage domain.

exclusive

Indicates if the existing templates with the same name should be overwritten.

The export action reports a failed action if a template of the same name exists in the destination domain. Set this parameter to true to change this behavior and overwrite any existing template.

get GET

Returns the information about this template or template version.

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

template

Template

Out

The information about the template or template version.

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.

remove DELETE

Removes a virtual machine template.

DELETE /ovirt-engine/api/templates/123
Table 700. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

update PUT

Updates the template.

The name, description, type, memory, cpu, topology, os, high_availability, display, stateless, usb, and timezone elements can be updated after a template has been created.

For example, to update a template so that it has 1 GiB of memory send a request like this:

PUT /ovirt-engine/api/templates/123

With the following request body:

<template>
  <memory>1073741824</memory>
</template>

The version_name name attribute is the only one that can be updated within the version attribute used for template versions:

<template>
  <version>
    <version_name>mytemplate_2</version_name>
  </version>
</template>
Table 701. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

template

Template

In/Out

TemplateCdrom

A service managing a CD-ROM device on templates.

Table 702. Methods summary
Name Summary

get

Returns the information about this CD-ROM device.

get GET

Returns the information about this CD-ROM device.

For example, to get information about the CD-ROM device of template 123 send a request like:

GET /ovirt-engine/api/templates/123/cdroms/
Table 703. Parameters summary
Name Type Direction Summary

cdrom

Cdrom

Out

The information about the CD-ROM device.

follow

String

In

Indicates which inner links should be followed.

cdrom

The information about the CD-ROM device.

The information consists of cdrom attribute containing reference to the CD-ROM device, the template, and optionally the inserted disk.

If there is a disk inserted then the file attribute will contain a reference to the ISO image:

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <template href="/ovirt-engine/api/templates/123" id="123"/>
  <file id="mycd.iso"/>
</cdrom>

If there is no disk inserted then the file attribute won’t be reported:

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <template href="/ovirt-engine/api/templates/123" id="123"/>
</cdrom>

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.

TemplateCdroms

Lists the CD-ROM devices of a template.

Table 704. Methods summary
Name Summary

list

Returns the list of CD-ROM devices of the template.

list GET

Returns the list of CD-ROM devices of the template.

The order of the returned list of CD-ROM devices isn’t guaranteed.

Table 705. Parameters summary
Name Type Direction Summary

cdroms

Cdrom[]

Out

The list of CD-ROM devices of the template.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of CD-ROMs 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 CD-ROMs to return. If not specified all the CD-ROMs are returned.

TemplateDisk

Table 706. Methods summary
Name Summary

copy

Copy the specified disk attached to the template to a specific storage domain.

export

get

remove

copy POST

Copy the specified disk attached to the template to a specific storage domain.

Table 707. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

filter

Boolean

In

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

storage_domain

StorageDomain

In

export POST

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

get GET

Table 709. Parameters summary
Name Type Direction Summary

disk

Disk

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.

remove DELETE

Table 710. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

TemplateDiskAttachment

This service manages the attachment of a disk to a template.

Table 711. Methods summary
Name Summary

get

Returns the details of the attachment.

remove

Removes the disk from the template.

get GET

Returns the details of the attachment.

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

remove DELETE

Removes the disk from the template. The disk will only be removed if there are other existing copies of the disk on other storage domains.

A storage domain has to be specified to determine which of the copies should be removed (template disks can have copies on multiple storage domains).

DELETE /ovirt-engine/api/templates/{template:id}/diskattachments/{attachment:id}?storage_domain=072fbaa1-08f3-4a40-9f34-a5ca22dd1d74
Table 713. Parameters summary
Name Type Direction Summary

force

Boolean

In

storage_domain

String

In

Specifies the identifier of the storage domain the image to be removed resides on.

TemplateDiskAttachments

This service manages the set of disks attached to a template. Each attached disk is represented by a DiskAttachment.

Table 714. Methods summary
Name Summary

list

List the disks that are attached to the template.

list GET

List the disks that are attached to the template.

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

Table 715. Parameters summary
Name Type Direction Summary

attachments

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.

TemplateDisks

Table 716. Methods summary
Name Summary

list

Returns the list of disks of the template.

list GET

Returns the list of disks of the template.

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

Table 717. Parameters summary
Name Type Direction Summary

disks

Disk[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of disks 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 disks to return. If not specified all the disks are returned.

TemplateGraphicsConsole

Table 718. Methods summary
Name Summary

get

Gets graphics console configuration of the template.

remove

Remove the graphics console from the template.

get GET

Gets graphics console configuration of the template.

Table 719. Parameters summary
Name Type Direction Summary

console

GraphicsConsole

Out

The information about the graphics console of the template.

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.

remove DELETE

Remove the graphics console from the template.

Table 720. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

TemplateGraphicsConsoles

Table 721. Methods summary
Name Summary

add

Add new graphics console to the template.

list

Lists all the configured graphics consoles of the template.

add POST

Add new graphics console to the template.

Table 722. Parameters summary
Name Type Direction Summary

console

GraphicsConsole

In/Out

list GET

Lists all the configured graphics consoles of the template.

The order of the returned list of graphics consoles isn’t guaranteed.

Table 723. Parameters summary
Name Type Direction Summary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the template.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of consoles 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 consoles to return. If not specified all the consoles are returned.

TemplateMediatedDevice

Table 724. Methods summary
Name Summary

get

Gets mediated device configuration of the template.

remove

Remove the mediated device from the template.

update

Updates the information about the mediated device.

get GET

Gets mediated device configuration of the template.

Table 725. Parameters summary
Name Type Direction Summary

device

VmMediatedDevice

Out

The information about the mediated device of the template.

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.

remove DELETE

Remove the mediated device from the template.

Table 726. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates the information about the mediated device.

You can update the information using specParams element.

For example, to update a mediated device, send a request like this:

PUT /ovirt-engine/api/templates/123/mediateddevices/00000000-0000-0000-0000-000000000000
<vm_mediated_device>
  <spec_params>
    <property>
      <name>mdevType</name>
      <value>nvidia-11</value>
    </property>
  </spec_params>
</vm_mediated_device>

with response body:

<vm_mediated_device href="/ovirt-engine/api/templates/123/mediateddevices/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <template href="/ovirt-engine/api/templates/123" id="123"/>
  <spec_params>
    <property>
      <name>mdevType</name>
      <value>nvidia-11</value>
    </property>
  </spec_params>
</vm_mediated_device>
Table 727. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

devices

VmMediatedDevice

In/Out

The information about the mediated device.

devices

The information about the mediated device.

The request data must contain specParams properties. The response data contains complete information about the updated mediated device.

TemplateMediatedDevices

A service that manages mediated devices of a template.

Table 728. Methods summary
Name Summary

add

Add new mediated device to the template.

list

Lists all the configured mediated devices of the template.

add POST

Add new mediated device to the template.

Table 729. Parameters summary
Name Type Direction Summary

device

VmMediatedDevice

In/Out

list GET

Lists all the configured mediated devices of the template.

The order of the returned list of mediated devices isn’t guaranteed.

Table 730. Parameters summary
Name Type Direction Summary

devices

VmMediatedDevice[]

Out

The list of mediated devices of the template.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of mediated devices 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 mediated devices to return. If not specified all the mediated devices are returned.

TemplateNic

Table 731. Methods summary
Name Summary

get

remove

update

Update the specified network interface card attached to the template.

get GET

Table 732. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

nic

Nic

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.

remove DELETE

Table 733. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update the specified network interface card attached to the template.

Table 734. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

TemplateNics

Table 735. Methods summary
Name Summary

add

Add a new network interface card to the template.

list

Returns the list of NICs of the template.

add POST

Add a new network interface card to the template.

Table 736. Parameters summary
Name Type Direction Summary

nic

Nic

In/Out

list GET

Returns the list of NICs of the template.

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

Table 737. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

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 NICs to return. If not specified all the NICs are returned.

TemplateWatchdog

Table 738. Methods summary
Name Summary

get

remove

update

Update the watchdog for the template identified by the given id.

get GET

Table 739. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

watchdog

Watchdog

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.

remove DELETE

Table 740. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update the watchdog for the template identified by the given id.

Table 741. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

TemplateWatchdogs

Table 742. Methods summary
Name Summary

add

Add a watchdog to the template identified by the given id.

list

Returns the list of watchdogs.

add POST

Add a watchdog to the template identified by the given id.

Table 743. Parameters summary
Name Type Direction Summary

watchdog

Watchdog

In/Out

list GET

Returns the list of watchdogs.

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

Table 744. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of watchdogs to return.

watchdogs

Watchdog[]

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 watchdogs to return. If not specified all the watchdogs are returned.

Templates

This service manages the virtual machine templates available in the system.

Table 745. Methods summary
Name Summary

add

Creates a new template.

list

Returns the list of virtual machine templates.

add POST

Creates a new template.

This requires the name and vm elements. To identify the virtual machine use the vm.id or vm.name attributes. For example, to create a template from a virtual machine with the identifier 123 send a request like this:

POST /ovirt-engine/api/templates

With a request body like this:

<template>
  <name>mytemplate</name>
  <vm id="123"/>
</template>

Since version 4.3, in order to create virtual machine template from a snapshot send a request body like this:

<template>
  <name>mytemplate</name>
  <vm id="123">
    <snapshots>
      <snapshot id="456"/>
    </snapshots>
  </vm>
</template>

The disks of the template can be customized, making some of their characteristics different from the disks of the original virtual machine. To do so use the vm.disk_attachments attribute, specifying the identifier of the disk of the original virtual machine and the characteristics that you want to change. For example, if the original virtual machine has a disk with the identifier 456, and, for that disk, you want to change the name to mydisk the format to Copy On Write and make it sparse, send a request body like this:

<template>
  <name>mytemplate</name>
  <vm id="123">
    <disk_attachments>
      <disk_attachment>
        <disk id="456">
          <name>mydisk</name>
          <format>cow</format>
          <sparse>true</sparse>
        </disk>
      </disk_attachment>
    </disk_attachments>
  </vm>
</template>

The template can be created as a sub-version of an existing template. This requires the name and vm attributes for the new template, and the base_template and version_name attributes for the new template version. The base_template and version_name attributes must be specified within a version section enclosed in the template section. Identify the virtual machine with the id or name attributes.

<template>
  <name>mytemplate</name>
  <vm id="123"/>
  <version>
    <base_template id="456"/>
    <version_name>mytemplate_001</version_name>
  </version>
</template>

The destination storage domain of the template can be customized, in one of two ways:

  1. Globally, at the request level. The request must list the desired disk attachments to be created on the storage domain. If the disk attachments are not listed, the global storage domain parameter will be ignored.

    <template>
  <name>mytemplate</name>
  <storage_domain id="123"/>
  <vm id="456">
    <disk_attachments>
      <disk_attachment>
        <disk id="789">
          <format>cow</format>
          <sparse>true</sparse>
        </disk>
      </disk_attachment>
    </disk_attachments>
  </vm>
</template>

  2. Per each disk attachment. Specify the desired storage domain for each disk attachment. Specifying the global storage definition will override the storage domain per disk attachment specification.

    <template>
  <name>mytemplate</name>
  <vm id="123">
    <disk_attachments>
      <disk_attachment>
        <disk id="456">
          <format>cow</format>
          <sparse>true</sparse>
          <storage_domains>
             <storage_domain id="789"/>
          </storage_domains>
        </disk>
      </disk_attachment>
    </disk_attachments>
  </vm>
</template>
Table 746. Parameters summary
Name Type Direction Summary

clone_permissions

Boolean

In

Specifies if the permissions of the virtual machine should be copied to the template.

seal

Boolean

In

Seals the template.

template

Template

In/Out

The information about the template or template version.

clone_permissions

Specifies if the permissions of the virtual machine should be copied to the template.

If this optional parameter is provided, and its value is true, then the permissions of the virtual machine (only the direct ones, not the inherited ones) will be copied to the created template. For example, to create a template from the myvm virtual machine copying its permissions, send a request like this:

POST /ovirt-engine/api/templates?clone_permissions=true

With a request body like this:

<template>
  <name>mytemplate<name>
  <vm>
    <name>myvm<name>
  </vm>
</template>

seal

Seals the template.

If this optional parameter is provided and its value is true, then the template is sealed after creation.

Sealing erases all host-specific configuration from the filesystem: SSH keys, UDEV rules, MAC addresses, system ID, hostname, and so on, thus making it easier to use the template to create multiple virtual machines without manual intervention.

Currently, sealing is supported only for Linux operating systems.

list GET

Returns the list of virtual machine templates.

For example:

GET /ovirt-engine/api/templates

Will return the list of virtual machines and virtual machine templates.

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

Table 747. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

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

filter

Boolean

In

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

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of templates to return.

search

String

In

A query string used to restrict the returned templates.

templates

Template[]

Out

The list of virtual machine templates.

case_sensitive

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

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 templates to return. If not specified, all the templates are returned.

UnmanagedNetwork

Table 748. Methods summary
Name Summary

get

remove

get GET

Table 749. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

network

UnmanagedNetwork

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.

remove DELETE

Table 750. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

UnmanagedNetworks

Table 751. Methods summary
Name Summary

list

Returns the list of unmanaged networks of the host.

list GET

Returns the list of unmanaged networks of the host.

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

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

UnmanagedNetwork[]

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 networks to return. If not specified all the networks are returned.

User

A service to manage a user in the system. Use this service to either get users details or remove users. In order to add new users please use users.

Table 753. Methods summary
Name Summary

get

Gets the system user information.

remove

Removes the system user.

update

Updates information about the user.

get GET

Gets the system user information.

Usage:

GET /ovirt-engine/api/users/1234

Will return the user information:

<user href="/ovirt-engine/api/users/1234" id="1234">
  <name>admin</name>
  <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/>
  <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/>
  <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/>
  <department></department>
  <domain_entry_id>23456</domain_entry_id>
  <email>user1@domain.com</email>
  <last_name>Lastname</last_name>
  <namespace>*</namespace>
  <principal>user1</principal>
  <user_name>user1@domain-authz</user_name>
  <domain href="/ovirt-engine/api/domains/45678" id="45678">
    <name>domain-authz</name>
  </domain>
</user>
Table 754. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

user

User

Out

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

remove DELETE

Removes the system user.

Usage:

DELETE /ovirt-engine/api/users/1234
Table 755. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates information about the user.

Only the user_options field can be updated.

For example, to update user options:

PUT /ovirt-engine/api/users/123

With a request body like this:

<user>
   <user_options>
      <property>
         <name>test</name>
         <value>["any","JSON"]</value>
      </property>
   </user_options>
</user>
Since version 4.4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. Please use the options endpoint instead.
Table 756. Parameters summary
Name Type Direction Summary

user

User

In/Out

UserOption

Table 757. Methods summary
Name Summary

get

Returns a user profile property of type JSON.

remove

Deletes an existing property of type JSON.

get GET

Returns a user profile property of type JSON.

Example request(for user with identifier 123 and option with identifier 456):

GET /ovirt-engine/api/users/123/options/456

The result will be the following XML document:

  <user_option href="/ovirt-engine/api/users/123/options/456" id="456">
    <name>SomeName</name>
    <content>["any", "JSON"]</content>
    <user href="/ovirt-engine/api/users/123" id="123"/>
  </user_option>
Table 758. Parameters summary
Name Type Direction Summary

option

UserOption

Out

remove DELETE

Deletes an existing property of type JSON.

Example request(for user with identifier 123 and option with identifier 456):

DELETE /ovirt-engine/api/users/123/options/456

UserOptions

Table 759. Methods summary
Name Summary

add

Adds a new user profile property of type JSON.

list

Returns a list of user profile properties of type JSON.

add POST

Adds a new user profile property of type JSON.

Example request(for user with identifier 123):

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

Payload:

  <user_option>
    <name>SomeName</name>
    <content>["any", "JSON"]</content>
  </user_option>
Table 760. Parameters summary
Name Type Direction Summary

option

UserOption

In/Out

list GET

Returns a list of user profile properties of type JSON.

Example request(for user with identifier 123):

GET /ovirt-engine/api/users/123/options

The result will be the following XML document:

<user_options>
  <user_option href="/ovirt-engine/api/users/123/options/456" id="456">
    <name>SomeName</name>
    <content>["any", "JSON"]</content>
    <user href="/ovirt-engine/api/users/123" id="123"/>
  </user_option>
</user_options>
Table 761. Parameters summary
Name Type Direction Summary

options

UserOption[]

Out

Users

A service to manage the users in the system.

Table 762. Methods summary
Name Summary

add

Add user from a directory service.

list

List all the users in the system.

add POST

Add user from a directory service.

For example, to add the myuser user from the myextension-authz authorization provider send a request like this:

POST /ovirt-engine/api/users

With a request body like this:

<user>
  <user_name>myuser@myextension-authz</user_name>
  <domain>
    <name>myextension-authz</name>
  </domain>
</user>

In case you are working with Active Directory you have to pass user principal name (UPN) as username, followed by authorization provider name. Due to bug 1147900 you need to provide also principal parameter set to UPN of the user.

For example, to add the user with UPN myuser@mysubdomain.mydomain.com from the myextension-authz authorization provider send a request body like this:

<user>
  <principal>myuser@mysubdomain.mydomain.com</principal>
  <user_name>myuser@mysubdomain.mydomain.com@myextension-authz</user_name>
  <domain>
    <name>myextension-authz</name>
  </domain>
</user>
Table 763. Parameters summary
Name Type Direction Summary

user

User

In/Out

list GET

List all the users in the system.

Usage:

GET /ovirt-engine/api/users

Will return the list of users:

<users>
  <user href="/ovirt-engine/api/users/1234" id="1234">
    <name>admin</name>
    <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/>
    <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/>
    <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/>
    <domain_entry_id>23456</domain_entry_id>
    <namespace>*</namespace>
    <principal>user1</principal>
    <user_name>user1@domain-authz</user_name>
    <domain href="/ovirt-engine/api/domains/45678" id="45678">
      <name>domain-authz</name>
    </domain>
  </user>
</users>

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

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

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.

VirtualFunctionAllowedNetwork

Table 765. Methods summary
Name Summary

get

remove

get GET

Table 766. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

network

Network

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.

remove DELETE

Table 767. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

VirtualFunctionAllowedNetworks

Table 768. Methods summary
Name Summary

add

list

Returns the list of networks.

add POST

Table 769. Parameters summary
Name Type Direction Summary

network

Network

In/Out

list GET

Returns the list of networks.

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

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

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.

Vm

Table 771. Methods summary
Name Summary

autopincpuandnumanodes

Apply an automatic CPU and NUMA configuration on the VM.

cancelmigration

This operation stops any migration of a virtual machine to another physical host.

clone

commitsnapshot

Permanently restores the virtual machine to the state of the previewed snapshot.

detach

Detaches a virtual machine from a pool.

export

Exports the virtual machine.

freezefilesystems

Freezes virtual machine file systems.

get

Retrieves the description of the virtual machine.

logon

Initiates the automatic user logon to access a virtual machine from an external console.

maintenance

Sets the global maintenance mode on the hosted engine virtual machine.

migrate

Migrates a virtual machine to another physical host.

previewsnapshot

Temporarily restores the virtual machine to the state of a snapshot.

reboot

Sends a reboot request to a virtual machine.

remove

Removes the virtual machine, including the virtual disks attached to it.

reordermacaddresses

reset

Sends a reset request to a virtual machine.

screenshot

Captures screenshot of the current state of the VM.

shutdown

This operation sends a shutdown request to a virtual machine.

start

Starts the virtual machine.

stop

This operation forces a virtual machine to power-off.

suspend

This operation saves the virtual machine state to disk and stops it.

thawfilesystems

Thaws virtual machine file systems.

ticket

Generates a time-sensitive authentication token for accessing a virtual machine’s display.

undosnapshot

Restores the virtual machine to the state it had before previewing the snapshot.

update

Update the virtual machine in the system for the given virtual machine id.

autopincpuandnumanodes POST

Apply an automatic CPU and NUMA configuration on the VM.

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. Instead please use PUT followed by update operation.

An example for a request:

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

With a request body like this:

<action>
  <optimize_cpu_settings>true</optimize_cpu_settings>
</action>
Table 772. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the detach action should be performed asynchronously.

optimize_cpu_settings

Boolean

In

Specifies how the auto CPU and NUMA configuration is applied.

optimize_cpu_settings

Specifies how the auto CPU and NUMA configuration is applied. If set to true, will adjust the CPU topology to fit the VM pinned host hardware. Otherwise, it will use the VM CPU topology.

cancelmigration POST

This operation stops any migration of a virtual machine to another physical host.

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

The cancel migration action does not take any action specific parameters; therefore, the request body should contain an empty action:

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

async

Boolean

In

Indicates if the migration should cancelled asynchronously.

clone POST

Table 774. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the clone should be performed asynchronously.

discard_snapshots

Boolean

In

Use the discard_snapshots parameter when the virtual machine should be clone with its snapshots collapsed.

storage_domain

StorageDomain

In

The storage domain on which the virtual machines disks will be copied to.

vm

Vm

In

discard_snapshots

Use the discard_snapshots parameter when the virtual machine should be clone with its snapshots collapsed. Default is true.

commitsnapshot POST

Permanently restores the virtual machine to the state of the previewed snapshot.

See the preview_snapshot operation for details.

Table 775. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the snapshots should be committed asynchronously.

detach POST

Detaches a virtual machine from a pool.

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

The detach action does not take any action specific parameters; therefore, the request body should contain an empty action:

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

async

Boolean

In

Indicates if the detach action should be performed asynchronously.

export POST

Exports the virtual machine.

A virtual machine can be exported to an export domain. For example, to export virtual machine 123 to the export domain myexport:

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

With a request body like this:

<action>
  <storage_domain>
    <name>myexport</name>
  </storage_domain>
  <exclusive>true</exclusive>
  <discard_snapshots>true</discard_snapshots>
</action>

Since version 4.2 of the engine it is also possible to export a virtual machine as a virtual appliance (OVA). For example, to export virtual machine 123 as an OVA file named myvm.ova that is placed in the directory /home/ovirt/ on host myhost:

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

With a request body like this:

<action>
  <host>
    <name>myhost</name>
  </host>
  <directory>/home/ovirt</directory>
  <filename>myvm.ova</filename>
</action>
Confirm that the export operation has completed before attempting any actions on the export domain.
Table 777. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the export should be performed asynchronously.

discard_snapshots

Boolean

In

Use the discard_snapshots parameter when the virtual machine should be exported with all of its snapshots collapsed.

exclusive

Boolean

In

Use the exclusive parameter when the virtual machine should be exported even if another copy of it already exists in the export domain (override).

storage_domain

StorageDomain

In

The (export) storage domain to export the virtual machine to.

freezefilesystems POST

Freezes virtual machine file systems.

This operation freezes a virtual machine’s file systems using the QEMU guest agent when taking a live snapshot of a running virtual machine. Normally, this is done automatically by the manager, but this must be executed manually with the API for virtual machines using OpenStack Volume (Cinder) disks.

Example:

POST /ovirt-engine/api/vms/123/freezefilesystems
<action/>
Table 778. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the freeze should be performed asynchronously.

get GET

Retrieves the description of the virtual machine.

Table 779. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

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

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.

next_run

Boolean

In

Indicates if the returned result describes the virtual machine as it is currently running or if describes the virtual machine with the modifications that have already been performed but that will only come into effect when the virtual machine is restarted.

ovf_as_ova

Boolean

In

Indicates if the results should expose the OVF as it appears in OVA files of that VM.

vm

Vm

Out

Description of the virtual machine.

all_content

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

By default the following attributes are excluded:

  • console

  • initialization.configuration.data - The OVF document describing the virtual machine.

  • rng_source

  • soundcard

  • virtio_scsi

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

GET /ovirt-engine/api/vms/123?all_content=true
These attributes are not included by default as they reduce performance. These attributes are seldom used and require additional queries to the database. Only use this parameter when required as it will reduce performance.

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.

next_run

Indicates if the returned result describes the virtual machine as it is currently running or if describes the virtual machine with the modifications that have already been performed but that will only come into effect when the virtual machine is restarted. By default the value is false.

If the parameter is included in the request, but without a value, it is assumed that the value is true. The the following request:

GET /vms/{vm:id};next_run

Is equivalent to using the value true:

GET /vms/{vm:id};next_run=true

ovf_as_ova

Indicates if the results should expose the OVF as it appears in OVA files of that VM. The OVF document describing the virtual machine. This parameter will work only when all_content=True is set. The OVF will be presented in initialization.configuration.data.

For example:

GET /vms/{vm:id}?all_content=true&ovf_as_ova=true

logon POST

Initiates the automatic user logon to access a virtual machine from an external console.

This action requires the ovirt-guest-agent-gdm-plugin and the ovirt-guest-agent-pam-module packages to be installed and the ovirt-guest-agent service to be running on the virtual machine.

Users require the appropriate user permissions for the virtual machine in order to access the virtual machine from an external console.

For example:

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

Request body:

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

async

Boolean

In

Indicates if the logon should be performed asynchronously.

maintenance POST

Sets the global maintenance mode on the hosted engine virtual machine.

This action has no effect on other virtual machines.

Example:

POST /ovirt-engine/api/vms/123/maintenance
<action>
  <maintenance_enabled>true<maintenance_enabled/>
</action>
Table 781. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the global maintenance action should be performed asynchronously.

maintenance_enabled

Boolean

In

Indicates if global maintenance should be enabled or disabled.

migrate POST

Migrates a virtual machine to another physical host.

Example:

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

To specify a specific host to migrate the virtual machine to:

<action>
  <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>
Table 782. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the migration should be performed asynchronously.

cluster

Cluster

In

Specifies the cluster the virtual machine should migrate to.

force

Boolean

In

Specifies that the virtual machine should migrate even if the virtual machine is defined as non-migratable.

host

Host

In

Specifies a specific host that the virtual machine should migrate to.

migrate_vms_in_affinity_closure

Boolean

In

Migrate also all other virtual machines in positive enforcing affinity groups with this virtual machine, that are running on the same host.

cluster

Specifies the cluster the virtual machine should migrate to. This is an optional parameter. By default, the virtual machine is migrated to another host within the same cluster.

Live migration to another cluster is not supported. Strongly consider the target cluster’s hardware architecture and network architecture before attempting a migration.

force

Specifies that the virtual machine should migrate even if the virtual machine is defined as non-migratable. This is an optional parameter. By default, it is set to false.

host

Specifies a specific host that the virtual machine should migrate to. This is an optional parameter. By default, the {engine-name} automatically selects a default host for migration within the same cluster. If an API user requires a specific host, the user can specify the host with either an id or name parameter.

migrate_vms_in_affinity_closure

Migrate also all other virtual machines in positive enforcing affinity groups with this virtual machine, that are running on the same host.

The default value is false.

previewsnapshot POST

Temporarily restores the virtual machine to the state of a snapshot.

The snapshot is indicated with the snapshot.id parameter. It is restored temporarily, so that the content can be inspected. Once that inspection is finished, the state of the virtual machine can be made permanent, using the commit_snapshot method, or discarded using the undo_snapshot method.

Table 783. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the preview should be performed asynchronously.

disks

Disk[]

In

Specify the disks included in the snapshot’s preview.

lease

StorageDomainLease

In

Specify the lease storage domain ID to use in the preview of the snapshot.

restore_memory

Boolean

In

snapshot

Snapshot

In

vm

Vm

In

disks

Specify the disks included in the snapshot’s preview.

For each disk parameter, it is also required to specify its image_id.

For example, to preview a snapshot with identifier 456 which includes a disk with identifier 111 and its image_id as 222, send a request like this:

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

Request body:

<action>
  <disks>
    <disk id="111">
      <image_id>222</image_id>
    </disk>
  </disks>
  <snapshot id="456"/>
</action>

lease

Specify the lease storage domain ID to use in the preview of the snapshot. If lease parameter is not passed, then the previewed snapshot lease storage domain will be used. If lease parameter is passed with empty storage domain parameter, then no lease will be used for the snapshot preview. If lease parameter is passed with storage domain parameter then the storage domain ID can be only one of the leases domain IDs that belongs to one of the virtual machine snapshots. This is an optional parameter, set by default to null

reboot POST

Sends a reboot request to a virtual machine.

For example:

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

The reboot action does not take any action specific parameters; therefore, the request body should contain an empty action:

<action/>

To reboot the VM even if a backup is running for it, the action should include the 'force' element.

For example, to force reboot virtual machine 123:

POST /ovirt-engine/api/vms/123/reboot
<action>
    <force>true</force>
</action>
Table 784. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the reboot should be performed asynchronously.

force

Boolean

In

Indicates if the VM should be forcibly rebooted even if a backup is running for it.

remove DELETE

Removes the virtual machine, including the virtual disks attached to it.

For example, to remove the virtual machine with identifier 123:

DELETE /ovirt-engine/api/vms/123
Table 785. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

detach_only

Boolean

In

Indicates if the attached virtual disks should be detached first and preserved instead of being removed.

force

Boolean

In

Indicates if the virtual machine should be forcibly removed.

force

Indicates if the virtual machine should be forcibly removed.

Locked virtual machines and virtual machines with locked disk images cannot be removed without this flag set to true.

reordermacaddresses POST

Table 786. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the action should be performed asynchronously.

reset POST

Sends a reset request to a virtual machine.

For example:

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

The reset action does not take any action specific parameters; therefore, the request body should contain an empty action:

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

async

Boolean

In

Indicates if the reset should be performed asynchronously.

screenshot POST

Captures screenshot of the current state of the VM.

For example:

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

The screenshot action does not take any action specific parameters; therefore, the request body should contain an empty action:

<action/>

shutdown POST

This operation sends a shutdown request to a virtual machine.

For example:

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

The shutdown action does not take any action specific parameters; therefore, the request body should contain an empty action:

<action/>

To shutdown the VM even if a backup is running for it, the action should include the 'force' element.

For example, to force shutdown virtual machine 123:

POST /ovirt-engine/api/vms/123/shutdown
<action>
    <force>true</force>
</action>
Table 788. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the shutdown should be performed asynchronously.

force

Boolean

In

Indicates if the VM should be forcibly shutdown even if a backup is running for it.

reason

String

In

The reason the virtual machine was stopped.

reason

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual machine.

start POST

Starts the virtual machine.

If the virtual environment is complete and the virtual machine contains all necessary components to function, it can be started.

This example starts the virtual machine:

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

With a request body:

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

async

Boolean

In

Indicates if the start action should be performed asynchronously.

authorized_key

AuthorizedKey

In

filter

Boolean

In

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

pause

Boolean

In

If set to true, start the virtual machine in paused mode.

use_cloud_init

Boolean

In

If set to true, the initialization type is set to cloud-init.

use_ignition

Boolean

In

If set to true, the initialization type is set to Ignition.

use_initialization

Boolean

In

If set to true, the initialization type is set by the VM’s OS.

use_sysprep

Boolean

In

If set to true, the initialization type is set to Sysprep.

vm

Vm

In

The definition of the virtual machine for this specific run.

volatile

Boolean

In

Indicates that this run configuration will be discarded even in the case of guest-initiated reboot.

pause

If set to true, start the virtual machine in paused mode. The default is false.

use_cloud_init

If set to true, the initialization type is set to cloud-init. The default value is false. See cloud-init documentation for details.

use_ignition

If set to true, the initialization type is set to Ignition. The default value is false. See Ignition documentation for details.

use_initialization

If set to true, the initialization type is set by the VM’s OS. Windows will set to Sysprep, Linux to cloud-init and RedHat CoreOS to Ignition. If any of the initialization-types are explicitly set (useCloudInit, useSysprep or useIgnition), they will be prioritized and this flag will be ignored. The default value is false.

use_sysprep

If set to true, the initialization type is set to Sysprep. The default value is false. See Sysprep for details.

vm

The definition of the virtual machine for this specific run.

For example:

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

This will set the boot device to the CDROM only for this specific start. After the virtual machine is powered off, this definition will be reverted.

volatile

Indicates that this run configuration will be discarded even in the case of guest-initiated reboot. The default value is false.

stop POST

This operation forces a virtual machine to power-off.

For example:

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

The stop action does not take any action specific parameters; therefore, the request body should contain an empty action:

<action/>

To stop the VM even if a backup is running for it, the action should include the 'force' element.

For example, to force stop virtual machine 123:

POST /ovirt-engine/api/vms/123/stop
<action>
    <force>true</force>
</action>
Table 790. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the stop action should be performed asynchronously.

force

Boolean

In

Indicates if the VM should be forcibly stop even if a backup is running for it.

reason

String

In

The reason the virtual machine was stopped.

reason

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual machine.

suspend POST

This operation saves the virtual machine state to disk and stops it. Start a suspended virtual machine and restore the virtual machine state with the start action.

For example:

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

The suspend action does not take any action specific parameters; therefore, the request body should contain an empty action:

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

async

Boolean

In

Indicates if the suspend action should be performed asynchronously.

thawfilesystems POST

Thaws virtual machine file systems.

This operation thaws a virtual machine’s file systems using the QEMU guest agent when taking a live snapshot of a running virtual machine. Normally, this is done automatically by the manager, but this must be executed manually with the API for virtual machines using OpenStack Volume (Cinder) disks.

Example:

POST /api/vms/123/thawfilesystems
<action/>
Table 792. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the thaw file systems action should be performed asynchronously.

ticket POST

Generates a time-sensitive authentication token for accessing a virtual machine’s display.

For example:

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

The client-provided action optionally includes a desired ticket value and/or an expiry time in seconds.

The response specifies the actual ticket value and expiry used.

<action>
  <ticket>
    <value>abcd12345</value>
    <expiry>120</expiry>
  </ticket>
</action>

If the virtual machine is configured to support only one graphics protocol then the generated authentication token will be valid for that protocol. But if the virtual machine is configured to support multiple protocols, VNC and SPICE, then the authentication token will only be valid for the SPICE protocol.

In order to obtain an authentication token for a specific protocol, for example for VNC, use the ticket method of the service, which manages the graphics consoles of the virtual machine, by sending a request:

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/ticket
Table 793. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the generation of the ticket should be performed asynchronously.

ticket

Ticket

In/Out

undosnapshot POST

Restores the virtual machine to the state it had before previewing the snapshot.

See the preview_snapshot operation for details.

Table 794. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the undo snapshot action should be performed asynchronously.

update PUT

Update the virtual machine in the system for the given virtual machine id.

Table 795. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

next_run

Boolean

In

Indicates if the update should be applied to the virtual machine immediately or if it should be applied only when the virtual machine is restarted.

vm

Vm

In/Out

next_run

Indicates if the update should be applied to the virtual machine immediately or if it should be applied only when the virtual machine is restarted. The default value is false, so by default changes are applied immediately.

VmApplication

A service that provides information about an application installed in a virtual machine.

Table 796. Methods summary
Name Summary

get

Returns the information about the application.

get GET

Returns the information about the application.

Table 797. Parameters summary
Name Type Direction Summary

application

Application

Out

The information about the application.

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.

application

The information about the application.

The information consists of name attribute containing the name of the application (which is an arbitrary string that may also contain additional information such as version) and vm attribute identifying the virtual machine.

For example, a request like this:

GET /ovirt-engine/api/vms/123/applications/789

May return information like this:

<application href="/ovirt-engine/api/vms/123/applications/789" id="789">
  <name>ovirt-guest-agent-common-1.0.12-3.el7</name>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</application>

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.

VmApplications

A service that provides information about applications installed in a virtual machine.

Table 798. Methods summary
Name Summary

list

Returns a list of applications installed in the virtual machine.

list GET

Returns a list of applications installed in the virtual machine.

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

Table 799. Parameters summary
Name Type Direction Summary

applications

Application[]

Out

A list of applications installed in the virtual machine.

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 applications to return.

applications

A list of applications installed in the virtual machine.

For example, a request like this:

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

May return a list like this:

<applications>
  <application href="/ovirt-engine/api/vms/123/applications/456" id="456">
    <name>kernel-3.10.0-327.36.1.el7</name>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </application>
  <application href="/ovirt-engine/api/vms/123/applications/789" id="789">
    <name>ovirt-guest-agent-common-1.0.12-3.el7</name>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </application>
</applications>

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 applications to return. If not specified all the applications are returned.

VmBackup

A service managing a backup of a virtual machines.

Table 800. Methods summary
Name Summary

finalize

Finalize the virtual machine backup entity.

get

Returns information about the virtual machine backup.

finalize POST

Finalize the virtual machine backup entity.

End backup, unlock resources, and perform cleanups. To finalize a virtual machine with an id '123' and a backup with an id '456' send a request as follows:

POST /ovirt-engine/api/vms/123/backups/456/finalize

With a request body as follows:

<action />

get GET

Returns information about the virtual machine backup.

Table 801. Parameters summary
Name Type Direction Summary

backup

Backup

Out

The information about the virtual machine backup entities.

follow

String

In

Indicates which inner links should be followed.

backup

The information about the virtual machine backup entities.

<backups>
  <backup id="backup-uuid">
    <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
    <link href="/ovirt-engine/api/vms/vm-uuid/backups/backup-uuid/disks" rel="disks"/>
    <status>initializing</status>
    <creation_date>
 </backup>
</backups>

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.

VmBackupDisk

Table 802. Methods summary
Name Summary

get

Retrieves the description of the disk.

get GET

Retrieves the description of the disk.

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

VmBackupDisks

Table 804. Methods summary
Name Summary

list

Returns the list of disks in backup.

list GET

Returns the list of disks in backup.

Table 805. Parameters summary
Name Type Direction Summary

disks

Disk[]

Out

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

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.

VmBackups

Lists the backups of a virtual machine.

Table 806. Methods summary
Name Summary

add

Adds a new backup entity to a virtual machine.

list

The list of virtual machine backups.

add POST

Adds a new backup entity to a virtual machine.

For example, to start a new incremental backup of a virtual machine since checkpoint id previous-checkpoint-uuid, send a request like this:

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

With a request body like this:

<backup>
  <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
  <disks>
      <disk id="disk-uuid" />
      ...
  </disks>
</backup>

The response body:

<backup id="backup-uuid">
    <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
    <to_checkpoint_id>new-checkpoint-uuid</to_checkpoint_id>
    <disks>
        <disk id="disk-uuid" />
        ...
        ...
    </disks>
    <status>initializing</status>
    <creation_date>
</backup>

To provide the ID of the created backup, send a request like this:

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

With a request body like this:

<backup id="backup-uuid">
  <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
  <disks>
      <disk id="disk-uuid" />
      ...
  </disks>
</backup>
Table 807. Parameters summary
Name Type Direction Summary

backup

Backup

In/Out

The information about the virtual machine backup entity.

require_consistency

Boolean

In

Indicates if the backup will fail if VM failed to freeze or not.

use_active

Boolean

In

Indicate whether to use the active volume for performing the backup.

require_consistency

Indicates if the backup will fail if VM failed to freeze or not.

If requireConsistency=True VM backup will fail in case of a failure to freeze the VM.

The REST API call should look like this:

POST /ovirt-engine/api/vms/123/backups?require_consistency=true

The default value of the requireConsistency flag is false.

use_active

Indicate whether to use the active volume for performing the backup.

If useActive=False a snapshot will be created for the backup operation.

The REST API call should look like this:

POST /ovirt-engine/api/vms/123/backups?use_active=false

The default value of the useActive flag is false.

list GET

The list of virtual machine backups.

Table 808. Parameters summary
Name Type Direction Summary

backups

Backup[]

Out

The information about the virtual machine backup entities.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of virtual machine backups to return.

backups

The information about the virtual machine backup entities.

<backups>
  <backup id="backup-uuid">
    <from_checkpoint_id>previous-checkpoint-uuid</from_checkpoint_id>
    <disks>
      <disk id="disk-uuid" />
      ...
      ...
    </disks>
    <status>initiailizing</status>
    <creation_date>
 </backup>
</backups>

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 backups to return. If not specified, all the virtual machine backups are returned.

VmCdrom

Manages a CDROM device of a virtual machine.

Changing and ejecting the disk is done using always the update method, to change the value of the file attribute.

Table 809. Methods summary
Name Summary

get

Returns the information about this CDROM device.

update

Updates the information about this CDROM device.

get GET

Returns the information about this CDROM device.

The information consists of cdrom attribute containing reference to the CDROM device, the virtual machine, and optionally the inserted disk.

If there is a disk inserted then the file attribute will contain a reference to the ISO image:

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <file id="mycd.iso"/>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</cdrom>

If there is no disk inserted then the file attribute won’t be reported:

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</cdrom>
Table 810. Parameters summary
Name Type Direction Summary

cdrom

Cdrom

Out

The information about the CDROM device.

current

Boolean

In

Indicates if the operation should return the information for the currently running virtual machine.

follow

String

In

Indicates which inner links should be followed.

current

Indicates if the operation should return the information for the currently running virtual machine. This parameter is optional, and the default value is false.

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.

update PUT

Updates the information about this CDROM device.

It allows to change or eject the disk by changing the value of the file attribute. For example, to insert or change the disk send a request like this:

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000

The body should contain the new value for the file attribute:

<cdrom>
  <file id="mycd.iso"/>
</cdrom>

The value of the id attribute, mycd.iso in this example, should correspond to a file available in an attached ISO storage domain.

To eject the disk use a file with an empty id:

<cdrom>
  <file id=""/>
</cdrom>

By default the above operations change permanently the disk that will be visible to the virtual machine after the next boot, but they do not have any effect on the currently running virtual machine. If you want to change the disk that is visible to the current running virtual machine, add the current=true parameter. For example, to eject the current disk send a request like this:

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000?current=true

With a request body like this:

<cdrom>
  <file id=""/>
</cdrom>
The changes made with the current=true parameter are never persisted, so they won’t have any effect after the virtual machine is rebooted.
Table 811. Parameters summary
Name Type Direction Summary

cdrom

Cdrom

In/Out

The information about the CDROM device.

current

Boolean

In

Indicates if the update should apply to the currently running virtual machine, or to the virtual machine after the next boot.

current

Indicates if the update should apply to the currently running virtual machine, or to the virtual machine after the next boot. This parameter is optional, and the default value is false, which means that by default the update will have effect only after the next boot.

VmCdroms

Manages the CDROM devices of a virtual machine.

Currently virtual machines have exactly one CDROM device. No new devices can be added, and the existing one can’t be removed, thus there are no add or remove methods. Changing and ejecting CDROM disks is done with the update method of the service that manages the CDROM device.

Table 812. Methods summary
Name Summary

add

Add a cdrom to a virtual machine identified by the given id.

list

Returns the list of CDROM devices of the virtual machine.

add POST

Add a cdrom to a virtual machine identified by the given id.

Table 813. Parameters summary
Name Type Direction Summary

cdrom

Cdrom

In/Out

list GET

Returns the list of CDROM devices of the virtual machine.

The order of the returned list of CD-ROM devices isn’t guaranteed.

Table 814. Parameters summary
Name Type Direction Summary

cdroms

Cdrom[]

Out

The list of CDROM devices of the virtual machine.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of CDROMs 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 CDROMs to return. If not specified all the CDROMs are returned.

VmCheckpoint

A service managing a checkpoint of a virtual machines.

Table 815. Methods summary
Name Summary

get

Returns information about the virtual machine checkpoint.

remove

Remove the virtual machine checkpoint entity.

get GET

Returns information about the virtual machine checkpoint.

Table 816. Parameters summary
Name Type Direction Summary

checkpoint

Checkpoint

Out

The information about the virtual machine checkpoint entity.

follow

String

In

Indicates which inner links should be followed.

checkpoint

The information about the virtual machine checkpoint entity.

<checkpoint id="checkpoint-uuid">
 <link href="/ovirt-engine/api/vms/vm-uuid/checkpoints/checkpoint-uuid/disks" rel="disks"/>
 <parent_id>parent-checkpoint-uuid</parent_id>
 <creation_date>xxx</creation_date>
 <vm href="/ovirt-engine/api/vms/vm-uuid" id="vm-uuid"/>
</checkpoint>

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.

remove DELETE

Remove the virtual machine checkpoint entity.

Remove the checkpoint from libvirt and the database.

Table 817. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

VmCheckpointDisk

Table 818. Methods summary
Name Summary

get

Retrieves the description of the disk.

get GET

Retrieves the description of the disk.

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

VmCheckpointDisks

Table 820. Methods summary
Name Summary

list

Returns the list of disks in checkpoint.

list GET

Returns the list of disks in checkpoint.

Table 821. Parameters summary
Name Type Direction Summary

disks

Disk[]

Out

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

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.

VmCheckpoints

Lists the checkpoints of a virtual machine.

Table 822. Methods summary
Name Summary

list

The list of virtual machine checkpoints.

list GET

The list of virtual machine checkpoints.

To get a list of checkpoints for a virtual machine with an id '123', send a request as follows:

GET /ovirt-engine/api/vms/123/checkpoints
Table 823. Parameters summary
Name Type Direction Summary

checkpoints

Checkpoint[]

Out

The information about the virtual machine checkpoint entities.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of virtual machine checkpoints to return.

checkpoints

The information about the virtual machine checkpoint entities.

<checkpoints>
  <checkpoint id="checkpoint-uuid">
    <link href="/ovirt-engine/api/vms/vm-uuid/checkpoints/checkpoint-uuid/disks" rel="disks"/>
    <parent_id>parent-checkpoint-uuid</parent_id>
    <creation_date>xxx</creation_date>
    <vm href="/ovirt-engine/api/vm-uuid" id="vm-uuid"/>
 </checkpoint>
</checkpoints>

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 checkpoints to return. If not specified, all the virtual machine checkpoints are returned.

VmDisk

Table 824. Methods summary
Name Summary

activate

deactivate

export

get

move

reduce

Reduces the size of the disk image.

remove

Detach the disk from the virtual machine.

update

activate POST

Table 825. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

deactivate POST

Table 826. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

export POST

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

get GET

Table 828. Parameters summary
Name Type Direction Summary

disk

Disk

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.

move POST

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

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

async

Boolean

In

Indicates if the remove should be performed asynchronously.

remove DELETE

Detach the disk from the virtual machine.

In version 3 of the API this used to also remove the disk completely from the system, but starting with version 4 it doesn’t. If you need to remove it completely use the remove method of the top level disk service.
Table 831. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Table 832. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

disk

Disk

In/Out

VmDisks

Table 833. Methods summary
Name Summary

add

list

Returns the list of disks of the virtual machine.

add POST

Table 834. Parameters summary
Name Type Direction Summary

disk

Disk

In/Out

list GET

Returns the list of disks of the virtual machine.

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

Table 835. Parameters summary
Name Type Direction Summary

disks

Disk[]

Out

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of disks 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 disks to return. If not specified all the disks are returned.

VmGraphicsConsole

Table 836. Methods summary
Name Summary

get

Retrieves the graphics console configuration of the virtual machine.

proxyticket

remoteviewerconnectionfile

Generates the file which is compatible with remote-viewer client.

remove

Remove the graphics console from the virtual machine.

ticket

Generates a time-sensitive authentication token for accessing this virtual machine’s console.

get GET

Retrieves the graphics console configuration of the virtual machine.

By default, when the current parameter is not specified, the data returned corresponds to the next execution of the virtual machine. In the current implementation of the system this means that the address and port attributes will not be populated because the system does not know what address and port will be used for the next execution. Since in most cases those attributes are needed, it is strongly advised to aways explicitly include the current parameter with the value true.
Table 837. Parameters summary
Name Type Direction Summary

console

GraphicsConsole

Out

The information about the graphics console of the virtual machine.

current

Boolean

In

Specifies if the data returned should correspond to the next execution of the virtual machine, or to the current execution.

follow

String

In

Indicates which inner links should be followed.

current

Specifies if the data returned should correspond to the next execution of the virtual machine, or to the current execution.

The address and port attributes will not be populated unless the value is true.

For example, to get data for the current execution of the virtual machine, including the address and port attributes, send a request like this:

GET /ovit-engine/api/vms/123/graphicsconsoles/456?current=true

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

proxyticket POST

Table 838. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the generation of the ticket should be performed asynchronously.

proxy_ticket

ProxyTicket

Out

remoteviewerconnectionfile POST

Generates the file which is compatible with remote-viewer client.

Use the following request to generate remote viewer connection file of the graphics console. Note that this action generates the file only if virtual machine is running.

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/remoteviewerconnectionfile

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

<action/>

The response contains the file, which can be used with remote-viewer client.

<action>
  <remote_viewer_connection_file>
    [virt-viewer]
    type=spice
    host=192.168.1.101
    port=-1
    password=123456789
    delete-this-file=1
    fullscreen=0
    toggle-fullscreen=shift+f11
    release-cursor=shift+f12
    secure-attention=ctrl+alt+end
    tls-port=5900
    enable-smartcard=0
    enable-usb-autoshare=0
    usb-filter=null
    tls-ciphers=DEFAULT
    host-subject=O=local,CN=example.com
    ca=...
  </remote_viewer_connection_file>
</action>

E.g., to fetch the content of remote viewer connection file and save it into temporary file, user can use oVirt Python SDK as follows:

# Find the virtual machine:
vm = vms_service.list(search='name=myvm')[0]

# Locate the service that manages the virtual machine, as that is where
# the locators are defined:
vm_service = vms_service.vm_service(vm.id)

# Find the graphic console of the virtual machine:
graphics_consoles_service = vm_service.graphics_consoles_service()
graphics_console = graphics_consoles_service.list()[0]

# Generate the remote viewer connection file:
console_service = graphics_consoles_service.console_service(graphics_console.id)
remote_viewer_connection_file = console_service.remote_viewer_connection_file()

# Write the content to file "/tmp/remote_viewer_connection_file.vv"
path = "/tmp/remote_viewer_connection_file.vv"
with open(path, "w") as f:
    f.write(remote_viewer_connection_file)

When you create the remote viewer connection file, then you can connect to virtual machine graphic console, as follows:

#!/bin/sh -ex

remote-viewer --ovirt-ca-file=/etc/pki/ovirt-engine/ca.pem /tmp/remote_viewer_connection_file.vv
Table 839. Parameters summary
Name Type Direction Summary

remote_viewer_connection_file

String

Out

Contains the file which is compatible with remote-viewer client.

remote_viewer_connection_file

Contains the file which is compatible with remote-viewer client.

User can use the content of this attribute to create a file, which can be passed to remote-viewer client to connect to virtual machine graphic console.

remove DELETE

Remove the graphics console from the virtual machine.

Table 840. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

ticket POST

Generates a time-sensitive authentication token for accessing this virtual machine’s console.

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/ticket

The client-provided action optionally includes a desired ticket value and/or an expiry time in seconds.

In any case, the response specifies the actual ticket value and expiry used.

<action>
  <ticket>
    <value>abcd12345</value>
    <expiry>120</expiry>
  </ticket>
</action>
Table 841. Parameters summary
Name Type Direction Summary

ticket

Ticket

In/Out

The generated ticket that can be used to access this console.

VmGraphicsConsoles

Table 842. Methods summary
Name Summary

add

Add new graphics console to the virtual machine.

list

Lists all the configured graphics consoles of the virtual machine.

add POST

Add new graphics console to the virtual machine.

Table 843. Parameters summary
Name Type Direction Summary

console

GraphicsConsole

In/Out

list GET

Lists all the configured graphics consoles of the virtual machine.

By default, when the current parameter is not specified, the data returned corresponds to the next execution of the virtual machine. In the current implementation of the system this means that the address and port attributes will not be populated because the system does not know what address and port will be used for the next execution. Since in most cases those attributes are needed, it is strongly advised to aways explicitly include the current parameter with the value true.

The order of the returned list of graphics consoles is not guaranteed.

Table 844. Parameters summary
Name Type Direction Summary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the virtual machine.

current

Boolean

In

Specifies if the data returned should correspond to the next execution of the virtual machine, or to the current execution.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of consoles to return.

current

Specifies if the data returned should correspond to the next execution of the virtual machine, or to the current execution.

The address and port attributes will not be populated unless the value is true.

For example, to get data for the current execution of the virtual machine, including the address and port attributes, send a request like this:

GET /ovirt-engine/api/vms/123/graphicsconsoles?current=true

The default value is 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 consoles to return. If not specified all the consoles are returned.

VmHostDevice

A service to manage individual host device attached to a virtual machine.

Table 845. Methods summary
Name Summary

get

Retrieve information about particular host device attached to given virtual machine.

remove

Remove the attachment of this host device from given virtual machine.

get GET

Retrieve information about particular host device attached to given virtual machine.

Example:

GET /ovirt-engine/api/vms/123/hostdevices/456
<host_device href="/ovirt-engine/api/hosts/543/devices/456" id="456">
  <name>pci_0000_04_00_0</name>
  <capability>pci</capability>
  <iommu_group>30</iommu_group>
  <placeholder>true</placeholder>
  <product id="0x13ba">
    <name>GM107GL [Quadro K2200]</name>
  </product>
  <vendor id="0x10de">
    <name>NVIDIA Corporation</name>
  </vendor>
  <host href="/ovirt-engine/api/hosts/543" id="543"/>
  <parent_device href="/ovirt-engine/api/hosts/543/devices/456" id="456">
    <name>pci_0000_00_03_0</name>
  </parent_device>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</host_device>
Table 846. Parameters summary
Name Type Direction Summary

device

HostDevice

Out

Retrieved information about the host device attached to given 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.

remove DELETE

Remove the attachment of this host device from given virtual machine.

In case this device serves as an IOMMU placeholder, it cannot be removed (remove will result only in setting its placeholder flag to true). Note that all IOMMU placeholder devices will be removed automatically as soon as there will be no more non-placeholder devices (all devices from given IOMMU group are detached). 
DELETE /ovirt-engine/api/vms/123/hostdevices/456
Table 847. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

VmHostDevices

A service to manage host devices attached to a virtual machine.

Table 848. Methods summary
Name Summary

add

Attach target device to given virtual machine.

list

List the host devices assigned to given virtual machine.

add POST

Attach target device to given virtual machine.

Example:

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

With request body of type HostDevice, for example

<host_device id="123" />
A necessary precondition for a successful host device attachment is that the virtual machine must be pinned to exactly one host. The device ID is then taken relative to this host.
Attachment of a PCI device that is part of a bigger IOMMU group will result in attachment of the remaining devices from that IOMMU group as "placeholders". These devices are then identified using the placeholder attribute of the HostDevice type set to true.

In case you want attach a device that already serves as an IOMMU placeholder, simply issue an explicit Add operation for it, and its placeholder flag will be cleared, and the device will be accessible to the virtual machine.

Table 849. Parameters summary
Name Type Direction Summary

device

HostDevice

In/Out

The host device to be attached to given virtual machine.

list GET

List the host devices assigned to given virtual machine.

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

Table 850. Parameters summary
Name Type Direction Summary

device

HostDevice[]

Out

Retrieved list of host devices attached to given virtual machine.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of devices 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 devices to return. If not specified all the devices are returned.

VmMediatedDevice

Table 851. Methods summary
Name Summary

get

Retrieves the configuration of mediated devices in the virtual machine.

remove

Remove the mediated device from the virtual machine.

update

Updates the information about the mediated device.

get GET

Retrieves the configuration of mediated devices in the virtual machine.

Table 852. Parameters summary
Name Type Direction Summary

device

VmMediatedDevice

Out

The information about the mediated device of 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.

remove DELETE

Remove the mediated device from the virtual machine.

Table 853. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates the information about the mediated device.

You can update the information using specParams element.

For example, to update a mediated device, send a request like this:

PUT /ovirt-engine/api/vms/123/mediateddevices/00000000-0000-0000-0000-000000000000
<vm_mediated_device>
  <spec_params>
    <property>
      <name>mdevType</name>
      <value>nvidia-11</value>
    </property>
  </spec_params>
</vm_mediated_device>

with response body:

<vm_mediated_device href="/ovirt-engine/api/vms/123/mediateddevices/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
  <spec_params>
    <property>
      <name>mdevType</name>
      <value>nvidia-11</value>
    </property>
  </spec_params>
</vm_mediated_device>
Table 854. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

device

VmMediatedDevice

In/Out

The information about the mediated device.

device

The information about the mediated device.

The request data must contain specParams properties. The response data contains complete information about the updated mediated device.

VmMediatedDevices

A service that manages mediated devices of a VM.

Table 855. Methods summary
Name Summary

add

Add a new mediated device to the virtual machine.

list

Lists all the configured mediated devices of the virtual machine.

add POST

Add a new mediated device to the virtual machine.

Table 856. Parameters summary
Name Type Direction Summary

device

VmMediatedDevice

In/Out

list GET

Lists all the configured mediated devices of the virtual machine.

The order of the returned list of mediated devices is not guaranteed.

Table 857. Parameters summary
Name Type Direction Summary

devices

VmMediatedDevice[]

Out

The list of mediated devices of the virtual machine.

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of mediated devices 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 mediated devices to return. If not specified all the mediated devices are returned.

VmNic

Table 858. Methods summary
Name Summary

activate

deactivate

get

remove

Removes the NIC.

update

Updates the NIC.

activate POST

Table 859. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

deactivate POST

Table 860. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

get GET

Table 861. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

nic

Nic

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.

remove DELETE

Removes the NIC.

For example, to remove the NIC with id 456 from the virtual machine with id 123 send a request like this:

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

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6

  • Red Hat Enterprise Linux 5

  • Windows Server 2008 and

  • Windows Server 2003
Table 862. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates the NIC.

For example, to update the NIC having with 456 belonging to virtual the machine with id 123 send a request like this:

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

With a request body like this:

<nic>
  <name>mynic</name>
  <interface>e1000</interface>
  <vnic_profile id='789'/>
</nic>

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6

  • Red Hat Enterprise Linux 5

  • Windows Server 2008 and

  • Windows Server 2003
Table 863. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

VmNics

Table 864. Methods summary
Name Summary

add

Adds a NIC to the virtual machine.

list

Returns the list of NICs of the virtual machine.

add POST

Adds a NIC to the virtual machine.

The following example adds to the virtual machine 123 a network interface named mynic using virtio and the NIC profile 456.

POST /ovirt-engine/api/vms/123/nics
<nic>
  <name>mynic</name>
  <interface>virtio</interface>
  <vnic_profile id="456"/>
</nic>

The following example sends that request using curl:

curl \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \
--cacert /etc/pki/ovirt-engine/ca.pem \
--data '
<nic>
  <name>mynic</name>
  <interface>virtio</interface>
  <vnic_profile id="456"/>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/123/nics

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6

  • Red Hat Enterprise Linux 5

  • Windows Server 2008 and

  • Windows Server 2003
Table 865. Parameters summary
Name Type Direction Summary

nic

Nic

In/Out

list GET

Returns the list of NICs of the virtual machine.

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

Table 866. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

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 NICs to return. If not specified all the NICs are returned.

VmNumaNode

Table 867. Methods summary
Name Summary

get

remove

Removes a virtual NUMA node.

update

Updates a virtual NUMA node.

get GET

Table 868. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

node

VirtualNumaNode

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.

remove DELETE

Removes a virtual NUMA node.

An example of removing a virtual NUMA node:

DELETE /ovirt-engine/api/vms/123/numanodes/456
It’s required to remove the numa nodes from the highest index first.
Table 869. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates a virtual NUMA node.

An example of pinning a virtual NUMA node to a physical NUMA node on the host:

PUT /ovirt-engine/api/vms/123/numanodes/456

The request body should contain the following:

<vm_numa_node>
  <numa_node_pins>
    <numa_node_pin>
      <index>0</index>
    </numa_node_pin>
  </numa_node_pins>
</vm_numa_node>
Table 870. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

node

VirtualNumaNode

In/Out

VmNumaNodes

Table 871. Methods summary
Name Summary

add

Creates a new virtual NUMA node for the virtual machine.

list

Lists virtual NUMA nodes of a virtual machine.

add POST

Creates a new virtual NUMA node for the virtual machine.

An example of creating a NUMA node:

POST /ovirt-engine/api/vms/c7ecd2dc/numanodes
Accept: application/xml
Content-type: application/xml

The request body can contain the following:

<vm_numa_node>
  <cpu>
    <cores>
      <core>
        <index>0</index>
      </core>
    </cores>
  </cpu>
  <index>0</index>
  <memory>1024</memory>
  <numa_tune_mode>strict</numa_tune_mode>
</vm_numa_node>
Table 872. Parameters summary
Name Type Direction Summary

node

VirtualNumaNode

In/Out

list GET

Lists virtual NUMA nodes of a virtual machine.

The order of the returned list of NUMA nodes isn’t guaranteed.

Table 873. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of nodes to return.

nodes

VirtualNumaNode[]

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 nodes to return. If not specified all the nodes are returned.

VmPool

A service to manage a virtual machines pool.

Table 874. Methods summary
Name Summary

allocatevm

This operation allocates a virtual machine in the virtual machine pool.

get

Get the virtual machine pool.

remove

Removes a virtual machine pool.

update

Update the virtual machine pool.

allocatevm POST

This operation allocates a virtual machine in the virtual machine pool.

POST /ovirt-engine/api/vmpools/123/allocatevm

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

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

async

Boolean

In

Indicates if the allocation should be performed asynchronously.

get GET

Get the virtual machine pool.

GET /ovirt-engine/api/vmpools/123

You will get a XML response like that one:

<vm_pool id="123">
  <actions>...</actions>
  <name>MyVmPool</name>
  <description>MyVmPool description</description>
  <link href="/ovirt-engine/api/vmpools/123/permissions" rel="permissions"/>
  <max_user_vms>1</max_user_vms>
  <prestarted_vms>0</prestarted_vms>
  <size>100</size>
  <stateful>false</stateful>
  <type>automatic</type>
  <use_latest_template_version>false</use_latest_template_version>
  <cluster id="123"/>
  <template id="123"/>
  <vm id="123">...</vm>
  ...
</vm_pool>
Table 876. 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.

pool

VmPool

Out

Retrieved virtual machines pool.

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.

remove DELETE

Removes a virtual machine pool.

DELETE /ovirt-engine/api/vmpools/123
Table 877. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Update the virtual machine pool.

PUT /ovirt-engine/api/vmpools/123

The name, description, size, prestarted_vms and max_user_vms attributes can be updated after the virtual machine pool has been created.

<vmpool>
  <name>VM_Pool_B</name>
  <description>Virtual Machine Pool B</description>
  <size>3</size>
  <prestarted_vms>1</size>
  <max_user_vms>2</size>
</vmpool>
Table 878. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

pool

VmPool

In/Out

The virtual machine pool that is being updated.

seal

Boolean

In

Specifies if virtual machines created for the pool should be sealed after creation.

seal

Specifies if virtual machines created for the pool should be sealed after creation.

If this optional parameter is provided, and its value is true, virtual machines created for the pool will be sealed after creation. If the value is 'false', the virtual machines will not be sealed. If the parameter is not provided, the virtual machines will be sealed, only if they are created from a sealed template and their guest OS is not set to Windows. This parameter affects only the virtual machines created when the pool is updated.

For example, to update a virtual machine pool and to seal the additional virtual machines that are created, send a request like this:

PUT /ovirt-engine/api/vmpools/123?seal=true

With the following body:

<vmpool>
  <name>VM_Pool_B</name>
  <description>Virtual Machine Pool B</description>
  <size>7</size>
</vmpool>

VmPools

Provides read-write access to virtual machines pools.

Table 879. Methods summary
Name Summary

add

Creates a new virtual machine pool.

list

Get a list of available virtual machines pools.

add POST

Creates a new virtual machine pool.

A new pool requires the name, cluster and template attributes. Identify the cluster and template with the id or name nested attributes:

POST /ovirt-engine/api/vmpools

With the following body:

<vmpool>
  <name>mypool</name>
  <cluster id="123"/>
  <template id="456"/>
</vmpool>
Table 880. Parameters summary
Name Type Direction Summary

pool

VmPool

In/Out

Pool to add.

seal

Boolean

In

Specifies if virtual machines created for the pool should be sealed after creation.

seal

Specifies if virtual machines created for the pool should be sealed after creation.

If this optional parameter is provided, and its value is true, virtual machines created for the pool will be sealed after creation. If the value is 'false', the virtual machines will not be sealed. If the parameter is not provided, the virtual machines will be sealed, only if they are created from a sealed template and their guest OS is not set to Windows. This parameter affects only the virtual machines created when the pool is created.

For example, to create a virtual machine pool with 5 virtual machines and to seal them, send a request like this:

POST /ovirt-engine/api/vmpools?seal=true

With the following body:

<vmpool>
  <name>mypool</name>
  <cluster id="123"/>
  <template id="456"/>
  <size>5</size>
</vmpool>

list GET

Get a list of available virtual machines pools.

GET /ovirt-engine/api/vmpools

You will receive the following response:

<vm_pools>
  <vm_pool id="123">
    ...
  </vm_pool>
  ...
</vm_pools>

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

Table 881. Parameters summary
Name Type Direction Summary

case_sensitive

Boolean

In

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

filter

Boolean

In

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

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of pools to return.

pools

VmPool[]

Out

Retrieved pools.

search

String

In

A query string used to restrict the returned pools.

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 pools to return. If this value is not specified, all of the pools are returned.

VmReportedDevice

Table 882. Methods summary
Name Summary

get

get GET

Table 883. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

reported_device

ReportedDevice

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.

VmReportedDevices

Table 884. Methods summary
Name Summary

list

Returns the list of reported devices of the virtual machine.

list GET

Returns the list of reported devices of the virtual machine.

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

Table 885. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of devices to return.

reported_device

ReportedDevice[]

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 devices to return. If not specified all the devices are returned.

VmSession

Table 886. Methods summary
Name Summary

get

get GET

Table 887. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

session

Session

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.

VmSessions

Provides information about virtual machine user sessions.

Table 888. Methods summary
Name Summary

list

Lists all user sessions for this virtual machine.

list GET

Lists all user sessions for this virtual machine.

For example, to retrieve the session information for virtual machine 123 send a request like this:

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

The response body will contain something like this:

<sessions>
  <session href="/ovirt-engine/api/vms/123/sessions/456" id="456">
    <console_user>true</console_user>
    <ip>
      <address>192.168.122.1</address>
    </ip>
    <user href="/ovirt-engine/api/users/789" id="789"/>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </session>
  ...
</sessions>

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

Table 889. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of sessions to return.

sessions

Session[]

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 sessions to return. If not specified all the sessions are returned.

VmWatchdog

A service managing a watchdog on virtual machines.

Table 890. Methods summary
Name Summary

get

Returns the information about the watchdog.

remove

Removes the watchdog from the virtual machine.

update

Updates the information about the watchdog.

get GET

Returns the information about the watchdog.

Table 891. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

watchdog

Watchdog

Out

The information about the watchdog.

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.

watchdog

The information about the watchdog.

The information consists of model element, action element and the reference to the virtual machine. It may look like this:

<watchdogs>
  <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
    <action>poweroff</action>
    <model>i6300esb</model>
  </watchdog>
</watchdogs>

remove DELETE

Removes the watchdog from the virtual machine.

For example, to remove a watchdog from a virtual machine, send a request like this:

DELETE /ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000
Table 892. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates the information about the watchdog.

You can update the information using action and model elements.

For example, to update a watchdog, send a request like this:

PUT /ovirt-engine/api/vms/123/watchdogs
<watchdog>
  <action>reset</action>
</watchdog>

with response body:

<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
  <action>reset</action>
  <model>i6300esb</model>
</watchdog>
Table 893. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

The information about the watchdog.

watchdog

The information about the watchdog.

The request data must contain at least one of model and action elements. The response data contains complete information about the updated watchdog.

VmWatchdogs

Lists the watchdogs of a virtual machine.

Table 894. Methods summary
Name Summary

add

Adds new watchdog to the virtual machine.

list

The list of watchdogs of the virtual machine.

add POST

Adds new watchdog to the virtual machine.

For example, to add a watchdog to a virtual machine, send a request like this:

POST /ovirt-engine/api/vms/123/watchdogs
<watchdog>
  <action>poweroff</action>
  <model>i6300esb</model>
</watchdog>

with response body:

<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
  <action>poweroff</action>
  <model>i6300esb</model>
</watchdog>
Table 895. Parameters summary
Name Type Direction Summary

watchdog

Watchdog

In/Out

The information about the watchdog.

watchdog

The information about the watchdog.

The request data must contain model element (such as i6300esb) and action element (one of none, reset, poweroff, dump, pause). The response data additionally contains references to the added watchdog and to the virtual machine.

list GET

The list of watchdogs of the virtual machine.

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

Table 896. Parameters summary
Name Type Direction Summary

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

Sets the maximum number of watchdogs to return.

watchdogs

Watchdog[]

Out

The information about the watchdog.

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 watchdogs to return. If not specified all the watchdogs are returned.

watchdogs

The information about the watchdog.

The information consists of model element, action element and the reference to the virtual machine. It may look like this:

<watchdogs>
  <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
    <action>poweroff</action>
    <model>i6300esb</model>
  </watchdog>
</watchdogs>

Vms

Table 897. Methods summary
Name Summary

add

Creates a new virtual machine.

list

Returns the list of virtual machines of the system.

add POST

Creates a new virtual machine.

The virtual machine can be created in different ways:

  • From a template. In this case the identifier or name of the template must be provided. For example, using a plain shell script and XML:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
  <name>myvm</name>
  <template>
    <name>Blank</name>
  </template>
  <cluster>
    <name>mycluster</name>
  </cluster>
</vm>
' \
"${url}/vms"

  • From a snapshot. In this case the identifier of the snapshot has to be provided. For example, using a plain shel script and XML:

#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
  <name>myvm</name>
  <snapshots>
    <snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/>
  </snapshots>
  <cluster>
    <name>mycluster</name>
  </cluster>
</vm>
' \
"${url}/vms"

When creating a virtual machine from a template or from a snapshot it is usually useful to explicitly indicate in what storage domain to create the disks for the virtual machine. If the virtual machine is created from a template then this is achieved passing a set of disk_attachment elements that indicate the mapping:

<vm>
  ...
  <disk_attachments>
    <disk_attachment>
      <disk id="8d4bd566-6c86-4592-a4a7-912dbf93c298">
        <storage_domains>
          <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
        </storage_domains>
      </disk>
    <disk_attachment>
  </disk_attachments>
</vm>

When the virtual machine is created from a snapshot this set of disks is slightly different, it uses the image_id attribute instead of id.

<vm>
  ...
  <disk_attachments>
    <disk_attachment>
      <disk>
        <image_id>8d4bd566-6c86-4592-a4a7-912dbf93c298</image_id>
        <storage_domains>
          <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
        </storage_domains>
      </disk>
    <disk_attachment>
  </disk_attachments>
</vm>

It is possible to specify additional virtual machine parameters in the XML description, e.g. a virtual machine of desktop type, with 2 GiB of RAM and additional description can be added sending a request body like the following:

<vm>
  <name>myvm</name>
  <description>My Desktop Virtual Machine</description>
  <type>desktop</type>
  <memory>2147483648</memory>
  ...
</vm>

A bootable CDROM device can be set like this:

<vm>
  ...
  <os>
    <boot dev="cdrom"/>
  </os>
</vm>

In order to boot from CDROM, you first need to insert a disk, as described in the CDROM service. Then booting from that CDROM can be specified using the os.boot.devices attribute:

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

In all cases the name or identifier of the cluster where the virtual machine will be created is mandatory.

Table 898. Parameters summary
Name Type Direction Summary

auto_pinning_policy

AutoPinningPolicy

In

Specifies if and how the auto CPU and NUMA configuration is applied.

clone

Boolean

In

Specifies if the virtual machine should be independent of the template.

clone_permissions

Boolean

In

Specifies if the permissions of the template should be copied to the virtual machine.

filter

Boolean

In

Relevant for admin users only.

seal

Boolean

In

Specifies if the virtual machine should be sealed after creation.

vm

Vm

In/Out

auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. Instead please use POST followed by add operation.

An example for a request:

POST /ovirt-engine/api/vms?auto_pinning_policy=existing/adjust

With a request body like this:

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
  <placement_policy>
    <hosts>
      <host>
        <name>myhost</name>
      </host>
    </hosts>
  </placement_policy>
</vm>

clone

Specifies if the virtual machine should be independent of the template.

When a virtual machine is created from a template by default the disks of the virtual machine depend on the disks of the template, they are using the copy on write mechanism so that only the differences from the template take up real storage space. If this parameter is specified and the value is true then the disks of the created virtual machine will be cloned, and independent of the template. For example, to create an independent virtual machine, send a request like this:

POST /ovirt-engine/vms?clone=true

With a request body like this:

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
When this parameter is true the permissions of the template will also be copied, as when using clone_permissions=true.

clone_permissions

Specifies if the permissions of the template should be copied to the virtual machine.

If this optional parameter is provided, and its values is true then the permissions of the template (only the direct ones, not the inherited ones) will be copied to the created virtual machine. For example, to create a virtual machine from the mytemplate template copying its permissions, send a request like this:

POST /ovirt-engine/api/vms?clone_permissions=true

With a request body like this:

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>

filter

Relevant for admin users only. Indicates whether to assign UserVmManager role on the created Virtual Machine for this user. This will enable the user to later access the Virtual Machine as though he were a non-admin user, foregoing his admin permissions (by providing filter=true).

admin-as-user (meaning providing filter=true) POST requests on an existing Virtual Machine will fail unless the Virtual Machine has been previously created by the admin as a user (meaning with filter=true).

seal

Specifies if the virtual machine should be sealed after creation.

If this optional parameter is provided, and its value is true, the virtual machine will be sealed after creation. If the value is 'false', the virtual machine will not be sealed. If the parameter is not provided, the virtual machine will be sealed, only if it is created from a sealed template and its guest OS is not set to Windows.

For example, to create a virtual machine from the mytemplate template and to seal it, send a request like this:

POST /ovirt-engine/api/vms?seal=true

With a request body like this:

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>

list GET

Returns the list of virtual machines of the system.

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

Table 899. Parameters summary
Name Type Direction Summary

all_content

Boolean

In

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

case_sensitive

Boolean

In

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

filter

Boolean

In

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

follow

String

In

Indicates which inner links should be followed.

max

Integer

In

The maximum number of results to return.

ovf_as_ova

Boolean

In

Indicates if the results should expose the OVF as it appears in OVA files of that VM.

search

String

In

A query string used to restrict the returned virtual machines.

vms

Vm[]

Out

all_content

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

By default the following attributes are excluded:

  • console

  • initialization.configuration.data - The OVF document describing the virtual machine.

  • rng_source

  • soundcard

  • virtio_scsi

For example, to retrieve the complete representation of the virtual machines send a request like this:

GET /ovirt-engine/api/vms?all_content=true
The reason for not including these attributes is performance: they are seldom used and they require additional queries to the database. So try to use the this parameter only when it is really needed.

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.

ovf_as_ova

Indicates if the results should expose the OVF as it appears in OVA files of that VM. The OVF document describing the virtual machine. This parameter will work only when all_content=True is set. The OVF will be presented in initialization.configuration.data.

For example:

GET /vms?all_content=true&ovf_as_ova=true

VnicProfile

This service manages a vNIC profile.

Table 900. Methods summary
Name Summary

get

Retrieves details about a vNIC profile.

remove

Removes the vNIC profile.

update

Updates details of a vNIC profile.

get GET

Retrieves details about a vNIC profile.

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

remove DELETE

Removes the vNIC profile.

Table 902. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

update PUT

Updates details of a vNIC profile.

Table 903. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

VnicProfile

In/Out

The vNIC profile that is being updated.

VnicProfiles

This service manages the collection of all vNIC profiles.

Table 904. Methods summary
Name Summary

add

Add a vNIC profile.

list

List all vNIC profiles.

add POST

Add a vNIC profile.

For example to add vNIC profile 123 to network 456 send a request to:

POST /ovirt-engine/api/networks/456/vnicprofiles

With the following body:

<vnic_profile id="123">
  <name>new_vNIC_name</name>
  <pass_through>
    <mode>disabled</mode>
  </pass_through>
  <port_mirroring>false</port_mirroring>
</vnic_profile>

Please note that there is a default network filter to each VNIC profile. For more details of how the default network filter is calculated please refer to the documentation in NetworkFilters.

The automatically created vNIC profile for the external network will be without network filter.

The output of creating a new VNIC profile depends in the body arguments that were given. In case no network filter was given, the default network filter will be configured. For example:

<vnic_profile href="/ovirt-engine/api/vnicprofiles/123" id="123">
  <name>new_vNIC_name</name>
  <link href="/ovirt-engine/api/vnicprofiles/123/permissions" rel="permissions"/>
  <pass_through>
    <mode>disabled</mode>
  </pass_through>
  <port_mirroring>false</port_mirroring>
  <network href="/ovirt-engine/api/networks/456" id="456"/>
  <network_filter href="/ovirt-engine/api/networkfilters/789" id="789"/>
</vnic_profile>

In case an empty network filter was given, no network filter will be configured for the specific VNIC profile regardless of the VNIC profile’s default network filter. For example:

<vnic_profile>
  <name>no_network_filter</name>
  <network_filter/>
</vnic_profile>

In case that a specific valid network filter id was given, the VNIC profile will be configured with the given network filter regardless of the VNIC profiles’s default network filter. For example:

<vnic_profile>
  <name>user_choice_network_filter</name>
  <network_filter id= "0000001b-001b-001b-001b-0000000001d5"/>
</vnic_profile>
Table 905. Parameters summary
Name Type Direction Summary

profile

VnicProfile

In/Out

The vNIC profile that is being added.

list GET

List all vNIC profiles.

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

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

The list of all vNIC profiles.

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.

Weight

Table 907. Methods summary
Name Summary

get

remove

get GET

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

weight

Weight

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.

remove DELETE

Table 909. Parameters summary
Name Type Direction Summary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

Weights

Table 910. Methods summary
Name Summary

add

Add a weight to a specified user defined scheduling policy.

list

Returns the list of weights.

add POST

Add a weight to a specified user defined scheduling policy.

Table 911. Parameters summary
Name Type Direction Summary

weight

Weight

In/Out

list GET

Returns the list of weights.

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

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

max

Integer

In

Sets the maximum number of weights to return.

weights

Weight[]

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 weights to return. If not specified all the weights are returned.

Types

This section enumerates all the data types that are available in the API.

AccessProtocol enum

Represents the access protocols supported by Gluster volumes. gluster and nfs are enabled by default.

Table 913. Values summary
Name Summary

cifs

CIFS access protocol.

gluster

Gluster access protocol.

nfs

NFS access protocol.

Action struct

Table 914. Attributes summary
Name Type Summary

activate

Boolean

allow_partial_import

Boolean

async

Boolean

attachment

DiskAttachment

authorized_key

AuthorizedKey

auto_pinning_policy

AutoPinningPolicy

bricks

GlusterBrick[]

certificates

Certificate[]

check_connectivity

Boolean

clone

Boolean

clone_permissions

Boolean

cluster

Cluster

collapse_snapshots

Boolean

comment

String

Free text containing comments about this object.

commit_on_success

Boolean

connection

StorageConnection

connectivity_timeout

Integer

correlation_id

String

data_center

DataCenter

deploy_hosted_engine

Boolean

description

String

A human-readable description in plain text.

details

GlusterVolumeProfileDetails

directory

String

discard_snapshots

Boolean

discovered_targets

IscsiDetails[]

disk

Disk

disk_profile

DiskProfile

disks

Disk[]

exclusive

Boolean

fault

Fault

fence_type

String

filename

String

filter

Boolean

fix_layout

Boolean

follow

String

force

Boolean

grace_period

GracePeriod

host

Host

id

String

A unique identifier.

image

String

image_transfer

ImageTransfer

import_as_template

Boolean

is_attached

Boolean

iscsi

IscsiDetails

iscsi_targets

String[]

job

Job

lease

StorageDomainLease

logical_units

LogicalUnit[]

maintenance_after_restart

Boolean

maintenance_enabled

Boolean

migrate_vms_in_affinity_closure

Boolean

modified_bonds

HostNic[]

modified_labels

NetworkLabel[]

modified_network_attachments

NetworkAttachment[]

name

String

A human-readable name in plain text.

optimize_cpu_settings

Boolean

option

Option

pause

Boolean

permission

Permission

power_management

PowerManagement

proxy_ticket

ProxyTicket

quota

Quota

reason

String

reassign_bad_macs

Boolean

reboot

Boolean

registration_configuration

RegistrationConfiguration

remote_viewer_connection_file

String

removed_bonds

HostNic[]

removed_labels

NetworkLabel[]

removed_network_attachments

NetworkAttachment[]

resolution_type

String

restore_memory

Boolean

root_password

String

seal

Boolean

snapshot

Snapshot

source_host

Host

ssh

Ssh

status

String

stop_gluster_service

Boolean

storage_domain

StorageDomain

storage_domains

StorageDomain[]

succeeded

Boolean

synchronized_network_attachments

NetworkAttachment[]

template

Template

ticket

Ticket

timeout

Integer

undeploy_hosted_engine

Boolean

upgrade_action

ClusterUpgradeAction

upgrade_percent_complete

Integer

use_cloud_init

Boolean

use_ignition

Boolean

use_initialization

Boolean

use_sysprep

Boolean

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

vm

Vm

vnic_profile_mappings

VnicProfileMapping[]

volatile

Boolean

AffinityGroup struct

An affinity group represents a group of virtual machines with a defined relationship.

Table 915. Attributes summary
Name Type Summary

broken

Boolean

Specifies if the affinity group is broken.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

enforcing

Boolean

Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines that are members of that affinity group.

hosts_rule

AffinityRule

Specifies the affinity rule applied between virtual machines and hosts that are members of this affinity group.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

positive

Boolean

Specifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are members of that affinity group.

priority

Decimal

Priority of the affinity group.

vms_rule

AffinityRule

Specifies the affinity rule applied to virtual machines that are members of this affinity group.

broken

Specifies if the affinity group is broken. Affinity group is considered broken when any of its rules are not satisfied. Broken field is a computed field in the engine. Because of that, this field is only usable in GET requests.

enforcing

Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines that are members of that affinity group.

Please note that this attribute has been deprecated since version 4.1 of the engine, and will be removed in the future. Use the vms_rule attribute from now on.

positive

Specifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are members of that affinity group.

Please note that this attribute has been deprecated since version 4.1 of the engine, and will be removed in the future. Use the vms_rule attribute from now on.

AffinityLabel struct

The affinity label can influence virtual machine scheduling. It is most frequently used to create a sub-cluster from the available hosts.

Table 917. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

has_implicit_affinity_group

Boolean

This property enables the legacy behavior for labels.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

read_only

Boolean

The read_only property marks a label that can not be modified.

has_implicit_affinity_group

This property enables the legacy behavior for labels. If true, the label acts also as a positive enforcing VM-to-host affinity group.

This parameter is only used for clusters with compatibility version 4.3 or lower.

read_only

The read_only property marks a label that can not be modified. This is usually the case when listing internally-generated labels.

AffinityRule struct

Generic rule definition for affinity group. Each supported resource type (virtual machine, host) is controlled by a separate rule. This allows expressing of rules like: no affinity between defined virtual machines, but hard affinity between defined virtual machines and virtual hosts.

Table 919. Attributes summary
Name Type Summary

enabled

Boolean

Specifies whether the affinity group uses this rule or not.

enforcing

Boolean

Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to the resources that are controlled by this rule.

positive

Boolean

Specifies whether the affinity group applies positive affinity or negative affinity to the resources that are controlled by this rule.

enabled

Specifies whether the affinity group uses this rule or not. This attribute is optional during creation and is considered to be true when it is not provided. In case this attribute is not provided to the update operation, it is considered to be true if AffinityGroup positive attribute is set as well. The backend enabled value will be preserved when both enabled and positive attributes are missing.

enforcing

Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to the resources that are controlled by this rule. This argument is mandatory if the rule is enabled and is ignored when the rule is disabled.

positive

Specifies whether the affinity group applies positive affinity or negative affinity to the resources that are controlled by this rule. This argument is mandatory if the rule is enabled and is ignored when the rule is disabled.

Agent struct

Type representing a fence agent.

Table 920. Attributes summary
Name Type Summary

address

String

Fence agent address.

comment

String

Free text containing comments about this object.

concurrent

Boolean

Specifies whether the agent should be used concurrently or sequentially.

description

String

A human-readable description in plain text.

encrypt_options

Boolean

Specifies whether the options should be encrypted.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

options

Option[]

Fence agent options (comma-delimited list of key-value pairs).

order

Integer

The order of this agent if used with other agents.

password

String

Fence agent password.

port

Integer

Fence agent port.

type

String

Fence agent type.

username

String

Fence agent user name.

Reference to the host service. Each fence agent belongs to a single host.

AgentConfiguration struct

Deprecated Agent configuration settings.

Ignored, because the deployment of OpenStack Neutron agent is dropped since {product-name} 4.4.0. The deployment of OpenStack hosts can be done by Red Hat OpenStack Platform Director or TripleO.

Table 922. Attributes summary
Name Type Summary

address

String

broker_type

MessageBrokerType

network_mappings

String

Not recommended to use, because the Open vSwitch interface mappings are managed by VDSM since {product-name} 4.

password

String

port

Integer

username

String

network_mappings

Not recommended to use, because the Open vSwitch interface mappings are managed by VDSM since {product-name} 4.2.0.

Api struct

This type contains the information returned by the root service of the API.

To get that information send a request like this:

GET /ovirt-engine/api

The result will be like this:

<api>
  <link rel="hosts" href="/ovirt-engine/api/hosts"/>
  <link rel="vms" href="/ovirt-engine/api/vms"/>
  ...
  <product_info>
    <name>oVirt Engine</name>
    <vendor>ovirt.org</vendor>
    <version>
      <build>0</build>
      <full_version>4.1.0_master</full_version>
      <major>4</major>
      <minor>1</minor>
      <revision>0</revision>
    </version>
  </product_info>
  <special_objects>
    <link rel="templates/blank" href="..."/>
    <link rel="tags/root" href="..."/>
  </special_objects>
  <summary>
    <vms>
      <total>10</total>
      <active>3</active>
    </vms>
    <hosts>
      <total>2</total>
      <active>2</active>
    </hosts>
    <users>
      <total>8</total>
      <active>2</active>
    </users>
    <storage_domains>
      <total>2</total>
      <active>2</active>
    </storage_domains>
  </summary>
  <time>2016-12-12T12:22:25.866+01:00</time>
</api>
Table 923. Attributes summary
Name Type Summary

product_info

ProductInfo

Information about the product, such as its name, the name of the vendor, and the version.

special_objects

SpecialObjects

References to special objects, such as the blank template and the root of the hierarchy of tags.

summary

ApiSummary

A summary containing the total number of relevant objects, such as virtual machines, hosts, and storage domains.

time

Date

The date and time when this information was generated.

Reference to the authenticated user.

The authenticated user is the user whose credentials were verified in order to accept the current request. In the current version of the system the authenticated user and the effective user are always the same. In the future, when support for user impersonation is introduced, they will be potentially different.

Reference to the effective user.

The effective user is the user whose permissions apply during the current request. In the current version of the system the authenticated user and the effective user are always the same. In the future, when support for user impersonation is introduced, they will be potentially different.

ApiSummary struct

A summary containing the total number of relevant objects, such as virtual machines, hosts, and storage domains.

Table 925. Attributes summary
Name Type Summary

hosts

ApiSummaryItem

The summary of hosts.

storage_domains

ApiSummaryItem

The summary of storage domains.

users

ApiSummaryItem

The summary of users.

vms

ApiSummaryItem

The summary of virtual machines.

ApiSummaryItem struct

This type contains an item of the API summary. Each item contains the total and active number of some kind of object.

Table 926. Attributes summary
Name Type Summary

active

Integer

The total number of active objects.

total

Integer

The total number of objects.

Application struct

Represents an application installed on a virtual machine. Applications are reported by the guest agent, if you deploy one on the virtual machine operating system.

To get that information send a request like this:

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

The result will be like this:

<application href="/ovirt-engine/api/vms/123/applications/456" id="456">
  <name>application-test-1.0.0-0.el7</name>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</application>
Table 927. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Architecture enum

Table 929. Values summary
Name Summary

aarch64

AARCH64 CPU architecture.

ppc64

s390x

IBM S390X CPU architecture.

undefined

x86_64

s390x

IBM S390X CPU architecture.

Needs to be specified for virtual machines and clusters running on the S390X architecture.

Note that S390 is often used in an ambiguous way to describe either the general machine architecture as such or its 31-bit variant. S390X is used specifically for the 64-bit architecture, which is in line with the other architectures, like X86_64 or PPC64.

AuthorizedKey struct

Table 930. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

key

String

name

String

A human-readable name in plain text.

AutoNumaStatus enum

Table 932. Values summary
Name Summary

disable

enable

unknown

AutoPinningPolicy enum

Type representing what the CPU and NUMA pinning policy is.

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. Instead please use CpuPinningPolicy.
Table 933. Values summary
Name Summary

adjust

The CPU and NUMA pinning will be configured by the dedicated host.

disabled

The CPU and NUMA pinning won’t be calculated.

existing

The CPU and NUMA pinning will be configured by the virtual machine current state.

adjust

The CPU and NUMA pinning will be configured by the dedicated host.

Currently, its implication is that the CPU and NUMA pinning will use the dedicated host CPU topology. The virtual machine configuration will automatically be set to fit the host to get the highest possible performance.

disabled

The CPU and NUMA pinning won’t be calculated.

Currently, its implication is that the CPU and NUMA pinning won’t be calculated to the current virtual machine configuration. By default the VM topology set with 1 Socket, 1 Core and 1 Thread.

existing

The CPU and NUMA pinning will be configured by the virtual machine current state.

Currently, its implication is that the CPU and NUMA pinning will use the provided virtual machine CPU topology. Without given CPU topology it will use the engine defaults (the VM topology set with 1 Socket, 1 Core and 1 Thread).

Backup struct

Table 934. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

creation_date

Date

The backup creation date.

description

String

A human-readable description in plain text.

from_checkpoint_id

String

The checkpoint id at which to start the incremental backup.

id

String

A unique identifier.

modification_date

Date

The backup modification date.

name

String

A human-readable name in plain text.

phase

BackupPhase

The phase of the backup operation.

to_checkpoint_id

String

The checkpoint id created by this backup operation.

to_checkpoint_id

The checkpoint id created by this backup operation. This id can be used as the fromCheckpointId in the next incremental backup.

BackupPhase enum

Table 936. Values summary
Name Summary

failed

The final phase, indicates that the backup has failed.

finalizing

In this phase, the backup is invoking 'stop_backup' operation in order to complete the backup and unlock the relevant disk.

initializing

The initial phase of the backup.

ready

The phase means that the relevant disks' backup URLs are ready to be used and downloaded using image transfer.

starting

The phase is set before invoking 'start_backup' operation in vdsm/libvirt (which means that 'stop_backup' should be invoked to complete the flow).

succeeded

The final phase, indicates that the backup has finished successfully.

initializing

The initial phase of the backup. It is set on entity creation.

Balance struct

Table 937. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Bios struct

Table 939. Attributes summary
Name Type Summary

boot_menu

BootMenu

type

BiosType

Chipset and BIOS type combination.

BiosType enum

Type representing a chipset and a BIOS type combination.

Table 940. Values summary
Name Summary

cluster_default

Use the cluster-wide default.

i440fx_sea_bios

i440fx chipset with SeaBIOS.

q35_ovmf

q35 chipset with OVMF (UEFI) BIOS.

q35_sea_bios

q35 chipset with SeaBIOS.

q35_secure_boot

q35 chipset with OVMF (UEFI) BIOS with SecureBoot enabled.

cluster_default

Use the cluster-wide default.

This value cannot be used for cluster.

i440fx_sea_bios

i440fx chipset with SeaBIOS.

For non-x86 architectures this is the only non-default value allowed.

BlockStatistic struct

Table 941. Attributes summary
Name Type Summary

statistics

Statistic[]

Bonding struct

Represents a network interfaces bond.

Table 942. Attributes summary
Name Type Summary

ad_partner_mac

Mac

The ad_partner_mac property of the partner bond in mode 4.

options

Option[]

A list of option elements for a bonded interface.

slaves

HostNic[]

A list of slave NICs for a bonded interface.

ad_partner_mac

The ad_partner_mac property of the partner bond in mode 4. Bond mode 4 is the 802.3ad standard, which is also called dynamic link aggregation. See Wikipedia and Presentation for more information. ad_partner_mac is the MAC address of the system (switch) at the other end of a bond. This parameter is read-only. Setting it will have no effect on the bond. It is retrieved from /sys/class/net/bondX/bonding/ad_partner_mac file on the system where the bond is located.

options

A list of option elements for a bonded interface. Each option contains property name and value attributes. Only required when adding bonded interfaces.

slaves

A list of slave NICs for a bonded interface. Only required when adding bonded interfaces.

The active_slave property of the bond in modes that support it (active-backup, balance-alb and balance-tlb). See Linux documentation for further details. This parameter is read-only. Setting it will have no effect on the bond. It is retrieved from /sys/class/net/bondX/bonding/active_slave file on the system where the bond is located.

For example:

GET /ovirt-engine/api/hosts/123/nics/321

Will respond:

<host_nic href="/ovirt-engine/api/hosts/123/nics/321" id="321">
  ...
  <bonding>
    <slaves>
      <host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456" />
      ...
    </slaves>
    <active_slave href="/ovirt-engine/api/hosts/123/nics/456" id="456" />
  </bonding>
  ...
</host_nic>

Bookmark struct

Represents a bookmark in the system.

Table 944. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

value

String

The bookmark value, representing a search in the engine.

Boot struct

Configuration of the boot sequence of a virtual machine.

Table 945. Attributes summary
Name Type Summary

devices

BootDevice[]

Ordered list of boot devices.

devices

Ordered list of boot devices. The virtual machine will try to boot from the given boot devices, in the given order.

BootDevice enum

Represents the kinds of devices that a virtual machine can boot from.

Table 946. Values summary
Name Summary

cdrom

Boot from CD-ROM.

hd

Boot from the hard drive.

network

Boot from the network, using PXE.

cdrom

Boot from CD-ROM. The CD-ROM can be chosen from the list of ISO files available in an ISO domain attached to the ata center that the virtual machine belongs to.

network

Boot from the network, using PXE. It is necessary to have PXE configured on the network that the virtual machine is connected to.

BootMenu struct

Represents boot menu configuration for virtual machines and templates.

Table 947. Attributes summary
Name Type Summary

enabled

Boolean

Whether the boot menu is enabled for this virtual machine (or template), or not.

BootProtocol enum

Defines the options of the IP address assignment method to a NIC.

Table 948. Values summary
Name Summary

autoconf

Stateless address auto-configuration.

dhcp

Dynamic host configuration protocol.

none

No address configuration.

poly_dhcp_autoconf

DHCP alongside Stateless address auto-configuration (SLAAC).

static

Statically-defined address, mask and gateway.

autoconf

Stateless address auto-configuration.

The mechanism is defined by RFC 4862. Please refer to this wikipedia article for more information.

The value is valid for IPv6 addresses only.

dhcp

Dynamic host configuration protocol.

Please refer to this wikipedia article for more information.

poly_dhcp_autoconf

DHCP alongside Stateless address auto-configuration (SLAAC).

The SLAAC mechanism is defined by RFC 4862. Please refer to the Stateless address auto-configuration article and the DHCP article for more information.

The value is valid for IPv6 addresses only.

BrickProfileDetail struct

Table 949. Attributes summary
Name Type Summary

profile_details

ProfileDetail[]

Cdrom struct

Table 951. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

file

File

id

String

A unique identifier.

name

String

A human-readable name in plain text.

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

Certificate struct

Table 953. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

content

String

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

organization

String

subject

String

Checkpoint struct

Table 954. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

creation_date

Date

The checkpoint creation date.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

parent_id

String

The parent checkpoint id.

state

CheckpointState

The state of the checkpoint.

CheckpointState enum

Table 956. Values summary
Name Summary

created

The initial state of the checkpoint.

invalid

The INVALID state set when a checkpoint cannot be used anymore for incremental backup and should be removed (For example, after committing to an older VM snapshot).

created

The initial state of the checkpoint. It is set on entity creation.

CloudInit struct

Deprecated type to specify cloud-init configuration.

This type has been deprecated and replaced by alternative attributes inside the Initialization type. See the cloud_init attribute documentation for details.

Table 957. Attributes summary
Name Type Summary

authorized_keys

AuthorizedKey[]

files

File[]

host

Host

network_configuration

NetworkConfiguration

regenerate_ssh_keys

Boolean

timezone

String

users

User[]

CloudInitNetworkProtocol enum

Defines the values for the cloud-init protocol. This protocol decides how the cloud-init network parameters are formatted before being passed to the virtual machine in order to be processed by cloud-init.

Protocols supported are cloud-init version dependent. For more information, see Network Configuration Sources

Table 958. Values summary
Name Summary

eni

Legacy protocol.

openstack_metadata

Successor of the ENI protocol, with support for IPv6 and more.

eni

Legacy protocol. Does not support IPv6. For more information, see Network Configuration ENI (Legacy)

openstack_metadata

Successor of the ENI protocol, with support for IPv6 and more. This is the default value. For more information, see API: Proxy neutron configuration to guest instance

Cluster struct

Type representation of a cluster.

A JSON representation of a cluster:

{
  "cluster" : [ {
    "ballooning_enabled" : "false",
    "cpu" : {
      "architecture" : "x86_64",
      "type" : "Intel SandyBridge Family"
    },
    "custom_scheduling_policy_properties" : {
      "property" : [ {
        "name" : "HighUtilization",
        "value" : "80"
      }, {
        "name" : "CpuOverCommitDurationMinutes",
        "value" : "2"
      } ]
    },
    "error_handling" : {
      "on_error" : "migrate"
    },
    "fencing_policy" : {
      "enabled" : "true",
      "skip_if_connectivity_broken" : {
        "enabled" : "false",
        "threshold" : "50"
      },
      "skip_if_gluster_bricks_up" : "false",
      "skip_if_gluster_quorum_not_met" : "false",
      "skip_if_sd_active" : {
        "enabled" : "false"
      }
    },
    "gluster_service" : "false",
    "firewall_type" : "iptables",
    "ha_reservation" : "false",
    "ksm" : {
      "enabled" : "true",
      "merge_across_nodes" : "true"
    },
    "memory_policy" : {
      "over_commit" : {
        "percent" : "100"
      },
      "transparent_hugepages" : {
        "enabled" : "true"
      }
    },
    "migration" : {
      "auto_converge" : "inherit",
      "bandwidth" : {
        "assignment_method" : "auto"
      },
      "compressed" : "inherit",
      "policy" : {
        "id" : "00000000-0000-0000-0000-000000000000"
      }
    },
    "required_rng_sources" : {
      "required_rng_source" : [ "random" ]
    },
    "switch_type" : "legacy",
    "threads_as_cores" : "false",
    "trusted_service" : "false",
    "tunnel_migration" : "false",
    "version" : {
      "major" : "4",
      "minor" : "1"
    },
    "virt_service" : "true",
    "data_center" : {
      "href" : "/ovirt-engine/api/datacenters/123",
      "id" : "123"
    },
    "mac_pool" : {
      "href" : "/ovirt-engine/api/macpools/456",
      "id" : "456"
    },
    "scheduling_policy" : {
      "href" : "/ovirt-engine/api/schedulingpolicies/789",
      "id" : "789"
    },
    "actions" : {
      "link" : [ {
        "href" : "/ovirt-engine/api/clusters/234/resetemulatedmachine",
        "rel" : "resetemulatedmachine"
      } ]
    },
    "name" : "Default",
    "description" : "The default server cluster",
    "href" : "/ovirt-engine/api/clusters/234",
    "id" : "234",
    "link" : [ {
      "href" : "/ovirt-engine/api/clusters/234/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/cpuprofiles",
      "rel" : "cpuprofiles"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/networkfilters",
      "rel" : "networkfilters"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/networks",
      "rel" : "networks"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/affinitygroups",
      "rel" : "affinitygroups"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/glusterhooks",
      "rel" : "glusterhooks"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/glustervolumes",
      "rel" : "glustervolumes"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/enabledfeatures",
      "rel" : "enabledfeatures"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/externalnetworkproviders",
      "rel" : "externalnetworkproviders"
    } ]
  } ]
}
Table 959. Attributes summary
Name Type Summary

ballooning_enabled

Boolean

bios_type

BiosType

Chipset and BIOS type combination.

comment

String

Free text containing comments about this object.

cpu

Cpu

custom_scheduling_policy_properties

Property[]

Custom scheduling policy properties of the cluster.

description

String

A human-readable description in plain text.

display

Display

error_handling

ErrorHandling

fencing_policy

FencingPolicy

A custom fencing policy can be defined for a cluster.

fips_mode

FipsMode

FIPS mode of the cluster.

firewall_type

FirewallType

The type of firewall to be used on hosts in this cluster.

gluster_service

Boolean

gluster_tuned_profile

String

The name of the tuned profile.

ha_reservation

Boolean

id

String

A unique identifier.

ksm

Ksm

log_max_memory_used_threshold

Integer

The memory consumption threshold for logging audit log events.

log_max_memory_used_threshold_type

LogMaxMemoryUsedThresholdType

The memory consumption threshold type for logging audit log events.

maintenance_reason_required

Boolean

This property has no longer any relevance and has been deprecated.

memory_policy

MemoryPolicy

migration

MigrationOptions

Reference to cluster-wide configuration of migration of a running virtual machine to another host.

name

String

A human-readable name in plain text.

optional_reason

Boolean

This property has no longer any relevance and has been deprecated.

required_rng_sources

RngSource[]

Set of random number generator (RNG) sources required from each host in the cluster.

serial_number

SerialNumber

supported_versions

Version[]

switch_type

SwitchType

The type of switch to be used by all networks in given cluster.

threads_as_cores

Boolean

trusted_service

Boolean

tunnel_migration

Boolean

upgrade_correlation_id

String

The upgrade correlation identifier.

upgrade_in_progress

Boolean

Indicates if an upgrade has been started for the cluster.

upgrade_percent_complete

Integer

If an upgrade is in progress, the upgrade’s reported percent complete.

version

Version

The compatibility version of the cluster.

virt_service

Boolean

vnc_encryption

Boolean

Enable VNC encryption.

bios_type

Chipset and BIOS type combination.

This value is used as default for all virtual machines in the cluster having biosType set to CLUSTER_DEFAULT.

custom_scheduling_policy_properties

Custom scheduling policy properties of the cluster. These optional properties override the properties of the scheduling policy specified by the scheduling_policy link, and apply only for this specific cluster.

For example, to update the custom properties of the cluster, send a request:

PUT /ovirt-engine/api/clusters/123

With a request body:

<cluster>
  <custom_scheduling_policy_properties>
    <property>
      <name>HighUtilization</name>
      <value>70</value>
    </property>
  </custom_scheduling_policy_properties>
</cluster>

Update operations using the custom_scheduling_policy_properties attribute will not update the the properties of the scheduling policy specified by the scheduling_policy link, they will only be reflected on this specific cluster.

fencing_policy

A custom fencing policy can be defined for a cluster.

For example:

PUT /ovirt-engine/api/cluster/123

With request body like this:

<cluster>
  <fencing_policy>
    <enabled>true</enabled>
    <skip_if_sd_active>
      <enabled>false</enabled>
    </skip_if_sd_active>
    <skip_if_connectivity_broken>
      <enabled>false</enabled>
      <threshold>50</threshold>
    </skip_if_connectivity_broken>
  </fencing_policy>
</cluster>

fips_mode

FIPS mode of the cluster.

FIPS mode represents the cluster’s policy towards hosts. Hosts added to the cluster will be checked to fulfill the cluster’s FIPS mode, making them non-operational if they do not. Unless a value is explicity provided, new clusters are initialized by default to UNDEFINED. This value changes automatically to the FIPS mode of the first host added to the cluster.

gluster_tuned_profile

The name of the tuned profile.

Tuned profile to set on all the hosts in the cluster. This is not mandatory and relevant only for clusters with Gluster service.

log_max_memory_used_threshold

The memory consumption threshold for logging audit log events.

For percentage, an audit log event is logged if the used memory is more that the value specified. For absolute value, an audit log event is logged when the the free memory falls below the value specified in MB.

log_max_memory_used_threshold_type

The memory consumption threshold type for logging audit log events.

You can choose between 'percentage' and 'absolute_value_in_mb'.

maintenance_reason_required

This property has no longer any relevance and has been deprecated. Its default value is true,

migration

Reference to cluster-wide configuration of migration of a running virtual machine to another host.

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

optional_reason

This property has no longer any relevance and has been deprecated. Its default value is true.

required_rng_sources

Set of random number generator (RNG) sources required from each host in the cluster.

When read, it returns the implicit urandom (for cluster version 4.1 and higher) or random (for cluster version 4.0 and lower) plus additional selected RNG sources. When written, the implicit urandom and random RNG sources cannot be removed.

Before version 4.1 of the engine, the set of required random number generators was completely controllable by the administrator; any source could be added or removed, including the random source. But starting with version 4.1, the urandom and random sources will always be part of the set, and can’t be removed.

Engine version 4.1 introduces a new RNG source urandom that replaces random RNG source in clusters with compatibility version 4.1 or higher.

upgrade_correlation_id

The upgrade correlation identifier. Use to correlate events detailing the cluster upgrade to the upgrade itself.

version

The compatibility version of the cluster.

All hosts in this cluster must support at least this compatibility version.

For example:

GET /ovirt-engine/api/clusters/123

Will respond with:

<cluster>
  ...
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  ...
</cluster>

To update the compatibility version, use:

PUT /ovirt-engine/api/clusters/123

With a request body like this:

<cluster>
  <version>
    <major>4</major>
    <minor>1</minor>
  </version>
</cluster>

In order to update the cluster compatibility version, all hosts in the cluster must support the new compatibility version.

vnc_encryption

Enable VNC encryption. Default value for this property is false.

A reference to the external network provider available in the cluster.

If the automatic deployment of the external network provider is supported, the networks of the referenced network provider are available on every host in the cluster. External network providers of a cluster can only be set during adding the cluster. This value may be overwritten for individual hosts during adding the host.

Reference to the default scheduling policy used by this cluster.

The scheduling policy properties are taken by default from the referenced scheduling policy, but they are overridden by the properties specified in the custom_scheduling_policy_properties attribute for this cluster.

ClusterFeature struct

Type represents an additional feature that is available at a cluster level.

Table 961. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

ClusterLevel struct

Describes the capabilities supported by a specific cluster level.

Table 963. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

cpu_types

CpuType[]

The CPU types supported by this cluster level.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

permits

Permit[]

The permits supported by this cluster level.

ClusterUpgradeAction enum

The action type for cluster upgrade action.

Table 965. Values summary
Name Summary

finish

The upgrade action to be passed to finish the cluster upgrade process by marking the cluster’s upgrade_running flag to false.

start

The upgrade action to be passed to start the cluster upgrade process by marking the cluster’s upgrade_running flag to true.

update_progress

The upgrade action to be passed to update the cluster upgrade progress.

finish

The upgrade action to be passed to finish the cluster upgrade process by marking the cluster’s upgrade_running flag to false. This should be used at the end of the cluster upgrade process.

start

The upgrade action to be passed to start the cluster upgrade process by marking the cluster’s upgrade_running flag to true. This should used at the beginning of the cluster upgrade process.

update_progress

The upgrade action to be passed to update the cluster upgrade progress. This should be used as the upgrade progresses.

Configuration struct

Table 966. Attributes summary
Name Type Summary

data

String

The document describing the virtual machine.

type

ConfigurationType

data

The document describing the virtual machine.

Example of the OVF document:

<?xml version='1.0' encoding='UTF-8'?>
<ovf:Envelope xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1/"
  xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData"
  xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  ovf:version="3.5.0.0">
  <References/>
  <Section xsi:type="ovf:NetworkSection_Type">
    <Info>List of networks</Info>
    <Network ovf:name="Network 1"/>
  </Section>
  <Section xsi:type="ovf:DiskSection_Type">
    <Info>List of Virtual Disks</Info>
  </Section>
  <Content ovf:id="out" xsi:type="ovf:VirtualSystem_Type">
    <CreationDate>2014/12/03 04:25:45</CreationDate>
    <ExportDate>2015/02/09 14:12:24</ExportDate>
    <DeleteProtected>false</DeleteProtected>
    <SsoMethod>guest_agent</SsoMethod>
    <IsSmartcardEnabled>false</IsSmartcardEnabled>
    <TimeZone>Etc/GMT</TimeZone>
    <default_boot_sequence>0</default_boot_sequence>
    <Generation>1</Generation>
    <VmType>1</VmType>
    <MinAllocatedMem>1024</MinAllocatedMem>
    <IsStateless>false</IsStateless>
    <IsRunAndPause>false</IsRunAndPause>
    <AutoStartup>false</AutoStartup>
    <Priority>1</Priority>
    <CreatedByUserId>fdfc627c-d875-11e0-90f0-83df133b58cc</CreatedByUserId>
    <IsBootMenuEnabled>false</IsBootMenuEnabled>
    <IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled>
    <IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled>
    <Name>VM_export</Name>
    <TemplateId>00000000-0000-0000-0000-000000000000</TemplateId>
    <TemplateName>Blank</TemplateName>
    <IsInitilized>false</IsInitilized>
    <Origin>3</Origin>
    <DefaultDisplayType>1</DefaultDisplayType>
    <TrustedService>false</TrustedService>
    <OriginalTemplateId>00000000-0000-0000-0000-000000000000</OriginalTemplateId>
    <OriginalTemplateName>Blank</OriginalTemplateName>
    <UseLatestVersion>false</UseLatestVersion>
    <Section ovf:id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a"
      ovf:required="false"
      xsi:type="ovf:OperatingSystemSection_Type">
      <Info>Guest Operating System</Info>
      <Description>other</Description>
    </Section>
    <Section xsi:type="ovf:VirtualHardwareSection_Type">
      <Info>1 CPU, 1024 Memory</Info>
      <System>
        <vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType>
      </System>
      <Item>
        <rasd:Caption>1 virtual cpu</rasd:Caption>
        <rasd:Description>Number of virtual CPU</rasd:Description>
        <rasd:InstanceId>1</rasd:InstanceId>
        <rasd:ResourceType>3</rasd:ResourceType>
        <rasd:num_of_sockets>1</rasd:num_of_sockets>
        <rasd:cpu_per_socket>1</rasd:cpu_per_socket>
      </Item>
      <Item>
        <rasd:Caption>1024 MB of memory</rasd:Caption>
        <rasd:Description>Memory Size</rasd:Description>
        <rasd:InstanceId>2</rasd:InstanceId>
        <rasd:ResourceType>4</rasd:ResourceType>
        <rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits>
        <rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
      </Item>
      <Item>
        <rasd:Caption>USB Controller</rasd:Caption>
        <rasd:InstanceId>3</rasd:InstanceId>
        <rasd:ResourceType>23</rasd:ResourceType>
        <rasd:UsbPolicy>DISABLED</rasd:UsbPolicy>
      </Item>
    </Section>
  </Content>
</ovf:Envelope>

ConfigurationType enum

Configuration format types.

Table 967. Values summary
Name Summary

ova

ConfigurationType of type standard OVF.

ovf

ConfigurationType of type oVirt-compatible OVF.

ova

ConfigurationType of type standard OVF.

The provided virtual machine configuration conforms with the Open Virtualization Format (OVF) standard. This value should be used for an OVF configuration that is extracted from an Open Virtual Appliance (OVA) that was generated by oVirt or by other vendors. See the OVF specification.

ovf

ConfigurationType of type oVirt-compatible OVF.

The provided virtual machine configuration conforms with the oVirt-compatible form of the Open Virtualization Format (OVF). Note that the oVirt-compatible form of the OVF may differ from the OVF standard that is used by other vendors. This value should be used for an OVF configuration that is taken from a storage domain.

Console struct

Representation for serial console device.

Table 968. Attributes summary
Name Type Summary

enabled

Boolean

Enable/disable the serial console device.

Core struct

Table 969. Attributes summary
Name Type Summary

index

Integer

socket

Integer

Cpu struct

Table 970. Attributes summary
Name Type Summary

architecture

Architecture

cores

Core[]

cpu_tune

CpuTune

level

Integer

mode

CpuMode

name

String

speed

Decimal

topology

CpuTopology

type

String

CpuMode enum

Table 971. Values summary
Name Summary

custom

host_model

host_passthrough

CpuPinningPolicy enum

Type representing the CPU and NUMA pinning policy.

Table 972. Values summary
Name Summary

dedicated

The CPU pinning will be automatically calculated by the engine when a vm starts and it will be dropped when the vm stops.

isolate_threads

The CPU pinning will be automatically calculated by the engine when a vm starts, and it will be dropped when the vm stops.

manual

The CPU pinning will be manually configured.

none

The CPU pinning won’t be configured.

resize_and_pin_numa

The CPU and NUMA pinning will be configured by the dedicated host.

dedicated

The CPU pinning will be automatically calculated by the engine when a vm starts and it will be dropped when the vm stops.

The pinning is exclusive, that means that no other VM can use the pinned physical CPU.

isolate_threads

The CPU pinning will be automatically calculated by the engine when a vm starts, and it will be dropped when the vm stops.

The pinning is exclusive, each virtual thread will get an exclusive physical core. That means that no other VM can use the pinned physical CPU.

manual

The CPU pinning will be manually configured.

Currently, this means that the CPU pinning will be manually configured to the current virtual machine configuration. The VM needs to be pinned to at least one host. The Pinning is provided within the CPU configuration, using CpuTune.

none

The CPU pinning won’t be configured.

Currently, this means that the CPU pinning won’t be configured to the current virtual machine configuration. By default, the VM topology is set with 1 Socket, 1 Core and 1 Thread.

resize_and_pin_numa

The CPU and NUMA pinning will be configured by the dedicated host.

The CPU and NUMA pinning will use the dedicated host CPU topology. The virtual machine configuration will automatically be set to fit the host to get the highest possible performance.

CpuProfile struct

Table 973. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

CpuTopology struct

Table 975. Attributes summary
Name Type Summary

cores

Integer

sockets

Integer

threads

Integer

CpuTune struct

Table 976. Attributes summary
Name Type Summary

vcpu_pins

VcpuPin[]

CpuType struct

Describes a supported CPU type.

Table 977. Attributes summary
Name Type Summary

architecture

Architecture

The architecture of the CPU.

level

Integer

The level of the CPU type.

name

String

The name of the CPU type, for example Intel Nehalem Family.

CreationStatus enum

Table 978. Values summary
Name Summary

complete

failed

in_progress

pending

CustomProperty struct

Custom property representation.

Table 979. Attributes summary
Name Type Summary

name

String

Property name.

regexp

String

A regular expression defining the available values a custom property can get.

value

String

Property value.

DataCenter struct

Table 980. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

local

Boolean

name

String

A human-readable name in plain text.

quota_mode

QuotaModeType

status

DataCenterStatus

storage_format

StorageFormat

supported_versions

Version[]

version

Version

The compatibility version of the data center.

version

The compatibility version of the data center.

All clusters in this data center must already be set to at least this compatibility version.

For example:

GET /ovirt-engine/api/datacenters/123

Will respond:

<data_center>
  ...
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  ...
</data_center>

To update the compatibility version, use:

PUT /ovirt-engine/api/datacenters/123

With a request body:

<data_center>
  <version>
    <major>4</major>
    <minor>1</minor>
  </version>
</data_center>

DataCenterStatus enum

Table 982. Values summary
Name Summary

contend

maintenance

not_operational

problematic

uninitialized

up

Device struct

A device wraps links to potential parents of a device.

Table 983. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

Disk struct

Represents a virtual disk device.

Table 985. Attributes summary
Name Type Summary

active

Boolean

Indicates if the disk is visible to the virtual machine.

actual_size

Integer

The actual size of the disk, in bytes.

alias

String

backup

DiskBackup

The backup behavior supported by the disk.

backup_mode

DiskBackupMode

The type of the disk backup (full/incremental), visible only when the disk backup is in progress.

bootable

Boolean

Indicates if the disk is marked as bootable.

comment

String

Free text containing comments about this object.

content_type

DiskContentType

Indicates the actual content residing on the disk.

description

String

A human-readable description in plain text.

external_disk

String

Use external disk.

format

DiskFormat

The underlying storage format.

id

String

A unique identifier.

image_id

String

initial_size

Integer

The initial size of a sparse image disk created on block storage, in bytes.

interface

DiskInterface

The type of interface driver used to connect the disk device to the virtual machine.

logical_name

String

lun_storage

HostStorage

name

String

A human-readable name in plain text.

propagate_errors

Boolean

Indicates if disk errors should cause virtual machine to be paused or if disk errors should be propagated to the the guest operating system instead.

provisioned_size

Integer

The virtual size of the disk, in bytes.

qcow_version

QcowVersion

The underlying QCOW version of a QCOW volume.

read_only

Boolean

Indicates if the disk is in read-only mode.

sgio

ScsiGenericIO

Indicates whether SCSI passthrough is enable and its policy.

shareable

Boolean

Indicates if the disk can be attached to multiple virtual machines.

sparse

Boolean

Indicates if the physical storage for the disk should not be preallocated.

status

DiskStatus

The status of the disk device.

storage_type

DiskStorageType

total_size

Integer

The total size of the disk including all of its snapshots, in bytes.

uses_scsi_reservation

Boolean

wipe_after_delete

Boolean

Indicates if the disk’s blocks will be read back as zeros after it is deleted:

- On block storage, the disk will be zeroed and only then deleted.

active

Indicates if the disk is visible to the virtual machine.

When adding a disk attachment to a virtual machine, if the server accepts requests that do not contain this attribute the result is undefined. In some cases the disk will be automatically activated and in other cases it will not. To avoid issues it is strongly recommended to always include the this attribute with the desired value.

actual_size

The actual size of the disk, in bytes.

The actual size is the number of bytes actually used by the disk. It will be smaller than the provisioned size for disks that use the cow format.

bootable

Indicates if the disk is marked as bootable.

This attribute only makes sense for disks that are actually connected to virtual machines, and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

external_disk

Use external disk.

An external disk can be a path to a local file or a block device, or a URL supported by QEMU such as:

  • nbd:<host>:<port>[:exportname=<export>]

  • nbd:unix:</path>[:exportname=<export>]

  • http://[<username>[:<password>]@]<host>/<path>

  • https://[<username>[:<password>]@]<host>/<path>

  • ftp://[<username>[:<password>]@]<host>/<path>

  • ftps://[<username>[:<password>]@]<host>/<path>

See the QEMU manual for additional supported protocols and more info.

initial_size

The initial size of a sparse image disk created on block storage, in bytes.

The initial size is the number of bytes a sparse disk is initially allocated with when created on block storage. The initial size will be smaller than the provisioned size. If not specified the default initial size used by the system will be allocated.

interface

The type of interface driver used to connect the disk device to the virtual machine.

This attribute only makes sense for disks that are actually connected to virtual machines, and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

provisioned_size

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

qcow_version

The underlying QCOW version of a QCOW volume. The QCOW version specifies to the qemu which qemu version the volume supports. This field can be updated using the update API and will be reported only for QCOW volumes. It is determined by the version of the storage domain that the disk is created on. Storage domains with a version lower than V4 support QCOW2 volumes. V4 storage domains also support QCOW2v3. For more information about features of the different QCOW versions, see QCOW3.

read_only

Indicates if the disk is in read-only mode.

Since version 4.0 this attribute is not shown in the API and was moved to DiskAttachment.

Since version 4.1.2 of {engine-name} this attribute is deprecated, and it will be removed in the future. In order to attach a disk in read only mode use the read_only attribute of the DiskAttachment type. For example:

POST /ovirt-engine/api/vms/123/diskattachments
<disk_attachment>
  <read_only>true</read_only>
  ...
</disk_attachment>

sgio

Indicates whether SCSI passthrough is enable and its policy.

Setting a value of filtered/unfiltered will enable SCSI passthrough for a LUN disk with unprivileged/privileged SCSI I/O. To disable SCSI passthrough the value should be set to disabled

shareable

Indicates if the disk can be attached to multiple virtual machines.

When a disk is attached to multiple virtual machines it is the responsibility of the guest operating systems of those virtual machines to coordinate access to it, to avoid corruption of the data, for example using a shared file system like GlusterFS or GFS.

total_size

The total size of the disk including all of its snapshots, in bytes.

The total size is the number of bytes actually used by the disk plus the size of its snapshots. It won’t be populated for direct LUN and Cinder disks. For disks without snapshots the total size is equal to the actual size.

wipe_after_delete

Indicates if the disk’s blocks will be read back as zeros after it is deleted:

  • On block storage, the disk will be zeroed and only then deleted.

  • On file storage, since the file system already guarantees that previously removed blocks are read back as zeros, the disk will be deleted immediately.

Statistics exposed by the disk. For example:

<statistics>
  <statistic href="/ovirt-engine/api/disks/123/statistics/456" id="456">
    <name>data.current.read</name>
    <description>Read data rate</description>
    <kind>gauge</kind>
    <type>decimal</type>
    <unit>bytes_per_second</unit>
    <values>
      <value>
        <datum>1052</datum>
      </value>
    </values>
    <disk href="/ovirt-engine/api/disks/123" id="123"/>
  </statistic>
  ...
</statistics>

These statistics are not directly included when the disk is retrieved, only a link. To obtain the statistics follow the included link:

GET /ovirt-engine/api/disks/123/statistics

The storage domains associated with this disk.

Only required when the first disk is being added to a virtual machine that was not itself created from a template.

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

DiskAttachment struct

Describes how a disk is attached to a virtual machine.

Table 987. Attributes summary
Name Type Summary

active

Boolean

Defines whether the disk is active in the virtual machine it’s attached to.

bootable

Boolean

Defines whether the disk is bootable.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

interface

DiskInterface

The type of interface driver used to connect the disk device to the virtual machine.

logical_name

String

The logical name of the virtual machine’s disk, as seen from inside the virtual machine.

name

String

A human-readable name in plain text.

pass_discard

Boolean

Defines whether the virtual machine passes discard commands to the storage.

read_only

Boolean

Indicates whether the disk is connected to the virtual machine as read only.

uses_scsi_reservation

Boolean

Defines whether SCSI reservation is enabled for this disk.

active

Defines whether the disk is active in the virtual machine it’s attached to.

A disk attached to a virtual machine in an active status is connected to the virtual machine at run time and can be used.

logical_name

The logical name of the virtual machine’s disk, as seen from inside the virtual machine.

The logical name of a disk is reported only when the guest agent is installed and running inside the virtual machine.

For example, if the guest operating system is Linux and the disk is connected via a VirtIO interface, the logical name will be reported as /dev/vda:

<disk_attachment>
  ...
  <logical_name>/dev/vda</logical_name>
</disk_attachment>

If the guest operating system is Windows, the logical name will be reported as \\.\PHYSICALDRIVE0.

read_only

Indicates whether the disk is connected to the virtual machine as read only.

When adding a new disk attachment the default value is false.

<disk_attachment>
  ...
  <read_only>true</read_only>
</disk_attachment>

uses_scsi_reservation

Defines whether SCSI reservation is enabled for this disk.

Virtual machines with VIRTIO-SCSI passthrough enabled can set persistent SCSI reservations on disks. If they set persistent SCSI reservations, those virtual machines cannot be migrated to a different host because they would lose access to the disk, because SCSI reservations are specific to SCSI initiators, and therefore hosts. This scenario cannot be automatically detected. To avoid migrating these virtual machines, the user can set this attribute to true, to indicate the virtual machine is using SCSI reservations.

DiskBackup enum

Represents an enumeration of the backup mechanism that is enabled on the disk.

Table 989. Values summary
Name Summary

incremental

Incremental backup support.

none

No backup support.

DiskBackupMode enum

Represents an enumeration of backup modes

Table 990. Values summary
Name Summary

full

This disk supports full backup.

incremental

This disk supports incremental backup.

full

This disk supports full backup. You can query zero extents and download all disk data.

incremental

This disk supports incremental backup. You can query dirty extents and download changed blocks.

DiskContentType enum

The actual content residing on the disk.

Table 991. Values summary
Name Summary

backup_scratch

The disk contains protected VM backup data.

data

The disk contains data.

hosted_engine

The disk contains the Hosted Engine VM disk.

hosted_engine_configuration

The disk contains the Hosted Engine configuration disk.

hosted_engine_metadata

The disk contains the Hosted Engine metadata disk.

hosted_engine_sanlock

The disk contains the Hosted Engine Sanlock disk.

iso

The disk contains an ISO image to be used a CDROM device.

memory_dump_volume

The disk contains a memory dump from a live snapshot.

memory_metadata_volume

The disk contains memory metadata from a live snapshot.

ovf_store

The disk is an OVF store.

DiskFormat enum

The underlying storage format of disks.

Table 992. Values summary
Name Summary

cow

The Copy On Write format allows snapshots, with a small performance overhead.

raw

The raw format does not allow snapshots, but offers improved performance.

DiskInterface enum

The underlying storage interface of disks communication with controller.

Table 993. Values summary
Name Summary

ide

Legacy controller device.

sata

SATA controller device.

spapr_vscsi

Para-virtualized device supported by the IBM pSeries family of machines, using the SCSI protocol.

virtio

Virtualization interface where just the guest’s device driver knows it is running in a virtual environment.

virtio_scsi

Para-virtualized SCSI controller device.

ide

Legacy controller device. Works with almost all guest operating systems, so it is good for compatibility. Performance is lower than with the other alternatives.

virtio

Virtualization interface where just the guest’s device driver knows it is running in a virtual environment. Enables guests to get high performance disk operations.

virtio_scsi

Para-virtualized SCSI controller device. Fast interface with the guest via direct physical storage device address, using the SCSI protocol.

DiskProfile struct

Table 994. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

DiskSnapshot struct

Table 996. Attributes summary
Name Type Summary

active

Boolean

Indicates if the disk is visible to the virtual machine.

actual_size

Integer

The actual size of the disk, in bytes.

alias

String

backup

DiskBackup

The backup behavior supported by the disk.

backup_mode

DiskBackupMode

The type of the disk backup (full/incremental), visible only when the disk backup is in progress.

bootable

Boolean

Indicates if the disk is marked as bootable.

comment

String

Free text containing comments about this object.

content_type

DiskContentType

Indicates the actual content residing on the disk.

description

String

A human-readable description in plain text.

external_disk

String

Use external disk.

format

DiskFormat

The underlying storage format.

id

String

A unique identifier.

image_id

String

initial_size

Integer

The initial size of a sparse image disk created on block storage, in bytes.

interface

DiskInterface

The type of interface driver used to connect the disk device to the virtual machine.

logical_name

String

lun_storage

HostStorage

name

String

A human-readable name in plain text.

propagate_errors

Boolean

Indicates if disk errors should cause virtual machine to be paused or if disk errors should be propagated to the the guest operating system instead.

provisioned_size

Integer

The virtual size of the disk, in bytes.

qcow_version

QcowVersion

The underlying QCOW version of a QCOW volume.

read_only

Boolean

Indicates if the disk is in read-only mode.

sgio

ScsiGenericIO

Indicates whether SCSI passthrough is enable and its policy.

shareable

Boolean

Indicates if the disk can be attached to multiple virtual machines.

sparse

Boolean

Indicates if the physical storage for the disk should not be preallocated.

status

DiskStatus

The status of the disk device.

storage_type

DiskStorageType

total_size

Integer

The total size of the disk including all of its snapshots, in bytes.

uses_scsi_reservation

Boolean

wipe_after_delete

Boolean

Indicates if the disk’s blocks will be read back as zeros after it is deleted:

- On block storage, the disk will be zeroed and only then deleted.

active

Indicates if the disk is visible to the virtual machine.

When adding a disk attachment to a virtual machine, if the server accepts requests that do not contain this attribute the result is undefined. In some cases the disk will be automatically activated and in other cases it will not. To avoid issues it is strongly recommended to always include the this attribute with the desired value.

actual_size

The actual size of the disk, in bytes.

The actual size is the number of bytes actually used by the disk. It will be smaller than the provisioned size for disks that use the cow format.

bootable

Indicates if the disk is marked as bootable.

This attribute only makes sense for disks that are actually connected to virtual machines, and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

external_disk

Use external disk.

An external disk can be a path to a local file or a block device, or a URL supported by QEMU such as:

  • nbd:<host>:<port>[:exportname=<export>]

  • nbd:unix:</path>[:exportname=<export>]

  • http://[<username>[:<password>]@]<host>/<path>

  • https://[<username>[:<password>]@]<host>/<path>

  • ftp://[<username>[:<password>]@]<host>/<path>

  • ftps://[<username>[:<password>]@]<host>/<path>

See the QEMU manual for additional supported protocols and more info.

initial_size

The initial size of a sparse image disk created on block storage, in bytes.

The initial size is the number of bytes a sparse disk is initially allocated with when created on block storage. The initial size will be smaller than the provisioned size. If not specified the default initial size used by the system will be allocated.

interface

The type of interface driver used to connect the disk device to the virtual machine.

This attribute only makes sense for disks that are actually connected to virtual machines, and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

provisioned_size

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

qcow_version

The underlying QCOW version of a QCOW volume. The QCOW version specifies to the qemu which qemu version the volume supports. This field can be updated using the update API and will be reported only for QCOW volumes. It is determined by the version of the storage domain that the disk is created on. Storage domains with a version lower than V4 support QCOW2 volumes. V4 storage domains also support QCOW2v3. For more information about features of the different QCOW versions, see QCOW3.

read_only

Indicates if the disk is in read-only mode.

Since version 4.0 this attribute is not shown in the API and was moved to DiskAttachment.

Since version 4.1.2 of {engine-name} this attribute is deprecated, and it will be removed in the future. In order to attach a disk in read only mode use the read_only attribute of the DiskAttachment type. For example:

POST /ovirt-engine/api/vms/123/diskattachments
<disk_attachment>
  <read_only>true</read_only>
  ...
</disk_attachment>

sgio

Indicates whether SCSI passthrough is enable and its policy.

Setting a value of filtered/unfiltered will enable SCSI passthrough for a LUN disk with unprivileged/privileged SCSI I/O. To disable SCSI passthrough the value should be set to disabled

shareable

Indicates if the disk can be attached to multiple virtual machines.

When a disk is attached to multiple virtual machines it is the responsibility of the guest operating systems of those virtual machines to coordinate access to it, to avoid corruption of the data, for example using a shared file system like GlusterFS or GFS.

total_size

The total size of the disk including all of its snapshots, in bytes.

The total size is the number of bytes actually used by the disk plus the size of its snapshots. It won’t be populated for direct LUN and Cinder disks. For disks without snapshots the total size is equal to the actual size.

wipe_after_delete

Indicates if the disk’s blocks will be read back as zeros after it is deleted:

  • On block storage, the disk will be zeroed and only then deleted.

  • On file storage, since the file system already guarantees that previously removed blocks are read back as zeros, the disk will be deleted immediately.

Statistics exposed by the disk. For example:

<statistics>
  <statistic href="/ovirt-engine/api/disks/123/statistics/456" id="456">
    <name>data.current.read</name>
    <description>Read data rate</description>
    <kind>gauge</kind>
    <type>decimal</type>
    <unit>bytes_per_second</unit>
    <values>
      <value>
        <datum>1052</datum>
      </value>
    </values>
    <disk href="/ovirt-engine/api/disks/123" id="123"/>
  </statistic>
  ...
</statistics>

These statistics are not directly included when the disk is retrieved, only a link. To obtain the statistics follow the included link:

GET /ovirt-engine/api/disks/123/statistics

The storage domains associated with this disk.

Only required when the first disk is being added to a virtual machine that was not itself created from a template.

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

DiskStatus enum

Current status representation for disk.

Table 998. Values summary
Name Summary

illegal

Disk cannot be accessed by the virtual machine, and the user needs to take action to resolve the issue.

locked

The disk is being used by the system, therefore it cannot be accessed by virtual machines at this point.

ok

The disk status is normal and can be accessed by the virtual machine.

locked

The disk is being used by the system, therefore it cannot be accessed by virtual machines at this point. This is usually a temporary status, until the disk is freed.

DiskStorageType enum

Table 999. Values summary
Name Summary

cinder

image

lun

managed_block_storage

A storage type, used for a storage domain that was created using a cinderlib driver.

DiskType enum

Table 1000. Values summary
Name Summary

data

system

Display struct

Represents a graphic console configuration.

Table 1001. Attributes summary
Name Type Summary

address

String

The IP address of the guest to connect the graphic console client to.

allow_override

Boolean

Indicates if to override the display address per host.

certificate

Certificate

The TLS certificate in case of a TLS connection.

copy_paste_enabled

Boolean

Indicates whether a user is able to copy and paste content from an external host into the graphic console.

disconnect_action

String

Returns the action that will take place when the graphic console is disconnected.

disconnect_action_delay

Integer

Delay (in minutes) before the graphic console disconnect action is carried out.

file_transfer_enabled

Boolean

Indicates if a user is able to drag and drop files from an external host into the graphic console.

keyboard_layout

String

The keyboard layout to use with this graphic console.

monitors

Integer

The number of monitors opened for this graphic console.

port

Integer

The port address on the guest to connect the graphic console client to.

proxy

String

The proxy IP which will be used by the graphic console client to connect to the guest.

secure_port

Integer

The secured port address on the guest, in case of using TLS, to connect the graphic console client to.

single_qxl_pci

Boolean

The engine now sets it automatically according to the operating system.

smartcard_enabled

Boolean

Indicates if to use smart card authentication.

type

DisplayType

The graphic console protocol type.

allow_override

Indicates if to override the display address per host. Relevant only for the Host.display attribute. If set, the graphical console address of a virtual machine will be overridden by the host specified display address. if not set, the graphical console address of a virtual machine will not be overridden.

certificate

The TLS certificate in case of a TLS connection. If TLS isn’t enabled then it won’t be reported.

copy_paste_enabled

Indicates whether a user is able to copy and paste content from an external host into the graphic console. This option is only available for the SPICE console type.

disconnect_action

Returns the action that will take place when the graphic console is disconnected. The options are:

none

No action is taken.

lock_screen

Locks the currently active user session.

logout

Logs out the currently active user session.

reboot

Initiates a graceful virtual machine reboot.

shutdown

Initiates a graceful virtual machine shutdown.

This option is only available for the SPICE console type.

disconnect_action_delay

Delay (in minutes) before the graphic console disconnect action is carried out. This option is only available for Shutdown disconnect action.

file_transfer_enabled

Indicates if a user is able to drag and drop files from an external host into the graphic console. This option is only available for the SPICE console type.

keyboard_layout

The keyboard layout to use with this graphic console. This option is only available for the VNC console type. If no keyboard is enabled then it won’t be reported.

monitors

The number of monitors opened for this graphic console. This option is only available for the SPICE console type. Possible values are 1, 2 or 4.

proxy

The proxy IP which will be used by the graphic console client to connect to the guest. It is useful when the client is outside the guest’s network. This option is only available for the SPICE console type. This proxy can be set in global configuration, cluster level, virtual machine pool level or disabled per virtual machine. If the proxy is set in any of this mentioned places and not disabled for the virtual machine, it will be returned by this method. If the proxy is not set, nothing will be reported.

secure_port

The secured port address on the guest, in case of using TLS, to connect the graphic console client to. If TLS isn’t enabled then it won’t be reported.

single_qxl_pci

The engine now sets it automatically according to the operating system. Therefore, it has been deprecated since 4.4.5. Indicates if to use one PCI slot for each monitor or to use a single PCI channel for all multiple monitors. This option is only available for the SPICE console type and only for connecting a guest Linux based OS.

smartcard_enabled

Indicates if to use smart card authentication. This option is only available for the SPICE console type.

DisplayType enum

Represents an enumeration of the protocol used to connect to the graphic console of the virtual machine.

Table 1002. Values summary
Name Summary

spice

Display of type SPICE.

vnc

Display of type VNC.

spice

Display of type SPICE. See SPICE documentation for more details.

vnc

Display of type VNC. VNC stands for Virtual Network Computing, and it is a graphical desktop sharing system that uses RFB (Remote Frame Buffer) protocol to remotely control another machine.

Dns struct

Represents the DNS resolver configuration.

Table 1003. Attributes summary
Name Type Summary

search_domains

Host[]

Array of hosts serving as search domains.

servers

Host[]

Array of hosts serving as DNS servers.

DnsResolverConfiguration struct

Represents the DNS resolver configuration.

Table 1004. Attributes summary
Name Type Summary

name_servers

String[]

Array of addresses of name servers.

name_servers

Array of addresses of name servers. Either IPv4 or IPv6 addresses may be specified.

Domain struct

This type represents a directory service domain.

Table 1005. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

user

User

A reference to a list of all users in the directory service. This information is used to add new users to the {product-name} environment.

DynamicCpu struct

Configuration of the Dynamic CPUs of a virtual machine.

Table 1007. Attributes summary
Name Type Summary

cpu_tune

CpuTune

topology

CpuTopology

EntityExternalStatus enum

Type representing an external entity status.

Table 1008. Values summary
Name Summary

error

The external entity status is erroneous.

failure

The external entity has an issue that causes failures.

info

There external entity status is okay but with some information that might be relevant.

ok

The external entity status is okay.

warning

The external entity status is okay but with an issue that might require attention.

error

The external entity status is erroneous. This might require a moderate attention.

failure

The external entity has an issue that causes failures. This might require immediate attention.

EntityProfileDetail struct

Table 1009. Attributes summary
Name Type Summary

profile_details

ProfileDetail[]

ErrorHandling struct

Table 1010. Attributes summary
Name Type Summary

on_error

MigrateOnError

Event struct

Type representing an event.

Table 1011. Attributes summary
Name Type Summary

code

Integer

The event code.

comment

String

Free text containing comments about this object.

correlation_id

String

The event correlation identifier.

custom_data

String

Free text representing custom event data.

custom_id

Integer

A custom event identifier.

description

String

A human-readable description in plain text.

flood_rate

Integer

Defines the flood rate.

id

String

A unique identifier.

index

Integer

The numeric index of this event.

log_on_host

Boolean

Specifies whether the event should also be written to the ${hypervisor.

name

String

A human-readable name in plain text.

origin

String

Free text identifying the origin of the event.

severity

LogSeverity

The event severity.

time

Date

The event time.

correlation_id

The event correlation identifier. Used in order to correlate several events together.

flood_rate

Defines the flood rate. This prevents flooding in case an event appeared more than once in the defined rate. Defaults is 30 seconds.

index

The numeric index of this event. The indexes of events are always increasing, so events with higher indexes are guaranteed to be older than events with lower indexes.

In the current implementation of the engine, the id attribute has the same value as this index attribute. That is an implementation detail that the user of the API should not rely on. In the future the id attribute may be changed to an arbitrary string, containing non numeric characters and no implicit order. On the other hand this index attribute is guaranteed to stay as integer and ordered.

log_on_host

Specifies whether the event should also be written to the ${hypervisor.name} log. If no host is specified the event description will be written to all hosts. Default is false.

Reference to the cluster service. Event can be associated with a cluster.

Reference to the data center service. Event can be associated with a data center.

Reference to the host service. Event can be associated with a host.

Reference to the storage domain service. Event can be associated with a storage domain.

Reference to the template service. Event can be associated with a template.

Reference to the user service. Event can be associated with a user.

Reference to the virtual machine service. Event can be associated with a virtual machine.

EventSubscription struct

Table 1013. Attributes summary
Name Type Summary

address

String

The email address to which notifications should be sent.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

event

NotifiableEvent

The subscribed-for event.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

notification_method

NotificationMethod

The notification method: SMTP or SNMP.

user

User

The subscribing user.

address

The email address to which notifications should be sent.

When not provided, notifications are sent to the user’s email. Only a single address per user is currently supported. If a subscription with a different email address to that of existing subscriptions is added, a 409 (CONFLICT) status is returned with an explanation that the provided address conflicts with an existing address of an event-subscription for this user.

This field might be deprecated in the future, and notifications will always be sent on the user’s email address.

event

The subscribed-for event.

(Combined with the user, Uniquely identifies the event-subscription).

notification_method

The notification method: SMTP or SNMP.

Currently only SMTP supported by API. Support for SNMP will be added in the future.

user

The subscribing user.

Combined with the event-name, uniquely identifies the event-subscription.

ExternalComputeResource struct

Table 1014. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

provider

String

url

String

user

String

ExternalDiscoveredHost struct

Table 1016. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

ip

String

last_report

String

mac

String

name

String

A human-readable name in plain text.

subnet_name

String

ExternalHost struct

Represents a host provisioned by a host provider (such as Foreman/Satellite).

See Foreman documentation for more details. See Satellite documentation for more details on Red Hat Satellite.

Table 1018. Attributes summary
Name Type Summary

address

String

The address of the host, either IP address of FQDN (Fully Qualified Domain Name).

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

ExternalHostGroup struct

Table 1020. Attributes summary
Name Type Summary

architecture_name

String

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

domain_name

String

id

String

A unique identifier.

name

String

A human-readable name in plain text.

operating_system_name

String

subnet_name

String

ExternalHostProvider struct

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

See Foreman documentation for more details. See Satellite documentation for more details on Red Hat Satellite.

Table 1022. Attributes summary
Name Type Summary

authentication_url

String

Defines the external provider authentication URL address.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

password

String

Defines password for the user during the authentication process.

properties

Property[]

Array of provider name/value properties.

requires_authentication

Boolean

Defines whether provider authentication is required or not.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

A reference to the compute resource as represented in the host provider. Each host provider optionally has the engine defined as a compute resource, which allows to create virtual machines in the engine. This compute resource details are used in the Bare-Metal provisioning use-case, in order to deploy the hypervisor.

A reference to the discovered hosts in the host provider. Discovered hosts are hosts that were not provisioned yet.

A reference to the host groups in the host provider. Host group contains different properties that the host provider applies on all hosts that are member of this group. Such as installed software, system definitions, passwords and more.

ExternalNetworkProviderConfiguration struct

Describes how an external network provider is provisioned on a host.

Table 1024. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

ExternalProvider struct

Represents an external provider.

Table 1026. Attributes summary
Name Type Summary

authentication_url

String

Defines the external provider authentication URL address.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

password

String

Defines password for the user during the authentication process.

properties

Property[]

Array of provider name/value properties.

requires_authentication

Boolean

Defines whether provider authentication is required or not.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

ExternalStatus enum

Represents an external status. This status is currently used for hosts and storage domains, and allows an external system to update status of objects it is aware of.

Table 1027. Values summary
Name Summary

error

Error status.

failure

Failure status.

info

Info status.

ok

OK status.

warning

Warning status.

error

Error status. There is some kind of error in the relevant object.

failure

Failure status. The relevant object is failing.

info

Info status. The relevant object is in OK status, but there is an information available that might be relevant for the administrator.

ok

OK status. The relevant object is working well.

warning

Warning status. The relevant object is working well, but there is some warning that might be relevant for the administrator.

ExternalSystemType enum

Represents the type of the external system that is associated with the step.

Table 1028. Values summary
Name Summary

gluster

Represents Gluster as the external system which is associated with the step.

vdsm

Represents VDSM as the external system which is associated with the step.

ExternalTemplateImport struct

Describes the parameters for the template import operation from an external system. Currently supports OVA only.

Table 1029. Attributes summary
Name Type Summary

clone

Boolean

Optional.

url

String

The URL to be passed to the engine.

clone

Optional. Indicates if the identifiers of the imported template should be regenerated.

By default when a template is imported the identifiers are preserved. This means that the same template can’t be imported multiple times, as that identifiers needs to be unique. To allow importing the same template multiple times set this parameter to true, as the default is false.

url

The URL to be passed to the engine.

Example:

ova:///mnt/ova/ova_file.ova

Optional. Specifies the CPU profile of the resulting template.

Optional. Specifies the quota that will be applied to the resulting template.

The template entity used to specify a name for the newly created template.

If a name is not specified, the source template name will be used.

ExternalVmImport struct

Describes the parameters for the virtual machine import operation from an external system.

Table 1031. Attributes summary
Name Type Summary

name

String

The name of the virtual machine to be imported, as is defined within the external system.

password

String

The password to authenticate against the external hypervisor system.

provider

ExternalVmProviderType

The type of external virtual machine provider.

sparse

Boolean

Optional.

url

String

The URL to be passed to the virt-v2v tool for conversion.

username

String

The username to authenticate against the external hypervisor system.

sparse

Optional. Specifies the disk allocation policy of the resulting virtual machine: true for sparse, false for preallocated.

If not specified: - When importing an OVA that was produced by oVirt, it will be determined according to the configuration of the disk within the OVF. - Otherwise, it will be set to true.

url

The URL to be passed to the virt-v2v tool for conversion.

Example:

vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1

More examples can be found at http://libguestfs.org/virt-v2v.1.html.

Optional. Specifies the CPU profile of the resulting virtual machine.

Optional. The name of the ISO containing drivers that can be used during the virt-v2v conversion process.

Optional. Specifies the host (using host’s ID) to be used for the conversion process. If not specified, one is selected automatically.

Optional. Specifies the quota that will be applied to the resulting virtual machine.

The virtual machine entity used to specify a name for the newly created virtual machine.

If a name is not specified, the source virtual machine name will be used.

ExternalVmProviderType enum

Describes the type of external hypervisor system.

Table 1033. Values summary
Name Summary

kvm

vmware

xen

Fault struct

Table 1034. Attributes summary
Name Type Summary

detail

String

reason

String

FenceType enum

Type representing the type of the fence operation.

Table 1035. Values summary
Name Summary

manual

Manual host fencing via power management.

restart

Restart the host via power management.

start

Start the host via power management.

status

Check the host power status via power management.

stop

Stop the host via power management.

FencingPolicy struct

Type representing a cluster fencing policy.

Table 1036. Attributes summary
Name Type Summary

enabled

Boolean

Enable or disable fencing on this cluster.

skip_if_connectivity_broken

SkipIfConnectivityBroken

If enabled, we will not fence a host in case more than a configurable percentage of hosts in the cluster lost connectivity as well.

skip_if_gluster_bricks_up

Boolean

A flag indicating if fencing should be skipped if Gluster bricks are up and running in the host being fenced.

skip_if_gluster_quorum_not_met

Boolean

A flag indicating if fencing should be skipped if Gluster bricks are up and running and Gluster quorum will not be met without those bricks.

skip_if_sd_active

SkipIfSdActive

If enabled, we will skip fencing in case the host maintains its lease in the storage.

skip_if_connectivity_broken

If enabled, we will not fence a host in case more than a configurable percentage of hosts in the cluster lost connectivity as well. This comes to prevent fencing storm in cases where there is a global networking issue in the cluster.

skip_if_gluster_bricks_up

A flag indicating if fencing should be skipped if Gluster bricks are up and running in the host being fenced. This flag is optional, and the default value is false.

skip_if_gluster_quorum_not_met

A flag indicating if fencing should be skipped if Gluster bricks are up and running and Gluster quorum will not be met without those bricks. This flag is optional, and the default value is false.

skip_if_sd_active

If enabled, we will skip fencing in case the host maintains its lease in the storage. It means that if the host still has storage access then it won’t get fenced.

File struct

Table 1037. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

content

String

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

type

String

Filter struct

Table 1039. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

position

Integer

FipsMode enum

Representation of the FIPS mode to the cluster.

Table 1041. Values summary
Name Summary

disabled

The FIPS mode is disabled.

enabled

The FIPS mode is enabled.

undefined

The FIPS mode is not yet evaluated.

disabled

The FIPS mode is disabled.

Its implication is that the FIPS mode is disabled and the hosts within should be with FIPS mode disabled, otherwise they would be non-operational.

enabled

The FIPS mode is enabled.

Its implication is that the FIPS mode is enabled and the hosts within should be with FIPS mode enabled, otherwise they should be non-operational.

undefined

The FIPS mode is not yet evaluated.

Currently, its implication is that the FIPS mode is undetermined. Once a host is added, this value will switch according to the host settings.

FirewallType enum

Describes all firewall types supported by the system.

Table 1042. Values summary
Name Summary

firewalld

FirewallD firewall type.

iptables

IPTables firewall type.

firewalld

FirewallD firewall type.

When a cluster has the firewall type set to firewalld, the firewalls of all hosts in the cluster will be configured using firewalld. FirewallD replaced IPTables in version 4.2. It simplifies configuration using a command line program and dynamic configuration.

iptables

IPTables firewall type.

iptables is deprecated.

Floppy struct

The underlying representation of a floppy file.

Table 1043. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

file

File

File object that represent the Floppy device’s content and its type.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

FopStatistic struct

Table 1045. Attributes summary
Name Type Summary

name

String

statistics

Statistic[]

GlusterBrick struct

Table 1046. Attributes summary
Name Type Summary

brick_dir

String

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

device

String

fs_name

String

gluster_clients

GlusterClient[]

id

String

A unique identifier.

memory_pools

GlusterMemoryPool[]

mnt_options

String

name

String

A human-readable name in plain text.

pid

Integer

port

Integer

server_id

String

status

GlusterBrickStatus

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

GlusterBrickAdvancedDetails struct

Table 1048. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

device

String

fs_name

String

gluster_clients

GlusterClient[]

id

String

A unique identifier.

memory_pools

GlusterMemoryPool[]

mnt_options

String

name

String

A human-readable name in plain text.

pid

Integer

port

Integer

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

GlusterBrickMemoryInfo struct

Table 1050. Attributes summary
Name Type Summary

memory_pools

GlusterMemoryPool[]

GlusterBrickStatus enum

Table 1051. Values summary
Name Summary

down

Brick is in down state, the data cannot be stored or retrieved from it.

unknown

When the status cannot be determined due to host being non-responsive.

up

Brick is in up state, the data can be stored or retrieved from it.

GlusterClient struct

Table 1052. Attributes summary
Name Type Summary

bytes_read

Integer

bytes_written

Integer

client_port

Integer

host_name

String

GlusterHook struct

Table 1053. Attributes summary
Name Type Summary

checksum

String

comment

String

Free text containing comments about this object.

conflict_status

Integer

conflicts

String

content

String

content_type

HookContentType

description

String

A human-readable description in plain text.

gluster_command

String

id

String

A unique identifier.

name

String

A human-readable name in plain text.

stage

HookStage

status

GlusterHookStatus

GlusterHookStatus enum

Table 1055. Values summary
Name Summary

disabled

Hook is disabled in the cluster.

enabled

Hook is enabled in the cluster.

missing

Unknown/missing hook status.

GlusterMemoryPool struct

Table 1056. Attributes summary
Name Type Summary

alloc_count

Integer

cold_count

Integer

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

hot_count

Integer

id

String

A unique identifier.

max_alloc

Integer

max_stdalloc

Integer

name

String

A human-readable name in plain text.

padded_size

Integer

pool_misses

Integer

type

String

GlusterServerHook struct

Table 1057. Attributes summary
Name Type Summary

checksum

String

comment

String

Free text containing comments about this object.

content_type

HookContentType

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

status

GlusterHookStatus

GlusterState enum

Table 1059. Values summary
Name Summary

down

unknown

up

GlusterVolume struct

Table 1060. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

disperse_count

Integer

id

String

A unique identifier.

name

String

A human-readable name in plain text.

options

Option[]

redundancy_count

Integer

replica_count

Integer

status

GlusterVolumeStatus

stripe_count

Integer

transport_types

TransportType[]

volume_type

GlusterVolumeType

GlusterVolumeProfileDetails struct

Table 1062. Attributes summary
Name Type Summary

brick_profile_details

BrickProfileDetail[]

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

nfs_profile_details

NfsProfileDetail[]

GlusterVolumeStatus enum

Table 1063. Values summary
Name Summary

down

Volume needs to be started, for clients to be able to mount and use it.

unknown

When the status cannot be determined due to host being non-responsive.

up

Volume is started, and can be mounted and used by clients.

GlusterVolumeType enum

Type representing the type of Gluster Volume.

Table 1064. Values summary
Name Summary

disperse

Dispersed volumes are based on erasure codes, providing space-efficient protection against disk or server failures.

distribute

Distributed volumes distributes files throughout the bricks in the volume.

distributed_disperse

Distributed dispersed volumes distribute files across dispersed subvolumes.

distributed_replicate

Distributed replicated volumes distributes files across replicated bricks in the volume.

distributed_stripe

Distributed striped volumes stripe data across two or more nodes in the cluster.

distributed_striped_replicate

Distributed striped replicated volumes distributes striped data across replicated bricks in the cluster.

replicate

Replicated volumes replicates files across bricks in the volume.

stripe

Striped volumes stripes data across bricks in the volume.

striped_replicate

Striped replicated volumes stripes data across replicated bricks in the cluster.

disperse

Dispersed volumes are based on erasure codes, providing space-efficient protection against disk or server failures.

Dispersed volumes an encoded fragment of the original file to each brick in a way that only a subset of the fragments is needed to recover the original file. The number of bricks that can be missing without losing access to data is configured by the administrator on volume creation time.

distribute

Distributed volumes distributes files throughout the bricks in the volume.

Distributed volumes can be used where the requirement is to scale storage and the redundancy is either not important or is provided by other hardware/software layers.

distributed_disperse

Distributed dispersed volumes distribute files across dispersed subvolumes.

This has the same advantages of distribute replicate volumes, but using disperse to store the data into the bricks.

distributed_replicate

Distributed replicated volumes distributes files across replicated bricks in the volume.

Distributed replicated volumes can be used in environments where the requirement is to scale storage and high-reliability is critical. Distributed replicated volumes also offer improved read performance in most environments.

distributed_stripe

Distributed striped volumes stripe data across two or more nodes in the cluster.

Distributed striped volumes should be used where the requirement is to scale storage and in high concurrency environments accessing very large files is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not recommended and it will be removed in future release.

distributed_striped_replicate

Distributed striped replicated volumes distributes striped data across replicated bricks in the cluster.

For best results, distributed striped replicated volumes should be used in highly concurrent environments where parallel access of very large files and performance is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not recommended and it will be removed in future release.

replicate

Replicated volumes replicates files across bricks in the volume.

Replicated volumes can be used in environments where high-availability and high-reliability are critical.

stripe

Striped volumes stripes data across bricks in the volume.

For best results, striped volumes should only in high concurrency environments accessing very large files.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not recommended and it will be removed in future release.

striped_replicate

Striped replicated volumes stripes data across replicated bricks in the cluster.

For best results, striped replicated volumes should be used in highly concurrent environments where there is parallel access of very large files and performance is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not recommended and it will be removed in future release.

GracePeriod struct

Table 1065. Attributes summary
Name Type Summary

expiry

Integer

GraphicsConsole struct

Table 1066. Attributes summary
Name Type Summary

address

String

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

port

Integer

protocol

GraphicsType

tls_port

Integer

GraphicsType enum

The graphics protocol used to connect to the graphic console.

Table 1068. Values summary
Name Summary

spice

Graphics protocol of type SPICE.

vnc

Graphics protocol of type VNC.

spice

Graphics protocol of type SPICE. See SPICE documentation for more details.

vnc

Graphics protocol of type VNC. VNC stands for Virtual Network Computing, and it is a graphical desktop sharing system that uses RFB (Remote Frame Buffer) protocol to remotely control another machine.

Group struct

This type represents all groups in the directory service.

Table 1069. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

domain_entry_id

String

The containing directory service domain id.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

namespace

String

Namespace where group resides.

A link to the roles sub-collection for roles attached to this group.

Used only to represent the initial role assignments for a new group; thereafter, modification of role assignments is only supported via the roles sub-collection.

GuestOperatingSystem struct

Represents an operating system installed on the virtual machine.

To get that information send a request like this:

GET /ovirt-engine/api/vms/123

The result will be like this:

<vm href="/ovirt-engine/api/vms/123" id="123">
...
  <guest_operating_system>
    <architecture>x86_64</architecture>
    <codename>Maipo</codename>
    <distribution>Red Hat Enterprise Linux Server</distribution>
    <family>Linux</family>
    <kernel>
      <version>
        <build>0</build>
        <full_version>3.10.0-514.10.2.el7.x86_64</full_version>
        <major>3</major>
        <minor>10</minor>
        <revision>514</revision>
      </version>
    </kernel>
    <version>
      <full_version>7.3</full_version>
      <major>7</major>
      <minor>3</minor>
    </version>
  </guest_operating_system>
</vm>
Table 1071. Attributes summary
Name Type Summary

architecture

String

The architecture of the operating system, such as x86_64.

codename

String

Code name of the operating system, such as Maipo.

distribution

String

Full name of operating system distribution.

family

String

Family of operating system, such as Linux.

kernel

Kernel

Kernel version of the operating system.

version

Version

Version of the installed operating system.

HardwareInformation struct

Represents hardware information of host.

To get that information send a request like this:

GET /ovirt-engine/api/hosts/123

The result will be like this:

<host href="/ovirt-engine/api/hosts/123" id="123">
  ...
  <hardware_information>
    <family>Red Hat Enterprise Linux</family>
    <manufacturer>Red Hat</manufacturer>
    <product_name>RHEV Hypervisor</product_name>
    <serial_number>01234567-89AB-CDEF-0123-456789ABCDEF</serial_number>
    <supported_rng_sources>
      <supported_rng_source>random</supported_rng_source>
    </supported_rng_sources>
    <uuid>12345678-9ABC-DEF0-1234-56789ABCDEF0</uuid>
    <version>1.2-34.5.el7ev</version>
  </hardware_information>
  ...
</application>
Table 1072. Attributes summary
Name Type Summary

family

String

Type of host’s CPU.

manufacturer

String

Manufacturer of the host’s machine and hardware vendor.

product_name

String

Host’s product name (for example RHEV Hypervisor).

serial_number

String

Unique ID for host’s chassis.

supported_rng_sources

RngSource[]

Supported sources of random number generator.

uuid

String

Unique ID for each host.

version

String

Unique name for each of the manufacturer.

HighAvailability struct

Type representing high availability of a virtual machine.

Table 1073. Attributes summary
Name Type Summary

enabled

Boolean

Define if the virtual machine is considered highly available.

priority

Integer

Indicates the priority of the virtual machine inside the run and migration queues.

enabled

Define if the virtual machine is considered highly available. Configuring a VM lease is highly recommended (refer to that section) in order to prevent split-brain scenarios. Use a boot disk’s storage-domain or any other active storage-domain.

priority

Indicates the priority of the virtual machine inside the run and migration queues.

Virtual machines with higher priorities will be started and migrated before virtual machines with lower priorities.

The value is an integer between 0 and 100. The higher the value, the higher the priority.

The graphical user interface (GUI) does not allow specifying all the possible values, instead it only allows you to select Low, Medium or High. When the value is set using the API, the GUI will set the label as follows:

API Value GUI Label

0 - 25

Low

26 - 74

Medium

75 - 100

High

When the label is selected using the GUI, the value in the API will be set as follows:

GUI Label API Value

Low

1

Medium

50

High

100

Hook struct

Represents a hook.

Table 1074. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

event_name

String

Name of the event to execute the hook on.

id

String

A unique identifier.

md5

String

Checksum of the hook.

name

String

A human-readable name in plain text.

HookContentType enum

Represents content type of hook script.

Table 1076. Values summary
Name Summary

binary

Binary content type of the hook.

text

Text content type of the hook.

HookStage enum

Type represents a stage of volume event at which hook executes.

Table 1077. Values summary
Name Summary

post

Stage after start of volume.

pre

Stage before start of volume.

HookStatus enum

Type represents the status of a hook.

Table 1078. Values summary
Name Summary

disabled

Hook is disabled.

enabled

Hook is enabled.

missing

Hook is missing.

Host struct

Type representing a host.

Table 1079. Attributes summary
Name Type Summary

address

String

The host address (FQDN/IP).

auto_numa_status

AutoNumaStatus

The host auto non uniform memory access (NUMA) status.

certificate

Certificate

The host certificate.

comment

String

Free text containing comments about this object.

cpu

Cpu

The CPU type of this host.

description

String

A human-readable description in plain text.

device_passthrough

HostDevicePassthrough

Specifies whether host device passthrough is enabled on this host.

display

Display

Optionally specify the display address of this host explicitly.

external_status

ExternalStatus

The host external status.

hardware_information

HardwareInformation

The host hardware information.

hosted_engine

HostedEngine

The self-hosted engine status of this host.

id

String

A unique identifier.

iscsi

IscsiDetails

The host iSCSI details.

kdump_status

KdumpStatus

The host KDUMP status.

ksm

Ksm

Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pages to a single page reference.

libvirt_version

Version

The host libvirt version.

max_scheduling_memory

Integer

The max scheduling memory on this host in bytes.

memory

Integer

The amount of physical memory on this host in bytes.

name

String

A human-readable name in plain text.

network_operation_in_progress

Boolean

Specifies whether a network-related operation, such as 'setup networks', 'sync networks', or 'refresh capabilities', is currently being executed on this host.

numa_supported

Boolean

Specifies whether non uniform memory access (NUMA) is supported on this host.

os

OperatingSystem

The operating system on this host.

override_iptables

Boolean

Specifies whether we should override firewall definitions.

ovn_configured

Boolean

Indicates if the host has correctly configured OVN.

port

Integer

The host port.

power_management

PowerManagement

The host power management definitions.

protocol

HostProtocol

The protocol that the engine uses to communicate with the host.

reinstallation_required

Boolean

Specifies whether the host should be reinstalled.

root_password

String

When creating a new host, a root password is required if the password authentication method is chosen, but this is not subsequently included in the representation.

se_linux

SeLinux

The host SElinux status.

spm

Spm

The host storage pool manager (SPM) status and definition.

ssh

Ssh

The SSH definitions.

status

HostStatus

The host status.

status_detail

String

The host status details.

summary

VmSummary

The virtual machine summary - how many are active, migrating and total.

transparent_huge_pages

TransparentHugePages

Transparent huge page support expands the size of memory pages beyond the standard 4 KiB limit.

type

HostType

Indicates if the host contains a full installation of the operating system or a scaled-down version intended only to host virtual machines.

update_available

Boolean

Specifies whether there is an oVirt-related update on this host.

version

Version

The version of VDSM.

vgpu_placement

VgpuPlacement

Specifies the vGPU placement strategy.

external_status

The host external status. This can be used by third-party software to change the host external status in case of an issue. This has no effect on the host lifecycle, unless a third-party software checks for this status and acts accordingly.

hosted_engine

The self-hosted engine status of this host.

When a host or collection of hosts is retrieved, this attribute is not included unless the all_content parameter of the operation is explicitly set to true. See the documentation of the operations that retrieve one or multiple hosts for details.

kdump_status

The host KDUMP status. KDUMP happens when the host kernel has crashed and it is now going through memory dumping.

ksm

Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pages to a single page reference. This helps with optimization for memory density.

For example, to enable KSM for host 123, send a request like this:

PUT /ovirt-engine/api/hosts/123

With a request body like this:

<host>
  <ksm>
    <enabled>true</enabled>
  </ksm>
</host>

libvirt_version

The host libvirt version. For more information on libvirt please go to libvirt.

network_operation_in_progress

Specifies whether a network-related operation, such as 'setup networks', 'sync networks', or 'refresh capabilities', is currently being executed on this host.

The header All-Content:true must be added to the request in order for this attribute to be included in the response.

override_iptables

Specifies whether we should override firewall definitions. This applies only when the host is installed or re-installed.

protocol

The protocol that the engine uses to communicate with the host.

Since version 4.1 of the engine the protocol is always set to stomp since xml was removed.

se_linux

The host SElinux status. Security-Enhanced Linux (SELinux) is a component in the Linux kernel that provides a mechanism for supporting access control security policies.

spm

The host storage pool manager (SPM) status and definition. Use it to set the SPM priority of this host, and to see whether this is the current SPM or not.

status_detail

The host status details. Relevant for Gluster hosts.

transparent_huge_pages

Transparent huge page support expands the size of memory pages beyond the standard 4 KiB limit. This reduces memory consumption and increases host performance.

For example, to enable transparent huge page support for host 123, send a request like this:

PUT /ovirt-engine/api/hosts/123

With a request body like this:

<host>
  <transparent_hugepages>
    <enabled>true</enabled>
  </transparent_hugepages>
</host>

version

The version of VDSM.

For example:

GET /ovirt-engine/api/hosts/123

This GET request will return the following output:

<host>
  ...
  <version>
    <build>999</build>
    <full_version>vdsm-4.18.999-419.gitcf06367.el7</full_version>
    <major>4</major>
    <minor>18</minor>
    <revision>0</revision>
  </version>
  ...
</host>

List of all host’s CPUs with detailed information about the topology (socket, core) and with information about the current CPU pinning.

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

You will receive response in XML like this one:

<host_cpu_units>
  <host_cpu_unit>
    <core_id>0</core_id>
    <cpu_id>0</cpu_id>
    <socket_id>0</socket_id>
    <vms>
      <vm href="/ovirt-engine/api/vms/def" id="def" />
    </vms>
  </host_cpu_unit>
  <host_cpu_unit>
    <core_id>0</core_id>
    <cpu_id>1</cpu_id>
    <socket_id>1</socket_id>
    <runs_vdsm>true</runs_vdsm>
  </host_cpu_unit>
  <host_cpu_unit>
    <core_id>0</core_id>
    <cpu_id>2</cpu_id>
    <socket_id>2</socket_id>
  </host_cpu_unit>
</host_cpu_units>

External network providers provisioned on the host.

This attribute is read-only. Setting it will have no effect on the host. The value of this parameter reflects the Default Network Provider of the cluster.

Lists all the Katello errata assigned to the host.

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

You will receive response in XML like this one:

<katello_errata>
  <katello_erratum href="/ovirt-engine/api/katelloerrata/456" id="456">
    <name>RHBA-2013:XYZ</name>
    <description>The description of the erratum</description>
    <title>some bug fix update</title>
    <type>bugfix</type>
    <issued>2013-11-20T02:00:00.000+02:00</issued>
    <solution>Few guidelines regarding the solution</solution>
    <summary>Updated packages that fix one bug are now available for XYZ</summary>
    <packages>
      <package>
        <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
      </package>
      ...
    </packages>
  </katello_erratum>
  ...
</katello_errata>

Each host resource exposes a statistics sub-collection for host-specific statistics.

An example of an XML representation:

<statistics>
  <statistic href="/ovirt-engine/api/hosts/123/statistics/456" id="456">
    <name>memory.total</name>
    <description>Total memory</description>
    <kind>gauge</kind>
    <type>integer</type>
    <unit>bytes</unit>
    <values>
      <value>
        <datum>25165824000</datum>
      </value>
    </values>
    <host href="/ovirt-engine/api/hosts/123" id="123"/>
  </statistic>
    ...
</statistics>
This statistics sub-collection is read-only.

The following list shows the statistic types for hosts:

Name Description

memory.total

Total memory in bytes on the host.

memory.used

Memory in bytes used on the host.

memory.free

Memory in bytes free on the host.

memory.shared

Memory in bytes shared on the host.

memory.buffers

I/O buffers in bytes.

memory.cached

OS caches in bytes.

swap.total

Total swap memory in bytes on the host.

swap.free

Swap memory in bytes free on the host.

swap.used

Swap memory in bytes used on the host.

swap.cached

Swap memory in bytes also cached in host’s memory.

ksm.cpu.current

Percentage of CPU usage for Kernel SamePage Merging.

cpu.current.user

Percentage of CPU usage for user slice.

cpu.current.system

Percentage of CPU usage for system.

cpu.current.idle

Percentage of idle CPU usage.

cpu.load.avg.5m

CPU load average per five minutes.

boot.time

Boot time of the machine.

HostCpuUnit struct

Type representing a physical CPU of a host with the current pinning status.

Table 1081. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

core_id

Integer

The id of the core the CPU belongs to.

cpu_id

Integer

The id of the CPU.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

runs_vdsm

Boolean

A flag indicating that the CPU runs the VDSM

socket_id

Integer

The id of the socket the CPU belongs to.

HostDevice struct

Table 1083. Attributes summary
Name Type Summary

capability

String

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

driver

String

The name of the driver this device is bound to.

id

String

A unique identifier.

iommu_group

Integer

m_dev_types

MDevType[]

List of all supported mdev types on the physical device,

name

String

A human-readable name in plain text.

physical_function

HostDevice

placeholder

Boolean

product

Product

vendor

Vendor

virtual_functions

Integer

driver

The name of the driver this device is bound to.

For example: pcieport or uhci_hcd.

HostDevicePassthrough struct

Table 1085. Attributes summary
Name Type Summary

enabled

Boolean

HostNic struct

Represents a host NIC.

For example, the XML representation of a host NIC looks like this:

<host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456">
  <name>eth0</name>
  <boot_protocol>static</boot_protocol>
  <bridged>true</bridged>
  <custom_configuration>true</custom_configuration>
  <ip>
    <address>192.168.122.39</address>
    <gateway>192.168.122.1</gateway>
    <netmask>255.255.255.0</netmask>
    <version>v4</version>
  </ip>
  <ipv6>
    <gateway>::</gateway>
    <version>v6</version>
  </ipv6>
  <ipv6_boot_protocol>none</ipv6_boot_protocol>
  <mac>
    <address>52:54:00:0c:79:1d</address>
  </mac>
  <mtu>1500</mtu>
  <status>up</status>
</host_nic>

A bonded interface is represented as a HostNic object containing the bonding and slaves attributes.

For example, the XML representation of a bonded host NIC looks like this:

<host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456">
  <name>bond0</name>
  <mac address="00:00:00:00:00:00"/>
  <ip>
    <address>192.168.122.39</address>
    <gateway>192.168.122.1</gateway>
    <netmask>255.255.255.0</netmask>
    <version>v4</version>
  </ip>
  <boot_protocol>dhcp</boot_protocol>
  <bonding>
    <options>
      <option>
        <name>mode</name>
        <value>4</value>
        <type>Dynamic link aggregation (802.3ad)</type>
      </option>
      <option>
        <name>miimon</name>
        <value>100</value>
      </option>
    </options>
    <slaves>
      <host_nic id="123"/>
      <host_nic id="456"/>
    </slaves>
  </bonding>
  <mtu>1500</mtu>
  <bridged>true</bridged>
  <custom_configuration>false</custom_configuration>
</host_nic>
Table 1086. Attributes summary
Name Type Summary

ad_aggregator_id

Integer

The ad_aggregator_id property of a bond or bond slave, for bonds in mode 4.

base_interface

String

The base interface of the NIC.

bonding

Bonding

The bonding parameters of the NIC.

boot_protocol

BootProtocol

The IPv4 boot protocol configuration of the NIC.

bridged

Boolean

Defines the bridged network status.

check_connectivity

Boolean

comment

String

Free text containing comments about this object.

custom_configuration

Boolean

description

String

A human-readable description in plain text.

id

String

A unique identifier.

ip

Ip

The IPv4 address of the NIC.

ipv6

Ip

The IPv6 address of the NIC.

ipv6_boot_protocol

BootProtocol

The IPv6 boot protocol configuration of the NIC.

mac

Mac

The MAC address of the NIC.

mtu

Integer

The maximum transmission unit for the interface.

name

String

A human-readable name in plain text.

override_configuration

Boolean

properties

Property[]

speed

Integer

status

NicStatus

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

Describes the virtual functions configuration of a physical function NIC.

vlan

Vlan

ad_aggregator_id

The ad_aggregator_id property of a bond or bond slave, for bonds in mode 4. Bond mode 4 is the 802.3ad standard, also called dynamic link aggregation. (See Wikipedia and Presentation for more information). This is only valid for bonds in mode 4, or NICs which are part of a bond. It is not present for bonds in other modes, or NICs which are not part of a bond in mode 4. The ad_aggregator_id property indicates which of the bond slaves are active. The value of the ad_aggregator_id of an active slave is the same as the value of the ad_aggregator_id property of the bond. This parameter is read only. Setting it will have no effect on the bond/NIC. It is retrieved from the /sys/class/net/bondX/bonding/ad_aggregator file for a bond, and the /sys/class/net/ensX/bonding_slave/ad_aggregator_id file for a NIC.

bridged

Defines the bridged network status. Set to true for a bridged network and false for a bridgeless network.

A reference to the network to which the interface should be connected. A blank network ID is allowed.

A link to the statistics of the NIC.

The data types for HostNic statistical values:

  • data.current.rx - The rate in bytes per second of data received.

  • data.current.tx - The rate in bytes per second of data transmitted.

  • data.current.rx.bps - The rate in bits per second of data received (since version 4.2).

  • data.current.tx.bps - The rate in bits per second of data transmitted (since version 4.2).

  • data.total.rx - Total received data.

  • data.total.tx - Total transmitted data.

  • errors.total.rx - Total errors from receiving data.

  • errors.total.tx - Total errors from transmitting data.

HostNicVirtualFunctionsConfiguration struct

Describes the virtual functions configuration of an SR-IOV-enabled physical function NIC.

Table 1088. Attributes summary
Name Type Summary

all_networks_allowed

Boolean

Defines whether all networks are allowed to be defined on the related virtual functions, or specified ones only.

max_number_of_virtual_functions

Integer

The maximum number of virtual functions the NIC supports.

number_of_virtual_functions

Integer

The number of virtual functions currently defined.

max_number_of_virtual_functions

The maximum number of virtual functions the NIC supports. This property is read-only.

number_of_virtual_functions

The number of virtual functions currently defined. A user-defined value between 0 and max_number_of_virtual_functions.

HostProtocol enum

The protocol used by the engine to communicate with a host.

Since version 4.1 of the engine the protocol is always set to stomp since xml was removed.
Table 1089. Values summary
Name Summary

stomp

JSON-RPC protocol on top of STOMP.

xml

XML-RPC protocol.

HostStatus enum

Type representing a host status.

Table 1090. Values summary
Name Summary

connecting

The engine cannot communicate with the host for a specific threshold so it is now trying to connect before going through fencing.

down

The host is down.

error

The host is in error status.

initializing

The host is initializing.

install_failed

The host installation failed.

installing

The host is being installed.

installing_os

The host operating system is now installing.

kdumping

The host kernel has crashed and it is now going through memory dumping.

maintenance

The host is in maintenance status.

non_operational

The host is non operational.

non_responsive

The host is not responsive.

pending_approval

The host is pending administrator approval.

preparing_for_maintenance

The host is preparing for maintenance.

reboot

The host is being rebooted.

unassigned

The host is in activation process.

up

The host is up.

error

The host is in error status. This will happen if we will try to run a virtual machine several times and it will fail.

initializing

The host is initializing. This is an intermediate step before moving the host to 'up' status.

install_failed

The host installation failed. In such cases look at the event log to understand what failed the installation, and issue a re-install.

installing_os

The host operating system is now installing. This status is relevant when using a Satellite/Foreman provider, and issuing a bare-metal provisioning (discovered host provisioning).

maintenance

The host is in maintenance status. When a host is in maintenance it cannot run virtual machines.

non_operational

The host is non operational. This can happen due to various reasons, such as not having a connection with the storage, not supporting a mandatory network, not supporting the cluster level, and more.

non_responsive

The host is not responsive. This means that the engine is not able to communicate with the host.

pending_approval

The host is pending administrator approval. This is relevant only for vintage ovirt-node / RHV-H. This property is no longer relevant since Vintage Node is no longer supported, and has been deprecated.

preparing_for_maintenance

The host is preparing for maintenance. During this time the engine makes sure to live migrate all the virtual machines from this host to other hosts. Once all migrations have been completed the host will move to 'maintenance' status.

HostStorage struct

Table 1091. Attributes summary
Name Type Summary

address

String

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

driver_options

Property[]

The options to be passed when creating a storage domain using a cinder driver.

driver_sensitive_options

Property[]

Parameters containing sensitive information, to be passed when creating a storage domain using a cinder driver.

id

String

A unique identifier.

logical_units

LogicalUnit[]

mount_options

String

name

String

A human-readable name in plain text.

nfs_retrans

Integer

The number of times to retry a request before attempting further recovery actions.

nfs_timeo

Integer

The time in tenths of a second to wait for a response before retrying NFS requests.

nfs_version

NfsVersion

override_luns

Boolean

password

String

path

String

port

Integer

portal

String

target

String

type

StorageType

username

String

vfs_type

String

volume_group

VolumeGroup

driver_options

The options to be passed when creating a storage domain using a cinder driver.

For example (Kaminario backend):

POST /ovirt-engine/api/storagedomains/
<storage_domain>
 <name>kamniraio-cinder</name>
 <type>managed_block_storage</type>
 <storage>
   <type>managed_block_storage</type>
   <driver_options>
     <property>
       <name>san_ip</name>
       <value>192.168.1.1</value>
     </property>
     <property>
       <name>san_login</name>
       <value>username</value>
     </property>
     <property>
       <name>san_password</name>
       <value>password</value>
     </property>
     <property>
       <name>use_multipath_for_image_xfer</name>
       <value>true</value>
     </property>
     <property>
       <name>volume_driver</name>
       <value>cinder.volume.drivers.kaminario.kaminario_iscsi.KaminarioISCSIDriver</value>
     </property>
   </driver_options>
 </storage>
 <host>
   <name>host</name>
   </host>
</storage_domain>

driver_sensitive_options

Parameters containing sensitive information, to be passed when creating a storage domain using a cinder driver. These parameters are encrypted when they are saved.

For example, the following XML encrypts and saves a username, password and SAN IP address:

POST /ovirt-engine/api/storagedomains/
<storage_domain>
 <name>kamniraio-cinder</name>
 <type>managed_block_storage</type>
 <storage>
   <type>managed_block_storage</type>
   <driver_options>
     <property>
       <name>san_ip</name>
       <value>192.168.1.1</value>
     </property>
     <property>
       <name>san_login</name>
       <value>username</value>
     </property>
     <property>
       <name>san_password</name>
       <value>password</value>
     </property>
     <property>
       <name>use_multipath_for_image_xfer</name>
       <value>true</value>
     </property>
     <property>
       <name>volume_driver</name>
       <value>cinder.volume.drivers.kaminario.kaminario_iscsi.KaminarioISCSIDriver</value>
     </property>
   </driver_options>
   <driver_sensitive_options>
     <property>
       <name>username</name>
       <value>admin</value>
     </property>
     <property>
       <name>password</name>
       <value>123</value>
     </property>
     <property>
       <name>san_ip</name>
       <value>192.168.1.1</value>
     </property>
   </driver_sensitive_options>
 </storage>
 <host>
   <name>host</name>
 </host>
</storage_domain>

nfs_retrans

The number of times to retry a request before attempting further recovery actions. The value must be in the range of 0 to 65535. For more details see the description of the retrans mount option in the nfs man page.

nfs_timeo

The time in tenths of a second to wait for a response before retrying NFS requests. The value must be in the range of 0 to 65535. For more details see the description of the timeo mount option in the nfs man page.

HostType enum

This enumerated type is used to determine which type of operating system is used by the host.

Table 1093. Values summary
Name Summary

ovirt_node

The host contains Red Hat Virtualization Host (RHVH): a new implementation of Red Hat Enterprise Virtualization Hypervisor (RHEV-H) which uses the same installer as Red Hat Enterprise Linux, CentOS, or Fedora.

rhel

The host contains a full Red Hat Enterprise Linux, CentOS, or Fedora installation.

rhev_h

The host contains Red Hat Enterprise Virtualization Hypervisor (RHEV-H), a small-scaled version of Red Hat Enterprise Linux, CentOS, or Fedora, used solely to host virtual machines.

ovirt_node

The host contains Red Hat Virtualization Host (RHVH): a new implementation of Red Hat Enterprise Virtualization Hypervisor (RHEV-H) which uses the same installer as Red Hat Enterprise Linux, CentOS, or Fedora. The main difference between RHVH and legacy RHEV-H is that RHVH has a writeable file system and will handle its own installation instead of having RPMs pushed to it by the Manager like in legacy RHEV-H.

rhev_h

The host contains Red Hat Enterprise Virtualization Hypervisor (RHEV-H), a small-scaled version of Red Hat Enterprise Linux, CentOS, or Fedora, used solely to host virtual machines.

This property is no longer relevant since Vintage Node is no longer supported, and has been deprecated.

HostedEngine struct

Table 1094. Attributes summary
Name Type Summary

active

Boolean

configured

Boolean

global_maintenance

Boolean

local_maintenance

Boolean

score

Integer

Icon struct

Icon of virtual machine or template.

Table 1095. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

data

String

Base64 encode content of the icon file.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

media_type

String

Format of icon file.

name

String

A human-readable name in plain text.

media_type

Format of icon file.

One of:

  • image/jpeg

  • image/png

  • image/gif

Identified struct

This interface is the base model for all types that represent objects with an identifier.

Table 1096. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Image struct

Represents an image entity.

Table 1097. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

size

Integer

The size of the image file.

type

ImageFileType

The type of the image file.

ImageFileType enum

Represents the file type of an image.

Table 1099. Values summary
Name Summary

disk

The image is a disk format that can be used as a virtual machine’s disk.

floppy

The image is a floppy disk that can be attached to a virtual machine, for example to install the VirtIO drivers in Windows.

iso

The image is a `.

iso

The image is a .iso file that can be used as a CD-ROM to boot and install a virtual machine.

ImageTransfer struct

This type contains information regarding an image transfer being performed.

Table 1100. Attributes summary
Name Type Summary

active

Boolean

Indicates whether there’s at least one active session for this transfer, i,e there’s at least one live transfer session between the client and the daemon.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

direction

ImageTransferDirection

The direction indicates whether the transfer is sending image data (upload) or receiving image data (download).

format

DiskFormat

The format of the data sent during upload or received during download.

id

String

A unique identifier.

inactivity_timeout

Integer

The timeout in seconds of client inactivity, after which the transfer is aborted by the {engine-name}.

name

String

A human-readable name in plain text.

phase

ImageTransferPhase

The current phase of the image transfer in progress.

proxy_url

String

The URL of the proxy server that the user inputs or outputs to.

shallow

Boolean

Download only the specified image instead of the entire image chain.

timeout_policy

ImageTransferTimeoutPolicy

Timeout policy determines how the system handles the transfer when a client is idle for more than inactivityTimeout.

transfer_url

String

The URL of the daemon server that the user can input or output to directly.

transferred

Integer

Indicates the amount of transferred bytes.

direction

The direction indicates whether the transfer is sending image data (upload) or receiving image data (download).

If a direction is not set during an addition of a new transfer, The default direction for the transfer will be upload.

format

The format of the data sent during upload or received during download. If not specified, defaults to disk’s format.

inactivity_timeout

The timeout in seconds of client inactivity, after which the transfer is aborted by the {engine-name}. To disable the inactivity timeout specify '0'. If not specified, the value is defaulted to the engine-config value: TransferImageClientInactivityTimeoutInSeconds.

phase

The current phase of the image transfer in progress. Each transfer needs a managed session, which must be opened for the user to input or output an image. Please refer to image transfer for further documentation.

proxy_url

The URL of the proxy server that the user inputs or outputs to. This attribute is available only if the image transfer is in the transferring phase. See phase for details.

shallow

Download only the specified image instead of the entire image chain.

If true, when using format="raw" and direction="download", the transfer includes data only from the specified disk snapshot, and unallocated areas are reported as holes. By default, the transfer includes data from all disk snapshots.

When specifying a disk snapshot, the transfer includes only data for the specified disk snapshot. When specifying a disk, the transfer includes only data from the active disk snaphost.

This parameter has no effect when not using format="raw" or for direction="upload".

Example: Downloading a single snapshot:

<image_transfer>
  <snapshot id="2fb24fa2-a5db-446b-b733-4654661cd56d"/>
  <direction>download</direction>
  <format>raw</format>
  <shallow>true</shallow>
</image_transfer>

To download the active snapshot disk image (which is not accessible as a disk snapshot), specify the disk:

<image_transfer>
  <disk id="ff6be46d-ef5d-41d6-835c-4a68e8956b00"/>
  <direction>download</direction>
  <format>raw</format>
  <shallow>true</shallow>
</image_transfer>

In both cases you can now download a qcow2 image using imageio client:

from ovirt_imageio import client

client.download(
  transfer.transfer_url,
  "51275e7d-42e9-491f-9d65-b9211c897eac",
  backing_file="07c0ccac-0845-4665-9097-d0a3b16cf43b",
  backing_format="qcow2")

transfer_url

The URL of the daemon server that the user can input or output to directly.

This is as an alternative to the proxy_url. I.e. if the client has access to the host machine, it could bypass the proxy and transfer directly to the host, potentially improving the throughput performance. This attribute is available only if the image transfer is in the transferring phase. See phase for details.

The backup associated with the image transfer. Specify when initiating an image transfer for a disk that is part of a backup.

The host which will be used to write to the image which is targeted for input or output. If not specified, an active host will be randomly selected from the data center.

The image which is targeted for input or output.

This attribute is deprecated since version 4.2 of the engine. Use the disk or snapshot attributes instead.

ImageTransferDirection enum

The image transfer direction for a transfer.

When adding a new transfer, the user can choose whether the transfer will be to an image, choosing upload, or to transfer from an image- choosing download as an ImageTransferDirection.

Please refer to image transfer for further documentation.

Table 1102. Values summary
Name Summary

download

The user must choose download when he/she wants to stream data from an image.

upload

The user can choose upload when he/she wants to stream data to an image.

ImageTransferPhase enum

A list of possible phases for an image transfer entity. Each of these values defines a specific point in a transfer flow.

Please refer to image transfer for more information.

Table 1103. Values summary
Name Summary

cancelled

This phase will be set as a result of the user cancelling the transfer.

cancelled_system

This phase will be set as a result of the system cancelling the transfer.

cancelled_user

This phase will be set as a result of the user cancelling the transfer.

finalizing_cleanup

This phase indicates that the user cancelled the transfer, and necessary cleanup is being done.

finalizing_failure

This phase can only be set in the Administration Portal, and indicates that there was an error during the transfer, and it is being finalized with a failure.

finalizing_success

This phase will be set when the user calls finalize.

finished_cleanup

This phase indicates that the user cancelled the transfer, and necessary cleanup is done.

finished_failure

Indicates that the targeted image failed the verification, and cannot be used.

finished_success

Indicates that the transfer session was successfully closed, and the targeted image was verified and ready to be used.

initializing

The initial phase of an image transfer.

paused_system

This phase means the session timed out, or some other error occurred with this transfer; for example ovirt-imageio is not running in the selected host.

paused_user

This phase is a result of a pause call by the user, using pause.

resuming

The phase where the transfer has been resumed by the client calling resume.

transferring

The phase where the transfer session is open, and the client can input or output the desired image using the preferred tools.

unknown

An unknown phase.

cancelled

This phase will be set as a result of the user cancelling the transfer. The cancellation can only be performed in the Administration Portal.

finalizing_success

This phase will be set when the user calls finalize. Calling finalize is essential to finish the transfer session, and finish using the targeted image. After finalizing, the phase will be changed to finished_success or finished_failure.

Refer to image transfer for more information.

finished_failure

Indicates that the targeted image failed the verification, and cannot be used. After reaching this phase, the image transfer entity will be deleted, and the targeted image will be set to illegal. System cancelling the transfer will also result in this.

finished_success

Indicates that the transfer session was successfully closed, and the targeted image was verified and ready to be used. After reaching this phase, the image transfer entity will be deleted.

initializing

The initial phase of an image transfer. It is set while the transfer session is establishing. Once the session is established, the phase will be changed to transferring

paused_system

This phase means the session timed out, or some other error occurred with this transfer; for example ovirt-imageio is not running in the selected host. To resume the session, the client should call resume. After resuming, the phase will change to resuming.

resuming

The phase where the transfer has been resumed by the client calling resume. Resuming starts a new session, and after calling it, the phase will be changed to transferring, or paused_system in case of a failure.

unknown

An unknown phase. This will only be set in cases of unpredictable errors.

ImageTransferTimeoutPolicy enum

The image transfer timeout policy.

Define how the system handles a transfer when the client is inactive for inactivityTimeout seconds.

Please refer to image transfer for further documentation.

Table 1104. Values summary
Name Summary

cancel

Cancel the transfer and unlock the disk.

legacy

LEGACY policy will preserve the legacy functionality which is the default.

pause

Pause the transfer.

cancel

Cancel the transfer and unlock the disk. For image transfer using upload direction, the disk is deleted.

legacy

LEGACY policy will preserve the legacy functionality which is the default. The default behaviour will cancel the transfer if the direction is download, and pause it if its upload.

pause

Pause the transfer. The transfer can be resumed or canceled by the user. The disk will remain locked while the transfer is paused.

InheritableBoolean enum

Enum representing the boolean value that can be either set, or inherited from a higher level. The inheritance order is virtual machine → cluster → engine-config.

Table 1105. Values summary
Name Summary

false

Set the value to false on this level.

inherit

Inherit the value from higher level.

true

Set the value to true on this level.

Initialization struct

Table 1106. Attributes summary
Name Type Summary

active_directory_ou

String

authorized_ssh_keys

String

cloud_init

CloudInit

Deprecated attribute to specify cloud-init configuration.

cloud_init_network_protocol

CloudInitNetworkProtocol

Attribute specifying the cloud-init protocol to use for formatting the cloud-init network parameters.

configuration

Configuration

custom_script

String

dns_search

String

dns_servers

String

domain

String

host_name

String

input_locale

String

nic_configurations

NicConfiguration[]

org_name

String

regenerate_ids

Boolean

regenerate_ssh_keys

Boolean

root_password

String

system_locale

String

timezone

String

ui_language

String

user_locale

String

user_name

String

windows_license_key

String

cloud_init

Deprecated attribute to specify cloud-init configuration.

This attribute and the CloudInit type have been deprecated and will be removed in the future. To specify the cloud-init configuration, use the attributes inside the Initialization type. The mapping between the attributes of these two types are as follows:

CloudInit Initialization

authorized_keys

authorized_ssh_keys

dns.search_domains

dns_search

dns.servers

dns_servers

files

custom_script

host

host_name

network_configuration.nics

nic_configurations

regenerate_ssh_keys

regenerate_ssh_keys

timezone

timezone

users

user_name & root_password

For more details on how to use cloud-init see the examples in Python and Java.

cloud_init_network_protocol

Attribute specifying the cloud-init protocol to use for formatting the cloud-init network parameters. If omitted, a default value is used, as described in the CloudInitNetworkProtocol

InstanceType struct

Describes the hardware configuration of virtual machines.

For example medium instance type includes 1 virtual CPU and 4 GiB of memory. It is a top-level entity (e.g. not bound to any data center or cluster). The attributes that are used for instance types and are common to virtual machine and template types are:

  • console

  • cpu

  • custom_cpu_model

  • custom_emulated_machine

  • display

  • high_availability

  • io

  • memory

  • memory_policy

  • migration

  • migration_downtime

  • os

  • rng_device

  • soundcard_enabled

  • usb

  • virtio_scsi

When creating a virtual machine from both an instance type and a template, the virtual machine will inherit the hardware configurations from the instance type

An instance type inherits it’s attributes from the template entity although most template attributes are not used in instance types.
Table 1107. Attributes summary
Name Type Summary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

custom_emulated_machine

String

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

status

TemplateStatus

The status of the template.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

version

TemplateVersion

Indicates whether this is the base version or a sub-version of another template.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

vm

Vm

The virtual machine configuration associated with this template.

auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

initialization

Reference to the virtual machine’s initialization configuration.

Since {product-name} 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from {product-name} 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since {product-name} 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.
{engine-name} internally rounds values down to whole MiBs (1MiB = 220 bytes)

migration

Reference to configuration of migration of a running virtual machine to another host.

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

origin

The origin of this virtual machine.

Possible values:

  • ovirt

  • rhev

  • vmware

  • xen

  • external

  • hosted_engine

  • managed_hosted_engine

  • kvm

  • physical_machine

  • hyperv

placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

Io struct

Table 1109. Attributes summary
Name Type Summary

threads

Integer

Ip struct

Represents the IP configuration of a network interface.

Table 1110. Attributes summary
Name Type Summary

address

String

The text representation of the IP address.

gateway

String

The address of the default gateway.

netmask

String

The network mask.

version

IpVersion

The version of the IP protocol.

address

The text representation of the IP address.

For example, an IPv4 address will be represented as follows:

<ip>
  <address>192.168.0.1</address>
  ...
</ip>

An IPv6 address will be represented as follows:

<ip>
  <address>2620:52:0:20f0:4216:7eff:feaa:1b50</address>
  ...
</ip>

netmask

The network mask.

For IPv6 addresses the value is an integer in the range of 0-128, which represents the subnet prefix.

version

The version of the IP protocol.

From version 4.1 of the Manager this attribute will be optional, and when a value is not provided, it will be inferred from the value of the address attribute.

IpAddressAssignment struct

Represents an IP address assignment for a network device.

For a static boot protocol assignment, subnet mask and IP address (and optinally default gateway) must be provided in the IP configuration.

Table 1111. Attributes summary
Name Type Summary

assignment_method

BootProtocol

Sets the boot protocol used to assign the IP configuration for a network device.

ip

Ip

Sets the IP configuration for a network device.

IpVersion enum

Defines the values for the IP protocol version.

Table 1112. Values summary
Name Summary

v4

IPv4.

v6

IPv6.

IscsiBond struct

Table 1113. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

IscsiDetails struct

Table 1115. Attributes summary
Name Type Summary

address

String

disk_id

String

initiator

String

lun_mapping

Integer

password

String

paths

Integer

port

Integer

portal

String

product_id

String

serial

String

size

Integer

status

String

storage_domain_id

String

target

String

username

String

vendor_id

String

volume_group_id

String

Job struct

Represents a job, which monitors execution of a flow in the system. A job can contain multiple steps in a hierarchic structure. The steps can be processed in parallel, depends on the implementation of the flow.

Table 1116. Attributes summary
Name Type Summary

auto_cleared

Boolean

Indicates if the job should be cleared automatically after it was completed by the system.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

end_time

Date

The end time of the job.

external

Boolean

Indicates if the job is originated by an external system.

id

String

A unique identifier.

last_updated

Date

The last update date of the job.

name

String

A human-readable name in plain text.

start_time

Date

The start time of the job.

status

JobStatus

The status of the job.

external

Indicates if the job is originated by an external system. External jobs are managed externally, by the creator of the job.

JobStatus enum

Represents the status of the job.

Table 1118. Values summary
Name Summary

aborted

The aborted job status.

failed

The failed job status.

finished

The finished job status.

started

The started job status.

unknown

The unknown job status.

aborted

The aborted job status. This status is applicable for an external job that was forcibly aborted.

finished

The finished job status. This status describes a completed job execution.

started

The started job status. This status represents a job which is currently being executed.

unknown

The unknown job status. This status represents jobs which their resolution is not known, i.e. jobs that were executed before the system was unexpectedly restarted.

KatelloErratum struct

Type representing a Katello erratum.

Table 1119. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

issued

Date

The date when the Katello erratum was issued.

name

String

A human-readable name in plain text.

packages

Package[]

The list of packages which solve the issue reported by the Katello erratum.

severity

String

The severity of the Katello erratum.

solution

String

The solution for the issue described by the Katello erratum.

summary

String

The summary of the Katello erratum.

title

String

The title of the Katello erratum.

type

String

The type of the Katello erratum.

severity

The severity of the Katello erratum.

The supported severities are moderate, important or critical.

type

The type of the Katello erratum.

The supported types are bugfix, enhancement or security.

KdumpStatus enum

Table 1121. Values summary
Name Summary

disabled

enabled

unknown

Kernel struct

Table 1122. Attributes summary
Name Type Summary

version

Version

Ksm struct

Table 1123. Attributes summary
Name Type Summary

enabled

Boolean

merge_across_nodes

Boolean

Represents an information element received by Link Layer Discovery Protocol (LLDP). IEEE 802.1AB defines type, length, value (TLV) as a "short, variable length encoding of an information element". This type represents such an information element.

The attribute name is a human-readable string used to describe what the value is about, and may not be unique. The name is redundant, because it could be created from type and the optional oui and subtype. The purpose of name is to simplify the reading of the information element. The name of a property is exactly the same string which is used in IEEE 802.1AB chapter 8.

Organizationally-specific information elements have the type of 127 and the attributes oui and subtype.

For example, the XML representation of an information element may look like this:

<link_layer_discovery_protocol_element>
  <name>Port VLAN Id</name>
  <oui>32962</oui>
  <properties>
    <property>
      <name>vlan id</name>
      <value>488</value>
    </property>
    <property>
      <name>vlan name</name>
      <value>v2-0488-03-0505</value>
    </property>
  </properties>
  <subtype>3</subtype>
  <type>127</type>
</link_layer_discovery_protocol_element>
Table 1124. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

oui

Integer

The organizationally-unique identifier (OUI) encoded as an integer.

properties

Property[]

Represents structured data transported by the information element as a list of name/value pairs.

subtype

Integer

The organizationally-defined subtype encoded as an integer.

type

Integer

The type of the LinkLayerDiscoveryProtocolElement encoded as an integer.

The organizationally-unique identifier (OUI) encoded as an integer. Only available if type is 127.

The organizationally-defined subtype encoded as an integer. Only available if type is 127.

LogMaxMemoryUsedThresholdType enum

Describes all maximum memory threshold types supported by the system.

Table 1125. Values summary
Name Summary

absolute_value_in_mb

Absolute value threshold type.

percentage

Percentage threshold type.

absolute_value_in_mb

Absolute value threshold type.

When an absolute value is specified, an audit log event is logged if the free memory in MB falls below the value specified in LogMaxMemoryUsedThreshold.

percentage

Percentage threshold type.

When a percentage is specified, an audit log event is logged if the memory used is above the value specified in LogMaxMemoryUsedThreshold.

LogSeverity enum

Enum representing a severity of an event.

Table 1126. Values summary
Name Summary

alert

Alert severity.

error

Error severity.

normal

Normal severity.

warning

Warning severity.

alert

Alert severity. Used to specify a condition that requires an immediate attention.

error

Error severity. Used to specify that there is an error that needs to be examined.

normal

Normal severity. Used for information events.

warning

Warning severity. Used to warn something might be wrong.

LogicalUnit struct

Table 1127. Attributes summary
Name Type Summary

address

String

discard_max_size

Integer

The maximum number of bytes that can be discarded by the logical unit’s underlying storage in a single operation.

discard_zeroes_data

Boolean

True, if previously discarded blocks in the logical unit’s underlying storage are read back as zeros.

disk_id

String

id

String

lun_mapping

Integer

password

String

paths

Integer

port

Integer

portal

String

product_id

String

serial

String

size

Integer

status

LunStatus

storage_domain_id

String

target

String

username

String

vendor_id

String

volume_group_id

String

discard_max_size

The maximum number of bytes that can be discarded by the logical unit’s underlying storage in a single operation. A value of 0 means that the device does not support discard functionality.

This is the software limit, and not the hardware limit, as noted in the queue-sysfs documentation for discard_max_bytes.

discard_zeroes_data

True, if previously discarded blocks in the logical unit’s underlying storage are read back as zeros. For more information please see the queue-sysfs documentation for discard_zeroes_data.

Since version 4.2.1 of the system, the support for this attribute has been removed as the sysfs file, discard_zeroes_data, was deprecated in the kernel. It is preserved for backwards compatibility, but the value will always be false.

LunStatus enum

Table 1128. Values summary
Name Summary

free

unusable

used

MDevType struct

Mediated device is a software device that allows to divide physical device’s resources.

See Libvirt-MDEV for further details.

Table 1129. Attributes summary
Name Type Summary

available_instances

Integer

MDev type available instances count.

description

String

MDev type description.

human_readable_name

String

MDev type human readable name.

name

String

MDev type name.

Mac struct

Represents a MAC address of a virtual network interface.

Table 1130. Attributes summary
Name Type Summary

address

String

MAC address.

MacPool struct

Represents a MAC address pool.

Example of an XML representation of a MAC address pool:

<mac_pool href="/ovirt-engine/api/macpools/123" id="123">
  <name>Default</name>
  <description>Default MAC pool</description>
  <allow_duplicates>false</allow_duplicates>
  <default_pool>true</default_pool>
  <ranges>
    <range>
      <from>00:1A:4A:16:01:51</from>
      <to>00:1A:4A:16:01:E6</to>
    </range>
  </ranges>
</mac_pool>
Table 1131. Attributes summary
Name Type Summary

allow_duplicates

Boolean

Defines whether duplicate MAC addresses are permitted in the pool.

comment

String

Free text containing comments about this object.

default_pool

Boolean

Defines whether this is the default pool.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

ranges

Range[]

Defines the range of MAC addresses for the pool.

allow_duplicates

Defines whether duplicate MAC addresses are permitted in the pool. If not specified, defaults to false.

default_pool

Defines whether this is the default pool. If not specified, defaults to false.

ranges

Defines the range of MAC addresses for the pool. Multiple ranges can be defined.

MemoryOverCommit struct

Table 1133. Attributes summary
Name Type Summary

percent

Integer

MemoryPolicy struct

Logical grouping of memory-related properties of virtual machine-like entities.

Table 1134. Attributes summary
Name Type Summary

ballooning

Boolean

guaranteed

Integer

The amount of memory, in bytes, that is guaranteed to not be drained by the balloon mechanism.

max

Integer

Maximum virtual machine memory, in bytes.

over_commit

MemoryOverCommit

transparent_huge_pages

TransparentHugePages

guaranteed

The amount of memory, in bytes, that is guaranteed to not be drained by the balloon mechanism.

The {engine-name} internally rounds this value down to whole MiB (1MiB = 220 bytes).

It can be updated while the virtual machine is running since {product-name} 4.2 onwards, provided memory is updated in the same request as well, and the virtual machine is in state up.

max

Maximum virtual machine memory, in bytes.

The user provides the value in bytes, and the {engine-name} rounds the value down to the nearest lower MiB value.

For example, if the user enters a value of 1073741825 (1 GiB + 1 byte), then the {engine-name} will truncate that value to the nearest lower MiB boundary: in this case 1073741824 (1 GiB).

MessageBrokerType enum

Deprecated Message Broker type.

Ignored, because the deployment of OpenStack Neutron agent is dropped since {product-name} 4.4.0.

Table 1135. Values summary
Name Summary

qpid

rabbit_mq

Method struct

Table 1136. Attributes summary
Name Type Summary

id

SsoMethod

MigrateOnError enum

Table 1137. Values summary
Name Summary

do_not_migrate

migrate

migrate_highly_available

MigrationBandwidth struct

Defines the bandwidth used by migration.

Table 1138. Attributes summary
Name Type Summary

assignment_method

MigrationBandwidthAssignmentMethod

The method used to assign the bandwidth.

custom_value

Integer

Custom bandwidth in Mbps.

custom_value

Custom bandwidth in Mbps. Will be applied only if the assignmentMethod attribute is custom.

MigrationBandwidthAssignmentMethod enum

Defines how the migration bandwidth is assigned.

Table 1139. Values summary
Name Summary

auto

Takes the bandwidth from the Quality of Service if the Quality of Service is defined.

custom

Custom defined bandwidth in Mbit/s.

hypervisor_default

Takes the value as configured on the hypervisor.

auto

Takes the bandwidth from the Quality of Service if the Quality of Service is defined. If the Quality of Service is not defined the bandwidth is taken from the detected link speed being used. If nothing is detected, bandwidth falls back to the hypervisor_default value.

MigrationOptions struct

The type for migration options.

Table 1140. Attributes summary
Name Type Summary

auto_converge

InheritableBoolean

bandwidth

MigrationBandwidth

The bandwidth that is allowed to be used by the migration.

compressed

InheritableBoolean

custom_parallel_migrations

Integer

Specifies how many parallel migration connections to use.

encrypted

InheritableBoolean

Specifies whether the migration should be encrypted or not.

parallel_migrations_policy

ParallelMigrationsPolicy

Specifies whether and how to use parallel migration connections.

custom_parallel_migrations

Specifies how many parallel migration connections to use. May be specified only when ParallelMigrationsPolicy is CUSTOM. The valid range of values is 2-255. The recommended range of values is 2-16.

MigrationPolicy struct

A policy describing how the migration is treated, such as convergence or how many parallel migrations are allowed.

Table 1142. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Network struct

The type for a logical network.

An example of the JSON representation of a logical network:

{
  "network" : [ {
    "data_center" : {
      "href" : "/ovirt-engine/api/datacenters/123",
      "id" : "123"
    },
    "stp" : "false",
    "mtu" : "0",
    "usages" : {
      "usage" : [ "vm" ]
    },
    "name" : "ovirtmgmt",
    "description" : "Management Network",
    "href" : "/ovirt-engine/api/networks/456",
    "id" : "456",
    "link" : [ {
      "href" : "/ovirt-engine/api/networks/456/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/networks/456/vnicprofiles",
      "rel" : "vnicprofiles"
    }, {
      "href" : "/ovirt-engine/api/networks/456/labels",
      "rel" : "labels"
    } ]
  } ]
}

An example of the XML representation of the same logical network:

<network href="/ovirt-engine/api/networks/456" id="456">
  <name>ovirtmgmt</name>
  <description>Management Network</description>
  <link href="/ovirt-engine/api/networks/456/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/networks/456/vnicprofiles" rel="vnicprofiles"/>
  <link href="/ovirt-engine/api/networks/456/labels" rel="labels"/>
  <data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
  <stp>false</stp>
  <mtu>0</mtu>
  <usages>
    <usage>vm</usage>
  </usages>
</network>
Table 1143. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

display

Boolean

Deprecated, 'usages' should be used to define network as a display network.

dns_resolver_configuration

DnsResolverConfiguration

The DNS resolver configuration will be reported when retrieving the network using GET.

id

String

A unique identifier.

ip

Ip

Deprecated, not in use.

mtu

Integer

Specifies the maximum transmission unit for the network.

name

String

A human-readable name in plain text.

port_isolation

Boolean

Defines whether communication between VMs running on the same host is blocked on this network.

profile_required

Boolean

Specifies whether upon creation of the network a virtual network interface profile should automatically be created.

required

Boolean

Defines whether the network is mandatory for all the hosts in the cluster.

status

NetworkStatus

The status of the network.

stp

Boolean

Specifies whether the spanning tree protocol is enabled for the network.

usages

NetworkUsage[]

Defines a set of usage elements for the network.

vdsm_name

String

The name of the network used on the host.

vlan

Vlan

A VLAN tag.

dns_resolver_configuration

The DNS resolver configuration will be reported when retrieving the network using GET. It is optional both when creating a new network or updating existing one.

port_isolation

Defines whether communication between VMs running on the same host is blocked on this network. Applies only to VM networks. It is on the network administrator to ensure that the communication between multiple hosts is blocked. This attribute can be set only on network creation and cannot be edited. When the value is not set, communication between VMs running on the same host is allowed.

required

Defines whether the network is mandatory for all the hosts in the cluster. In case a 'required' operational network is omitted from a host, the host will be marked as non_operational,

status

The status of the network. non_operational if the network defined as 'required' and omitted from any active cluster host. operational otherwise.

usages

Defines a set of usage elements for the network.

For example, users can specify that the network is to be used for virtual machine traffic and also for display traffic with the vm and display values.

vdsm_name

The name of the network used on the host. This alternative name is automatically generated by VDSM when the network name is found unsuitable to serve as a bridge name on the host. Unsuitable names contain spaces, special characters or are longer than 15 characters and are replaced with a UUID on the host. This parameter is read-only. Setting it will have no effect.

A reference to the cluster this network is attached to. Will be filled only if the network is accessed from the cluster level.

An optional reference to the OpenStack network provider on which the network is created.

If it is specified when a network is created, a matching OpenStack network will be also created.

An optional reference to a network that should be used for physical network access. Valid only if external_provider is specified.

NetworkAttachment struct

Describes how a host connects to a network.

An XML representation of a network attachment on a host:

<network_attachment href="/ovirt-engine/api/hosts/123/nics/456/networkattachments/789" id="789">
  <network href="/ovirt-engine/api/networks/234" id="234"/>
  <host_nic href="/ovirt-engine/api/hosts/123/nics/123" id="123"/>
  <in_sync>true</in_sync>
  <ip_address_assignments>
    <ip_address_assignment>
      <assignment_method>static</assignment_method>
      <ip>
        <address>192.168.122.39</address>
        <gateway>192.168.122.1</gateway>
        <netmask>255.255.255.0</netmask>
        <version>v4</version>
      </ip>
    </ip_address_assignment>
  </ip_address_assignments>
  <reported_configurations>
    <reported_configuration>
      <name>mtu</name>
      <expected_value>1500</expected_value>
      <actual_value>1500</actual_value>
      <in_sync>true</in_sync>
    </reported_configuration>
    <reported_configuration>
      <name>bridged</name>
      <expected_value>true</expected_value>
      <actual_value>true</actual_value>
      <in_sync>true</in_sync>
    </reported_configuration>
    ...
  </reported_configurations>
</network_attachment>

The network element, with either a name or an id, is required in order to attach a network to a network interface card (NIC).

For example, to attach a network to a host network interface card, send a request like this:

POST /ovirt-engine/api/hosts/123/nics/456/networkattachments

With a request body like this:

<networkattachment>
  <network id="234"/>
</networkattachment>

To attach a network to a host, send a request like this:

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

With a request body like this:

<network_attachment>
  <network id="234"/>
  <host_nic id="456"/>
</network_attachment>

The ip_address_assignments and properties elements are updatable post-creation.

For example, to update a network attachment, send a request like this:

PUT /ovirt-engine/api/hosts/123/nics/456/networkattachments/789

With a request body like this:

<network_attachment>
  <ip_address_assignments>
    <ip_address_assignment>
      <assignment_method>static</assignment_method>
      <ip>
        <address>7.1.1.1</address>
        <gateway>7.1.1.2</gateway>
        <netmask>255.255.255.0</netmask>
        <version>v4</version>
      </ip>
    </ip_address_assignment>
  </ip_address_assignments>
</network_attachment>

To detach a network from the network interface card send a request like this:

DELETE /ovirt-engine/api/hosts/123/nics/456/networkattachments/789
Changes to network attachment configuration must be explicitly committed.

An XML representation of a network attachment’s properties sub-collection:

<network_attachment>
  <properties>
    <property>
      <name>bridge_opts</name>
      <value>
        forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
      </value>
    </property>
  </properties>
  ...
</network_attachment>
Table 1145. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

dns_resolver_configuration

DnsResolverConfiguration

DNS resolver configuration will be reported when retrieving the network attachment using GET.

id

String

A unique identifier.

in_sync

Boolean

ip_address_assignments

IpAddressAssignment[]

The IP configuration of the network.

name

String

A human-readable name in plain text.

properties

Property[]

Defines custom properties for the network configuration.

reported_configurations

ReportedConfiguration[]

A read-only list of configuration properties.

dns_resolver_configuration

DNS resolver configuration will be reported when retrieving the network attachment using GET. It is optional when creating a new network attachment or updating an existing one.

properties

Defines custom properties for the network configuration.

Bridge options have the set name of bridge_opts. Separate multiple entries with a whitespace character. The following keys are valid for bridge_opts:

Name Default value

forward_delay

1500

gc_timer

3765

group_addr

1:80:c2:0:0:0

group_fwd_mask

0x0

hash_elasticity

4

hash_max

512

hello_time

200

hello_timer

70

max_age

2000

multicast_last_member_count

2

multicast_last_member_interval

100

multicast_membership_interval

26000

multicast_querier

0

multicast_querier_interval

25500

multicast_query_interval

13000

multicast_query_response_interval

1000

multicast_query_use_ifaddr

0

multicast_router

1

multicast_snooping

1

multicast_startup_query_count

2

multicast_startup_query_interval

3125

NetworkConfiguration struct

Table 1147. Attributes summary
Name Type Summary

dns

Dns

nics

Nic[]

NetworkFilter struct

Network filters filter packets sent to and from the virtual machine’s NIC according to defined rules.

There are several types of network filters supported based on libvirt. For more details about the different network filters see here.

The default Network Filter is based on network type and configuration. VM network’s default filter is vdsm-no-mac-spoof if EnableMACAntiSpoofingFilterRules is True, otherwise the filter is not configured, for OVN networks the filter is not configured.

In addition to libvirt’s network filters, there are two additional network filters: The first is called vdsm-no-mac-spoofing and is composed of no-mac-spoofing and no-arp-mac-spoofing. The second is called ovirt-no-filter and is used when no network filter is to be defined for the virtual machine’s NIC. The ovirt-no-filter network filter is only used for internal implementation, and does not exist on the NICs.

This is a example of the XML representation:

<network_filter id="00000019-0019-0019-0019-00000000026c">
  <name>example-filter</name>
  <version>
    <major>4</major>
    <minor>0</minor>
    <build>-1</build>
    <revision>-1</revision>
  </version>
</network_filter>

If any part of the version is not present, it is represented by -1.

Table 1148. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

version

Version

The minimum supported version of a specific NetworkFilter.

version

The minimum supported version of a specific NetworkFilter. This is the version that the NetworkFilter was first introduced in.

NetworkFilterParameter struct

Parameter for the network filter.

See Libvirt-Filters for further details. This is a example of the XML representation:

<network_filter_parameter id="123">
  <name>IP</name>
  <value>10.0.1.2</value>
</network_filter_parameter>
Table 1149. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

value

String

Represents the value of the parameter.

NetworkLabel struct

Represents a label which can be added to a host network interface and to a network. The label binds the network to the host network interface by the label id.

Table 1151. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

NetworkPluginType enum

Network plug-in type.

Specifies the provider driver implementation on the host.

Since version 4.2 of the {engine-name}, this type has been deprecated in favour of the external_plugin_type attribute of the OpenStackNetworkProvider type.

Table 1153. Values summary
Name Summary

open_vswitch

Open vSwitch.

open_vswitch

Open vSwitch.

Specifies that Open vSwitch based driver implementation should be used for this provider.

Since version 4.2 of the {engine-name}, this value has been deprecated. Use the string open_vswitch in the OpenStackNetworkProvider.external_plugin_type attribute instead.

NetworkStatus enum

Table 1154. Values summary
Name Summary

non_operational

operational

NetworkUsage enum

This type indicates the purpose that the network is used for in the cluster.

Table 1155. Values summary
Name Summary

default_route

The default gateway and the DNS resolver configuration of the host will be taken from this network.

display

The network will be used for SPICE and VNC traffic.

gluster

The network will be used for Gluster (bricks) data traffic.

management

The network will be used for communication between the {engine-name} and the nodes.

migration

The network will be used for virtual machine migration.

vm

default_route

The default gateway and the DNS resolver configuration of the host will be taken from this network.

If this network is attached to the host, then the DNS resolver configuration will be taken from the dns_resolver_configuration attribute of the network attachment. If there is no dns_resolver_configuration attribute in this network attachment, then they will be taken from the dns_resolver_configuration of the network itself. If dns_resolver_configuration attribute isn’t present even there, DNS resolver configuration won’t be set.

If you set this flag on a network, then the the default gateway for the host will be taken from the gateway attribute of the ip_address_assignment of the network attachment.

management

The network will be used for communication between the {engine-name} and the nodes. This is the network where the ovirtmgmt bridge will be created.

NfsProfileDetail struct

Table 1156. Attributes summary
Name Type Summary

nfs_server_ip

String

profile_details

ProfileDetail[]

NfsVersion enum

Table 1157. Values summary
Name Summary

auto

v3

v4

v4_0

NFS 4.

v4_1

v4_2

NFS 4.

v4_0

NFS 4.0.

v4_2

NFS 4.2.

Nic struct

Represents a virtual machine NIC.

For example, the XML representation of a NIC will look like this:

<nic href="/ovirt-engine/api/vms/123/nics/456" id="456">
  <name>nic1</name>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
  <interface>virtio</interface>
  <linked>true</linked>
  <mac>
    <address>02:00:00:00:00:00</address>
  </mac>
  <plugged>true</plugged>
  <vnic_profile href="/ovirt-engine/api/vnicprofiles/789" id="789"/>
</nic>
Table 1158. Attributes summary
Name Type Summary

boot_protocol

BootProtocol

Defines how an IP address is assigned to the NIC.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

interface

NicInterface

The type of driver used for the NIC.

linked

Boolean

Defines if the NIC is linked to the virtual machine.

mac

Mac

The MAC address of the interface.

name

String

A human-readable name in plain text.

on_boot

Boolean

Defines if the network interface should be activated upon operation system startup.

plugged

Boolean

Defines if the NIC is plugged in to the virtual machine.

synced

Boolean

Defines if the NIC configuration on the virtual machine is synced with the configuration represented by engine.

A reference to the network that the interface should be connected to. A blank network ID is allowed.

Usage of this element for creating or updating a NIC is deprecated; use vnic_profile instead. It is preserved because it is still in use by the initialization element, as a holder for IP addresses and other network details.

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

NicConfiguration struct

The type describes the configuration of a virtual network interface.

Table 1160. Attributes summary
Name Type Summary

boot_protocol

BootProtocol

IPv4 boot protocol.

ip

Ip

IPv4 address details.

ipv6

Ip

IPv6 address details.

ipv6_boot_protocol

BootProtocol

IPv6 boot protocol.

name

String

Network interface name.

on_boot

Boolean

Specifies whether the network interface should be activated on the virtual machine guest operating system boot.

NicInterface enum

Defines the options for an emulated virtual network interface device model.

Table 1161. Values summary
Name Summary

e1000

e1000.

e1000e

e1000e.

pci_passthrough

PCI Passthrough.

rtl8139

rtl8139.

rtl8139_virtio

Dual mode rtl8139, VirtIO.

spapr_vlan

sPAPR VLAN.

virtio

VirtIO.

NicStatus enum

Network interface card status.

Table 1162. Values summary
Name Summary

down

The NIC is down and cannot be accessed.

up

The NIC is up and can be accessed.

NotifiableEvent enum

Type representing a subset of events in the {product-name} server: those which a user may subscribe to receive a notification about.

Table 1163. Values summary
Name Summary

cluster_alert_ha_reservation

HA Reservation check has failed

cluster_alert_ha_reservation_down

HA Reservation check has passed

dwh_error

ETL Service Error

dwh_stopped

ETL Service Stopped

engine_backup_completed

Engine backup completed successfully

engine_backup_failed

Engine backup failed

engine_backup_started

Engine backup started

engine_ca_certification_has_expired

Engine CA’s certification has expired

engine_ca_certification_is_about_to_expire

Engine CA’s certification is about to expire

engine_certification_has_expired

Engine’s certification has expired

engine_certification_is_about_to_expire

Engine’s certification is about to expire

engine_stop

Engine has stopped

faulty_multipaths_on_host

Faulty multipath paths on host

gluster_brick_status_changed

Detected change in status of brick

gluster_hook_add_failed

Failed to add Gluster Hook on conflicting servers

gluster_hook_added

Added Gluster Hook

gluster_hook_conflict_detected

Detected conflict in Gluster Hook

gluster_hook_detected_delete

Detected removal of Gluster Hook

gluster_hook_detected_new

Detected new Gluster Hook

gluster_hook_disable

Gluster Hook Disabled

gluster_hook_disable_failed

Failed to Disable Gluster Hook

gluster_hook_enable

Gluster Hook Enabled

gluster_hook_enable_failed

Failed to Enable Gluster Hook

gluster_hook_remove_failed

Failed to remove Gluster Hook from cluster

gluster_hook_removed

Removed Gluster Hook

gluster_server_add_failed

Failed to Add Gluster Server

gluster_server_remove

Gluster Server Removed

gluster_server_remove_failed

Failed to Remove Gluster Server

gluster_service_restart_failed

Failed to re-start Gluster Service

gluster_service_restarted

Gluster Service re-started

gluster_service_start_failed

Failed to start Gluster service

gluster_service_started

Gluster Service started

gluster_service_stop_failed

Failed to stop Gluster service

gluster_service_stopped

Gluster Service stopped

gluster_volume_add_brick

Gluster Volume brick(s) added

gluster_volume_add_brick_failed

Failed to add brick(s) on Gluster Volume

gluster_volume_all_snapshots_delete_failed

Failed to delete snapshots on the volume

gluster_volume_all_snapshots_deleted

All the snapshots deleted on the volume

gluster_volume_brick_replaced

Gluster Volume Brick Replaced

gluster_volume_confirmed_space_low

Low space for volume confirmed

gluster_volume_create

Gluster Volume Created

gluster_volume_create_failed

Gluster Volume could not be created

gluster_volume_delete

Gluster Volume deleted

gluster_volume_delete_failed

Gluster Volume could not be deleted

gluster_volume_migrate_brick_data_finished

Gluster Volume migration of data for remove brick finished

gluster_volume_option_added

Gluster Volume Option added

gluster_volume_option_modified

Gluster Volume Option modified

gluster_volume_option_set_failed

Gluster Volume Option could not be set

gluster_volume_options_reset

Gluster Volume Options reset

gluster_volume_options_reset_all

All the Gluster Volume Options reset

gluster_volume_options_reset_failed

Gluster Volume Options could not be reset

gluster_volume_profile_start

Gluster Volume Profile started

gluster_volume_profile_start_failed

Failed to start Gluster Volume Profile

gluster_volume_profile_stop

Gluster Volume Profile stopped

gluster_volume_profile_stop_failed

Failed to stop Gluster Volume Profile

gluster_volume_rebalance_finished

Gluster Volume rebalance finished

gluster_volume_rebalance_not_found_from_cli

Could not find information for rebalance on volume from CLI.

gluster_volume_rebalance_start

Gluster Volume Rebalance started

gluster_volume_rebalance_start_detected_from_cli

Detected start of rebalance on gluster volume from CLI

gluster_volume_rebalance_start_failed

Gluster Volume Rebalance could not be started

gluster_volume_rebalance_stop

Gluster Volume Rebalance stopped

gluster_volume_rebalance_stop_failed

Gluster Volume Rebalance could not be stopped

gluster_volume_remove_bricks

Gluster Volume Bricks Removed

gluster_volume_remove_bricks_failed

Gluster Volume Bricks could not be removed

gluster_volume_remove_bricks_stop

Stopped removing bricks from Gluster Volume

gluster_volume_remove_bricks_stop_failed

Failed to stop remove bricks from Gluster Volume

gluster_volume_replace_brick_failed

Gluster Volume Replace Brick Failed

gluster_volume_replace_brick_start

Gluster Volume Replace Brick Started

gluster_volume_replace_brick_start_failed

Gluster Volume Replace Brick could not be started

gluster_volume_snapshot_activate_failed

Failed to activate snapshot on the volume

gluster_volume_snapshot_activated

Snapshot activated on the volume

gluster_volume_snapshot_create_failed

Could not create snapshot for volume ${glusterVolumeName} on cluster ${clusterName}.

gluster_volume_snapshot_created

Snapshot ${snapname} created for volume ${glusterVolumeName} on cluster ${clusterName}.

gluster_volume_snapshot_deactivate_failed

Failed to de-activate snapshot on the volume

gluster_volume_snapshot_deactivated

Snapshot de-activated on the volume

gluster_volume_snapshot_delete_failed

Failed to delete snapshot on volume

gluster_volume_snapshot_deleted

Snapshot deleted on volume

gluster_volume_snapshot_restore_failed

Failed to restore snapshot on the volume

gluster_volume_snapshot_restored

Snapshot restore on the volume

gluster_volume_start

Gluster volume started

gluster_volume_start_failed

Gluster Volume could not be started

gluster_volume_stop

Gluster volume stopped

gluster_volume_stop_failed

Gluster Volume could not be stopped

ha_vm_failed

Highly-Available VM failed

ha_vm_restart_failed

Highly-Available VM restart failed

host_activate_failed

Failed to activate Host

host_activate_manual_ha

Host was activated, but the Hosted Engine HA service may still be in maintenance mode

host_approve_failed

Failed to approve Host

host_bond_slave_state_down

Host’s slave of bond changed state to down

host_certificate_has_invalid_san

Host’s certificate contains invalid subject alternative name (SAN)

host_certification_has_expired

Host’s certification has expired

host_certification_is_about_to_expire

Host’s certification is about to expire

host_failure

Host is non responsive

host_high_cpu_use

Host cpu usage exceeded defined threshold

host_high_mem_use

Host memory usage exceeded defined threshold

host_high_swap_use

Host swap memory usage exceeded defined threshold

host_initiated_run_vm_failed

Failed to restart VM on a different host

host_install_failed

Host installation failed

host_interface_high_network_use

Host network interface usage exceeded defined threshold

host_interface_state_down

Host’s interface changed state to down

host_low_mem

Host free memory is under defined threshold

host_low_swap

Host free swap memory is under defined threshold

host_recover_failed

Host failed to recover

host_set_nonoperational

Host state was set to non-operational

host_set_nonoperational_domain

Host state was set to non-operational due to inaccessible Storage Domain

host_set_nonoperational_iface_down

Host state was set to non-operational due to a missing Interface

host_slow_storage_response_time

Slow storage response time

host_time_drift_alert

Host has time-drift

host_untrusted

Host state was set to non-operational.

host_updates_are_available

Host has available updates

host_updates_are_available_with_packages

Host has available packages to update

importexport_import_template_from_trusted_to_untrusted

Template imported from trusted cluster into non-trusted cluster

importexport_import_template_from_untrusted_to_trusted

Template imported from non-trusted cluster into trusted cluster

importexport_import_vm_from_trusted_to_untrusted

Import VM from trusted cluster into non-trusted cluster

importexport_import_vm_from_untrusted_to_trusted

Import VM from non-trusted cluster into trusted cluster

irs_confirmed_disk_space_low

Confirmed low disk space

irs_disk_space_low

Low disk space

irs_disk_space_low_error

Critically low disk space

irs_failure

Failed to access Storage

mac_address_is_external

VM with external MAC address

multipath_devices_without_valid_paths_on_host

Multipath devices without valid paths on host

network_update_display_for_cluster_with_active_vm

Display network was updated on cluster with an active VM

network_update_display_for_host_with_active_vm

Display network was updated on host with an active VM

no_faulty_multipaths_on_host

No faulty multipath paths on host

number_of_lvs_on_storage_domain_exceeded_threshold

Storage Domain’s number of LVs exceeded threshold

remove_gluster_volume_bricks_not_found_from_cli

Could not find information for remove brick on volume from CLI.

start_removing_gluster_volume_bricks

Started removing bricks from Volume

start_removing_gluster_volume_bricks_detected_from_cli

Detected start of brick removal for bricks on volume from CLI

start_removing_gluster_volume_bricks_failed

Could not remove volume bricks

system_change_storage_pool_status_no_host_for_spm

Failed electing an SPM for the Data-Center

system_deactivated_storage_domain

Storage Domain state was set to inactive

user_add_vm_from_trusted_to_untrusted

A non-trusted VM was created from trusted Template

user_add_vm_from_untrusted_to_trusted

A trusted VM was created from non-trusted Template

user_add_vm_template_from_trusted_to_untrusted

A non-trusted Template was created from trusted VM

user_add_vm_template_from_untrusted_to_trusted

A trusted Template was created from non-trusted VM

user_host_maintenance

Host was switched to Maintenance Mode

user_host_maintenance_manual_ha

Host was switched to Maintenance Mode, but Hosted Engine HA maintenance mode could not be enabled

user_host_maintenance_migration_failed

Failed to switch Host to Maintenance mode

user_update_vm_from_trusted_to_untrusted

VM moved from trusted cluster to non-trusted cluster

user_update_vm_from_untrusted_to_trusted

VM moved from non-trusted cluster to trusted cluster

user_update_vm_template_from_trusted_to_untrusted

Template moved from trusted cluster to non-trusted cluster

user_update_vm_template_from_untrusted_to_trusted

Template moved from a non-trusted cluster to a trusted cluster

vm_console_connected

VM console connected

vm_console_disconnected

VM console disconnected

vm_down_error

VM is down with error

vm_failure

VM cannot be found on Host

vm_migration_failed

Migration failed

vm_migration_start

Starting migration of VM

vm_migration_to_server_failed

Migration of VM to a destination host failed

vm_not_responding

VM is not responding

vm_paused

VM has been paused

vm_paused_eio

VM has been paused due to a storage I/O error

vm_paused_enospc

VM has been paused due to lack of storage space

vm_paused_eperm

VM has been paused due to storage read/write permissions problem

vm_paused_error

VM has been paused due to unknown storage error

vm_recovered_from_pause_error

VM has recovered from paused back to up

vm_set_ticket

VM console session initiated

vm_status_restored

VM status restored

gluster_volume_rebalance_not_found_from_cli

Could not find information for rebalance on volume from CLI. Marking it as unknown.

host_untrusted

Host state was set to non-operational. Host is untrusted by the attestation service

remove_gluster_volume_bricks_not_found_from_cli

Could not find information for remove brick on volume from CLI. Marking it as unknown.

NotificationMethod enum

Type representing the notification method for an event subscription. Currently only SMTP is supported by the API In the future support for SNMP notifications may be added.

Table 1164. Values summary
Name Summary

smtp

Notification by e-mail.

snmp

Notification by SNMP.

smtp

Notification by e-mail.

Event-subscriptions with SMTP notification method will contain an email address in the address field.

snmp

Notification by SNMP.

Event-subscriptions with SNMP notification method will contain an SNMP address in the address field.

NumaNode struct

Represents a physical NUMA node.

Example XML representation:

<host_numa_node href="/ovirt-engine/api/hosts/0923f1ea/numanodes/007cf1ab" id="007cf1ab">
  <cpu>
    <cores>
      <core>
        <index>0</index>
      </core>
    </cores>
  </cpu>
  <index>0</index>
  <memory>65536</memory>
  <node_distance>40 20 40 10</node_distance>
  <host href="/ovirt-engine/api/hosts/0923f1ea" id="0923f1ea"/>
</host_numa_node>
Table 1165. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

cpu

Cpu

description

String

A human-readable description in plain text.

id

String

A unique identifier.

index

Integer

memory

Integer

Memory of the NUMA node in MB.

name

String

A human-readable name in plain text.

node_distance

String

Each host NUMA node resource exposes a statistics sub-collection for host NUMA node specific statistics.

An example of an XML representation:

<statistics>
  <statistic href="/ovirt-engine/api/hosts/123/numanodes/456/statistics/789" id="789">
    <name>memory.total</name>
    <description>Total memory</description>
    <kind>gauge</kind>
    <type>integer</type>
    <unit>bytes</unit>
    <values>
      <value>
        <datum>25165824000</datum>
      </value>
    </values>
    <host_numa_node href="/ovirt-engine/api/hosts/123/numanodes/456" id="456" />
  </statistic>
    ...
</statistics>
This statistics sub-collection is read-only.

The following list shows the statistic types for a host NUMA node:

Name Description

memory.total

Total memory in bytes on the NUMA node.

memory.used

Memory in bytes used on the NUMA node.

memory.free

Memory in bytes free on the NUMA node.

cpu.current.user

Percentage of CPU usage for user slice.

cpu.current.system

Percentage of CPU usage for system.

cpu.current.idle

Percentage of idle CPU usage.

NumaNodePin struct

Represents the pinning of a virtual NUMA node to a physical NUMA node.

Table 1167. Attributes summary
Name Type Summary

host_numa_node

NumaNode

Deprecated.

index

Integer

The index of a physical NUMA node to which the virtual NUMA node is pinned.

pinned

Boolean

Deprecated.

host_numa_node

Deprecated. Has no function.

pinned

Deprecated. Should always be true.

NumaTuneMode enum

Table 1168. Values summary
Name Summary

interleave

preferred

strict

OpenStackImage struct

Table 1169. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

OpenStackImageProvider struct

Table 1171. Attributes summary
Name Type Summary

authentication_url

String

Defines the external provider authentication URL address.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

password

String

Defines password for the user during the authentication process.

properties

Property[]

Array of provider name/value properties.

requires_authentication

Boolean

Defines whether provider authentication is required or not.

tenant_name

String

Defines the tenant name for OpenStack Identity API v2.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

tenant_name

Defines the tenant name for OpenStack Identity API v2.0.

OpenStackNetwork struct

Table 1173. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

OpenStackNetworkProvider struct

Table 1175. Attributes summary
Name Type Summary

agent_configuration

AgentConfiguration

Deprecated Agent configuration settings.

authentication_url

String

Defines the external provider authentication URL address.

auto_sync

Boolean

Indicates if the networks of this provider are automatically synchronized.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

external_plugin_type

String

Network plug-in type.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

password

String

Defines password for the user during the authentication process.

plugin_type

NetworkPluginType

Network plug-in type.

project_domain_name

String

Defines the project’s domain name for OpenStack Identity API v3.

project_name

String

Defines the project name for OpenStack Identity API v3.

properties

Property[]

Array of provider name/value properties.

read_only

Boolean

Indicates whether the provider is read-only.

requires_authentication

Boolean

Defines whether provider authentication is required or not.

tenant_name

String

Defines the tenant name for OpenStack Identity API v2.

type

OpenStackNetworkProviderType

The type of provider.

unmanaged

Boolean

Indicates whether the provider is unmanaged by {product-name}.

url

String

Defines URL address of the external provider.

user_domain_name

String

Defines the domain name of the username in ExternalProvider for OpenStack Identity API v3.

username

String

Defines user name to be used during authentication process.

agent_configuration

Deprecated Agent configuration settings.

Ignored, because the deployment of OpenStack Neutron agent is dropped since {product-name} 4.4.0.

auto_sync

Indicates if the networks of this provider are automatically synchronized.

If true, the networks of this provider are automatically and cyclically synchronized to {product-name} in the background. This means that all new networks of this provider are imported, and all discarded networks are removed from all clusters that have this external provider as the default provider. If the name of a network is changed on the provider, the change is synchronized to the network entity in {product-name}. Furthermore, if a new cluster that has the provider as the default provider is added, already imported networks are attached to this new cluster during synchronization.

The automatically initiated import triggers the following steps:

  • The networks of the external provider will be imported to every data center in the data centers of the clusters that have that external provider as the default provider.

  • A vNIC profile will be created for each involved data center and network.

  • The networks will be assigned to each cluster that has that external provider as the default provider.

All users are allowed to use the new vNIC Profile.

The default is false for backwards compatibility.

external_plugin_type

Network plug-in type.

This attribute allows you to choose the correct provider driver on the host when an external NIC is added or modified. If automated installation of the driver is supported (only available for some predefined implementations, for example ovirt-provider-ovn), this attribute will also allow the system to decide which driver implementation to install on newly added hosts.

plugin_type

Network plug-in type.

Since version 4.2 of the {engine-name}, this attribute has been deprecated in favour of external_plugin_type. This attribute is only valid for providers of type open_vswitch, and will only be returned when the value of the external_plugin_type attribute value is equal to open_vswitch.

If both plugin_type and external_plugin_type are specified during an update, the value of plugin_type will be ignored.

For external providers this value will not be shown and will be ignored during update requests.

read_only

Indicates whether the provider is read-only.

A read-only provider does not allow adding, modifying, or deleting of networks or subnets. Port-related operations are allowed, as they are required for the provisioning of virtual NICs.

requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

tenant_name

Defines the tenant name for OpenStack Identity API v2.0.

unmanaged

Indicates whether the provider is unmanaged by {product-name}.

If true, authentication and subnet control are entirely left to the external provider and are unmanaged by {product-name}.

The default is false for backwards compatibility.

OpenStackNetworkProviderType enum

The OpenStack network provider can either be implemented by OpenStack Neutron, in which case the Neutron agent is automatically installed on the hosts, or it can be an external provider implementing the OpenStack API, in which case the virtual interface driver is a custom solution installed manually.

Table 1177. Values summary
Name Summary

external

Indicates that the provider is an external one, implementing the OpenStack Neutron API.

neutron

Indicates that the provider is OpenStack Neutron.

external

Indicates that the provider is an external one, implementing the OpenStack Neutron API. The virtual interface driver in this case is implemented by the external provider.

neutron

Indicates that the provider is OpenStack Neutron. The standard OpenStack Neutron agent is used as the virtual interface driver.

OpenStackProvider struct

Table 1178. Attributes summary
Name Type Summary

authentication_url

String

Defines the external provider authentication URL address.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

password

String

Defines password for the user during the authentication process.

properties

Property[]

Array of provider name/value properties.

requires_authentication

Boolean

Defines whether provider authentication is required or not.

tenant_name

String

Defines the tenant name for OpenStack Identity API v2.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

tenant_name

Defines the tenant name for OpenStack Identity API v2.0.

OpenStackSubnet struct

Table 1179. Attributes summary
Name Type Summary

cidr

String

Defines network CIDR.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

dns_servers

String[]

Defines a list of DNS servers.

gateway

String

Defines IP gateway.

id

String

A unique identifier.

ip_version

String

Defines IP version.

name

String

A human-readable name in plain text.

ip_version

Defines IP version.

Values can be v4' for IPv4 or `v6 for IPv6.

OpenStackVolumeProvider struct

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 1181. Attributes summary
Name Type Summary

authentication_url

String

Defines the external provider authentication URL address.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

password

String

Defines password for the user during the authentication process.

properties

Property[]

Array of provider name/value properties.

requires_authentication

Boolean

Defines whether provider authentication is required or not.

tenant_name

String

Defines the tenant name for OpenStack Identity API v2.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

tenant_name

Defines the tenant name for OpenStack Identity API v2.0.

OpenStackVolumeType struct

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 1183. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

properties

Property[]

OpenstackVolumeAuthenticationKey struct

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 1185. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

creation_date

Date

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

usage_type

OpenstackVolumeAuthenticationKeyUsageType

uuid

String

value

String

OpenstackVolumeAuthenticationKeyUsageType enum

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 1187. Values summary
Name Summary

ceph

OperatingSystem struct

Information describing the operating system. This is used for both virtual machines and hosts.

Table 1188. Attributes summary
Name Type Summary

boot

Boot

Configuration of the boot sequence.

cmdline

String

Custom kernel parameters for starting the virtual machine if Linux operating system is used.

custom_kernel_cmdline

String

A custom part of the host kernel command line.

initrd

String

Path to custom initial ramdisk on ISO storage domain if Linux operating system is used.

kernel

String

Path to custom kernel on ISO storage domain if Linux operating system is used.

reported_kernel_cmdline

String

The host kernel command line as reported by a running host.

type

String

Operating system name in human readable form.

version

Version

boot

Configuration of the boot sequence.

Not used for hosts.

cmdline

Custom kernel parameters for starting the virtual machine if Linux operating system is used.

Not used for hosts.

custom_kernel_cmdline

A custom part of the host kernel command line. This will be merged with the existing kernel command line.

You must reinstall and then reboot the host to apply the changes implemented by this attribute.

During each host deploy procedure, kernel parameters that were added in the previous host deploy procedure are removed using grubby --update-kernel DEFAULT --remove-args <previous_custom_params>, and the current kernel command line customization is applied using grubby --update-kernel DEFAULT --args <custom_params>. The Manager internally keeps track of the last-applied kernel parameters customization.

This attribute is currently only used for hosts.

initrd

Path to custom initial ramdisk on ISO storage domain if Linux operating system is used.

For example iso://initramfs-3.10.0-514.6.1.el7.x86_64.img.

Not used for hosts.

kernel

Path to custom kernel on ISO storage domain if Linux operating system is used.

For example iso://vmlinuz-3.10.0-514.6.1.el7.x86_64.

Not used for hosts.

reported_kernel_cmdline

The host kernel command line as reported by a running host.

This is a read-only attribute. Attempts to change this attribute are silently ignored.

This attribute is currently only used for hosts.

type

Operating system name in human readable form.

For example Fedora or RHEL. In general one of the names returned by the operating system service.

Read only for hosts.

OperatingSystemInfo struct

Represents a guest operating system.

Table 1189. Attributes summary
Name Type Summary

architecture

Architecture

Operating system architecture.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

large_icon

Icon

Large icon of the guest operating system.

name

String

A human-readable name in plain text.

small_icon

Icon

Small icon of the guest operating system.

tpm_support

TpmSupport

TPM support status.

large_icon

Large icon of the guest operating system. Maximum dimensions: width 150px, height 120px.

small_icon

Small icon of the guest operating system. Maximum dimensions: width 43px, height 43px.

Option struct

Table 1190. Attributes summary
Name Type Summary

name

String

type

String

value

String

OsType enum

Type representing kind of operating system.

This type has been deprecated with the introduction of the OperatingSystemInfo type. Operating systems are available as a top-level collection in the API: operating_systems.

The end-user declares the type of the operating system installed in the virtual machine (guest operating system) by selecting one of these values. This declaration enables the system to tune the virtual machine configuration for better user experience. For example, the system chooses devices that are most suitable for the operating system. Note that the system rely on user’s selection and does not verify it by inspecting the actual guest operating system installed.

Table 1191. Values summary
Name Summary

other

Other type of operating system, not specified by the other values.

other_linux

Distribution of Linux other than those specified by the other values.

rhel_3

Red Hat Enterprise Linux 3 32-bit.

rhel_3x64

Red Hat Enterprise Linux 3 64-bit.

rhel_4

Red Hat Enterprise Linux 4 32-bit.

rhel_4x64

Red Hat Enterprise Linux 4 64-bit.

rhel_5

Red Hat Enterprise Linux 5 32-bit.

rhel_5x64

Red Hat Enterprise Linux 5 64-bit.

rhel_6

Red Hat Enterprise Linux 6 32-bit.

rhel_6x64

Red Hat Enterprise Linux 6 64-bit.

unassigned

This value is mapped to other.

windows_2003

Windows 2003 32-bit.

windows_2003x64

Windows 2003 64-bit.

windows_2008

Windows 2008 32-bit.

windows_2008r2x64

Windows 2008 R2 64-bit.

windows_2008x64

Windows 2008 64-bit.

windows_2012x64

Windows 2012 64-bit.

windows_7

Windows 7 32-bit.

windows_7x64

Windows 7 64-bit.

windows_8

Windows 8 32-bit.

windows_8x64

Windows 8 64-bit.

windows_xp

Windows XP.

Package struct

Type representing a package.

This is an example of the package element:

<package>
  <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>
Table 1192. Attributes summary
Name Type Summary

name

String

The name of the package.

ParallelMigrationsPolicy enum

Type representing parallel migration connections policy.

Table 1193. Values summary
Name Summary

auto

Choose automatically between parallel and non-parallel connections.

auto_parallel

Use parallel connections and select their number automatically.

custom

Use manually specified number of parallel connections.

disabled

Use non-parallel connections.

inherit

Use cluster value (applicable only to VMs).

auto

Choose automatically between parallel and non-parallel connections. If parallel connections are used, select their number automatically.

custom

Use manually specified number of parallel connections. The number of parallel connections must be set in MigrationOptions.customParallelMigrations.

Payload struct

Table 1194. Attributes summary
Name Type Summary

files

File[]

type

VmDeviceType

volume_id

String

PayloadEncoding enum

Table 1195. Values summary
Name Summary

base64

plaintext

Permission struct

Type represents a permission.

Table 1196. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Permit struct

Type represents a permit.

Table 1198. Attributes summary
Name Type Summary

administrative

Boolean

Specifies whether permit is administrative or not.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

PmProxy struct

Table 1200. Attributes summary
Name Type Summary

type

PmProxyType

PmProxyType enum

Table 1201. Values summary
Name Summary

cluster

The fence proxy is selected from the same cluster as the fenced host.

dc

The fence proxy is selected from the same data center as the fenced host.

other_dc

The fence proxy is selected from a different data center than the fenced host.

PolicyUnitType enum

Holds the types of all internal policy unit types.

Table 1202. Values summary
Name Summary

filter

load_balancing

weight

PortMirroring struct

PowerManagement struct

Table 1203. Attributes summary
Name Type Summary

address

String

The host name or IP address of the host.

agents

Agent[]

Specifies fence agent options when multiple fences are used.

automatic_pm_enabled

Boolean

Toggles the automated power control of the host in order to save energy.

enabled

Boolean

Indicates whether power management configuration is enabled or disabled.

kdump_detection

Boolean

Toggles whether to determine if kdump is running on the host before it is shut down.

options

Option[]

Fencing options for the selected type= specified with the option name="" and value="" strings.

password

String

A valid, robust password for power management.

pm_proxies

PmProxy[]

Determines the power management proxy.

status

PowerManagementStatus

Determines the power status of the host.

type

String

Fencing device code.

username

String

A valid user name for power management.

agents

Specifies fence agent options when multiple fences are used.

Use the order sub-element to prioritize the fence agents. Agents are run sequentially according to their order until the fence action succeeds. When two or more fence agents have the same order, they are run concurrently. Other sub-elements include type, ip, user, password, and options.

automatic_pm_enabled

Toggles the automated power control of the host in order to save energy. When set to true, the host will be automatically powered down if the cluster’s load is low, and powered on again when required. This is set to true when a host is created, unless disabled by the user.

kdump_detection

Toggles whether to determine if kdump is running on the host before it is shut down. When set to true, the host will not shut down during a kdump process. This is set to true when a host has power management enabled, unless disabled by the user.

type

Fencing device code.

A list of valid fencing device codes are available in the capabilities collection.

PowerManagementStatus enum

Table 1204. Values summary
Name Summary

off

Host is OFF.

on

Host is ON.

unknown

Unknown status.

Product struct

Table 1205. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

ProductInfo struct

Product information.

The entry point contains a product_info element to help an API user determine the legitimacy of the {product-name} environment. This includes the name of the product, the vendor and the version.

Verify a genuine {product-name} environment

The follow elements identify a genuine {product-name} environment:

<api>
...
<product_info>
  <name>oVirt Engine</name>
  <vendor>ovirt.org</vendor>
  <version>
    <build>0</build>
    <full_version>4.1.0_master</full_version>
    <major>4</major>
    <minor>1</minor>
    <revision>0</revision>
  </version>
</product_info>
...
</api>
Table 1206. Attributes summary
Name Type Summary

instance_id

String

The ID of this particular installation of the product.

name

String

The name of the product, for example oVirt Engine.

vendor

String

The name of the vendor, for example `ovirt.

version

Version

The version number of the product.

vendor

The name of the vendor, for example ovirt.org.

ProfileDetail struct

Table 1207. Attributes summary
Name Type Summary

block_statistics

BlockStatistic[]

duration

Integer

fop_statistics

FopStatistic[]

profile_type

String

statistics

Statistic[]

Property struct

Table 1208. Attributes summary
Name Type Summary

name

String

value

String

ProxyTicket struct

Table 1209. Attributes summary
Name Type Summary

value

String

QcowVersion enum

The QCOW version specifies to the qemu which qemu version the volume supports.

This field can be updated using the update API and will be reported only for QCOW volumes, it is determined by the storage domain’s version which the disk is created on. Storage domains with version lower than V4 support QCOW2 version 2 volumes, while V4 storage domains also support QCOW2 version 3. For more information about features of the different QCOW versions, see here.

Table 1210. Values summary
Name Summary

qcow2_v2

The Copy On Write default compatibility version It means that every QEMU can use it.

qcow2_v3

The Copy On Write compatibility version which was introduced in QEMU 1.

qcow2_v3

The Copy On Write compatibility version which was introduced in QEMU 1.1 It means that the new format is in use.

Qos struct

This type represents the attributes to define Quality of service (QoS).

For storage the type is storage, the attributes max_throughput, max_read_throughput, max_write_throughput, max_iops, max_read_iops and max_write_iops are relevant.

For resources with computing capabilities the type is cpu, the attribute cpu_limit is relevant.

For virtual machines networks the type is network, the attributes inbound_average, inbound_peak, inbound_burst, outbound_average, outbound_peak and outbound_burst are relevant.

For host networks the type is hostnetwork, the attributes outbound_average_linkshare, outbound_average_upperlimit and outbound_average_realtime are relevant.

Table 1211. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

cpu_limit

Integer

The maximum processing capability in %.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

inbound_average

Integer

The desired average inbound bit rate in Mbps (Megabits per sec).

inbound_burst

Integer

The amount of data that can be delivered in a single burst, in MB.

inbound_peak

Integer

The maximum inbound rate in Mbps (Megabits per sec).

max_iops

Integer

Maximum permitted number of input and output operations per second.

max_read_iops

Integer

Maximum permitted number of input operations per second.

max_read_throughput

Integer

Maximum permitted throughput for read operations.

max_throughput

Integer

Maximum permitted total throughput.

max_write_iops

Integer

Maximum permitted number of output operations per second.

max_write_throughput

Integer

Maximum permitted throughput for write operations.

name

String

A human-readable name in plain text.

outbound_average

Integer

The desired average outbound bit rate in Mbps (Megabits per sec).

outbound_average_linkshare

Integer

Weighted share.

outbound_average_realtime

Integer

The committed rate in Mbps (Megabits per sec).

outbound_average_upperlimit

Integer

The maximum bandwidth to be used by a network in Mbps (Megabits per sec).

outbound_burst

Integer

The amount of data that can be sent in a single burst, in MB.

outbound_peak

Integer

The maximum outbound rate in Mbps (Megabits per sec).

type

QosType

The kind of resources this entry can be assigned.

cpu_limit

The maximum processing capability in %.

Used to configure computing resources.

inbound_average

The desired average inbound bit rate in Mbps (Megabits per sec).

Used to configure virtual machines networks. If defined, inbound_peak and inbound_burst also has to be set.

See Libvirt-QOS for further details.

inbound_burst

The amount of data that can be delivered in a single burst, in MB.

Used to configure virtual machine networks. If defined, inbound_average and inbound_peak must also be set.

See Libvirt-QOS for further details.

inbound_peak

The maximum inbound rate in Mbps (Megabits per sec).

Used to configure virtual machines networks. If defined, inbound_average and inbound_burst also has to be set.

See Libvirt-QOS for further details.

max_iops

Maximum permitted number of input and output operations per second.

Used to configure storage. Must not be set if max_read_iops or max_write_iops is set.

max_read_iops

Maximum permitted number of input operations per second.

Used to configure storage. Must not be set if max_iops is set.

max_read_throughput

Maximum permitted throughput for read operations.

Used to configure storage. Must not be set if max_throughput is set.

max_throughput

Maximum permitted total throughput.

Used to configure storage. Must not be set if max_read_throughput or max_write_throughput is set.

max_write_iops

Maximum permitted number of output operations per second.

Used to configure storage. Must not be set if max_iops is set.

max_write_throughput

Maximum permitted throughput for write operations.

Used to configure storage. Must not be set if max_throughput is set.

outbound_average

The desired average outbound bit rate in Mbps (Megabits per sec).

Used to configure virtual machines networks. If defined, outbound_peak and outbound_burst also has to be set.

See Libvirt-QOS for further details.

outbound_average_linkshare

Weighted share.

Used to configure host networks. Signifies how much of the logical link’s capacity a specific network should be allocated, relative to the other networks attached to the same logical link. The exact share depends on the sum of shares of all networks on that link. By default this is a number in the range 1-100.

outbound_average_realtime

The committed rate in Mbps (Megabits per sec).

Used to configure host networks. The minimum bandwidth required by a network. The committed rate requested is not guaranteed and will vary depending on the network infrastructure and the committed rate requested by other networks on the same logical link.

outbound_average_upperlimit

The maximum bandwidth to be used by a network in Mbps (Megabits per sec).

Used to configure host networks. If outboundAverageUpperlimit and outbound_average_realtime are provided, the outbound_averageUpperlimit must not be lower than the outbound_average_realtime.

See Libvirt-QOS for further details.

outbound_burst

The amount of data that can be sent in a single burst, in MB.

Used to configure virtual machine networks. If defined, outbound_average and outbound_peak must also be set.

See Libvirt-QOS for further details.

outbound_peak

The maximum outbound rate in Mbps (Megabits per sec).

Used to configure virtual machines networks. If defined, outbound_average and outbound_burst also has to be set.

See Libvirt-QOS for further details.

QosType enum

This type represents the kind of resource the Quality of service (QoS) can be assigned to.

Table 1213. Values summary
Name Summary

cpu

The Quality of service (QoS) can be assigned to resources with computing capabilities.

hostnetwork

The Quality of service (QoS) can be assigned to host networks.

network

The Quality of service (QoS) can be assigned to virtual machines networks.

storage

The Quality of service (QoS) can be assigned to storage.

Quota struct

Represents a quota object.

An example XML representation of a quota:

<quota href="/ovirt-engine/api/datacenters/7044934e/quotas/dcad5ddc" id="dcad5ddc">
  <name>My Quota</name>
  <description>A quota for my oVirt environment</description>
  <cluster_hard_limit_pct>0</cluster_hard_limit_pct>
  <cluster_soft_limit_pct>0</cluster_soft_limit_pct>
  <data_center href="/ovirt-engine/api/datacenters/7044934e" id="7044934e"/>
  <storage_hard_limit_pct>0</storage_hard_limit_pct>
  <storage_soft_limit_pct>0</storage_soft_limit_pct>
</quota>
Table 1214. Attributes summary
Name Type Summary

cluster_hard_limit_pct

Integer

cluster_soft_limit_pct

Integer

comment

String

Free text containing comments about this object.

data_center

DataCenter

description

String

A human-readable description in plain text.

disks

Disk[]

id

String

A unique identifier.

name

String

A human-readable name in plain text.

storage_hard_limit_pct

Integer

storage_soft_limit_pct

Integer

users

User[]

vms

Vm[]

QuotaClusterLimit struct

Table 1216. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

memory_limit

Decimal

memory_usage

Decimal

name

String

A human-readable name in plain text.

vcpu_limit

Integer

vcpu_usage

Integer

QuotaModeType enum

Table 1218. Values summary
Name Summary

audit

disabled

enabled

QuotaStorageLimit struct

Table 1219. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

limit

Integer

name

String

A human-readable name in plain text.

usage

Decimal

Range struct

Table 1221. Attributes summary
Name Type Summary

from

String

to

String

Rate struct

Determines maximum speed of consumption of bytes from random number generator device.

Table 1222. Attributes summary
Name Type Summary

bytes

Integer

Number of bytes allowed to consume per period.

period

Integer

Duration of one period in milliseconds.

RegistrationAffinityGroupMapping struct

This type describes how to map affinity groups as part of the object registration. An object can be a virtual machine, template, etc.

An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <affinity_group_mappings>
     <registration_affinity_group_mapping>
       <from>
         <name>affinity</name>
       </from>
       <to>
         <name>affinity2</name>
       </to>
     </registration_affinity_group_mapping>
    </affinity_group_mappings>
  </registration_configuration>
</action>

Reference to the original affinity group. It can be specified using name.

RegistrationAffinityLabelMapping struct

This type describes how to map affinity labels as part of the object registration. An object can be a virtual machine, template, etc.

An example of an XML representation using mapping:

<action>
  <registration_configuration>
    <affinity_label_mappings>
     <registration_affinity_label_mapping>
       <from>
         <name>affinity_label</name>
       </from>
       <to>
         <name>affinity_label2</name>
       </to>
     </registration_affinity_label_mapping>
    </affinity_label_mappings>
  </registration_configuration>
</action>

Reference to the original affinity label. It can be specified using name.

RegistrationClusterMapping struct

This type describes how to map clusters as part of the object registration. An object can be a virtual machine, template, etc.

An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <cluster_mappings>
      <registration_cluster_mapping>
        <from>
          <name>myoriginalcluster</name>
        </from>
        <to>
          <name>mynewcluster</name>
        </to>
      </registration_cluster_mapping>
    </cluster_mappings>
  </registration_configuration>
</action>

Reference to the original cluster. It can be specified using the id or the name.

Reference to the destination cluster. It can be specified using the id or the name.

RegistrationConfiguration struct

This type describes how an object (virtual machine, template, etc) is registered, and is used for the implementation of disaster recovery solutions.

Each mapping contained in this type can be used to map objects in the original system to corresponding objects in the system where the virtual machine or template is being registered. For example, there could be a primary setup with a virtual machine configured on cluster A, and an active secondary setup with cluster B. Cluster B is compatible with that virtual machine, and in case of a disaster recovery scenario the storage domain can be imported to the secondary setup, and the user can register the virtual machine to cluster B.

In that case, we can automate the recovery process by defining a cluster mapping. After the entity is registered, its OVF will indicate it belongs to cluster A, but the mapping will indicate that cluster A will be replaced with cluster B. {engine-name} should do the switch and register the virtual machine to cluster B in the secondary site.

Cluster mapping is just one example, there are different types of mappings:

  • Cluster mapping.

  • LUN mapping.

  • Role mapping.

  • Domain mapping.

  • Permissions mapping.

  • Affinity Group mapping.

  • Affinity Label mapping.

  • Virtual NIC profile mapping.

Each mapping will be used for its specific OVF’s data once the register operation takes place in the {engine-name}.

An example of an XML representation using the mapping:

<action>
  <registration_configuration>
    <cluster_mappings>
      <registration_cluster_mapping>
        <from>
          <name>myoriginalcluster</name>
        </from>
        <to>
          <name>mynewcluster</name>
        </to>
      </registration_cluster_mapping>
    </cluster_mappings>
    <role_mappings>
      <registration_role_mapping>
        <from>
          <name>SuperUser</name>
        </from>
        <to>
          <name>UserVmRunTimeManager</name>
        </to>
      </registration_role_mapping>
    </role_mappings>
    <domain_mappings>
      <registration_domain_mapping>
        <from>
          <name>redhat</name>
        </from>
        <to>
          <name>internal</name>
        </to>
      </registration_domain_mapping>
    </domain_mappings>
    <lun_mappings>
     <registration_lun_mapping>
       <from id="111">
       </from>
       <to id="222">
         <alias>weTestLun</alias>
         <lun_storage>
           <type>iscsi</type>
           <logical_units>
              <logical_unit id="36001405fb1ddb4b91e44078f1fffcfef">
                 <address>44.33.11.22</address>
                 <port>3260</port>
                 <portal>1</portal>
                 <target>iqn.2017-11.com.name.redhat:444</target>
              </logical_unit>
           </logical_units>
         </lun_storage>
       </to>
     </registration_lun_mapping>
    </lun_mappings>
    <affinity_group_mappings>
     <registration_affinity_group_mapping>
       <from>
         <name>affinity</name>
       </from>
       <to>
         <name>affinity2</name>
       </to>
     </registration_affinity_group_mapping>
    </affinity_group_mappings>
    <affinity_label_mappings>
     <registration_affinity_label_mapping>
       <from>
         <name>affinity_label</name>
       </from>
       <to>
         <name>affinity_label2</name>
       </to>
     </registration_affinity_label_mapping>
    </affinity_label_mappings>
    <vnic_profile_mappings>
      <registration_vnic_profile_mapping>
        <from>
          <name>gold</name>
          <network>
            <name>red</name>
          </network>
        </from>
        <to id="738dd914-8ec8-4a8b-8628-34672a5d449b"/>
      </registration_vnic_profile_mapping>
      <registration_vnic_profile_mapping>
        <from>
          <name>silver</name>
          <network>
            <name>blue</name>
          </network>
        </from>
        <to>
          <name>copper</name>
          <network>
            <name>orange</name>
          </network>
        </to>
      </registration_vnic_profile_mapping>
    </vnic_profile_mappings>
  </registration_configuration>
</action>
Table 1226. Attributes summary
Name Type Summary

affinity_group_mappings

RegistrationAffinityGroupMapping[]

Describes how the affinity groups are mapped.

affinity_label_mappings

RegistrationAffinityLabelMapping[]

Describes how the affinity labels are mapped.

cluster_mappings

RegistrationClusterMapping[]

Describes how the clusters that the object references are mapped.

domain_mappings

RegistrationDomainMapping[]

Describes how the users' domains are mapped.

lun_mappings

RegistrationLunMapping[]

Describes how the LUNs are mapped.

role_mappings

RegistrationRoleMapping[]

Describes how the roles are mapped.

vnic_profile_mappings

RegistrationVnicProfileMapping[]

Mapping rules for virtual NIC profiles that will be applied during the register process.

RegistrationDomainMapping struct

This type describes how to map the users' domain as part of the object registration. An object can be a virtual machine, template, etc. NOTE: This is based on the assumption that user names will be the same, and that only the domain name will be changed.

An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <domain_mappings>
      <registration_domain_mapping>
        <from>
          <name>redhat</name>
        </from>
        <to>
          <name>internal</name>
        </to>
      </registration_domain_mapping>
    </domain_mappings>
  </registration_configuration>
</action>

Reference to the original domain. It can be specified using name.

RegistrationLunMapping struct

This type describes how to map LUNs as part of the object registration. An object can be a virtual machine, template, etc.

An external LUN disk is an entity which does not reside on a storage domain. It must be specified because it doesn’t need to exist in the environment where the object is registered. An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <lun_mappings>
      <registration_lun_mapping>
    <lun_mappings>
     <registration_lun_mapping>
       <from id="111">
       </from>
       <to id="222">
         <alias>weTestLun</alias>
         <lun_storage>
           <type>iscsi</type>
           <logical_units>
              <logical_unit id="36001405fb1ddb4b91e44078f1fffcfef">
                 <address>44.33.11.22</address>
                 <port>3260</port>
                 <portal>1</portal>
                 <target>iqn.2017-11.com.name.redhat:444</target>
              </logical_unit>
           </logical_units>
         </lun_storage>
       </to>
     </registration_lun_mapping>
    </lun_mappings>
  </registration_configuration>
</action>

Reference to the original LUN. This must be specified using the id attribute.

RegistrationRoleMapping struct

This type describes how to map roles as part of the object registration. An object can be a virtual machine, template, etc.

A role mapping is intended to map correlating roles between the primary site and the secondary site. For example, there may be permissions with role UserVmRunTimeManager for the virtual machine that is being registered. Therefore we can send a mapping that will register the virtual machine in the secondary setup using the SuperUser role instead of UserVmRunTimeManager An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <role_mappings>
      <registration_eole_mapping>
        <from>
          <name>SuperUser</name>
        </from>
        <to>
          <name>UserVmRunTimeManager</name>
        </to>
      </registration_role_mapping>
    </role_mappings>
  </registration_configuration>
</action>

Reference to the original role. It can be specified using name.

RegistrationVnicProfileMapping struct

Maps an external virtual NIC profile to one that exists in the {engine-name}. The target may be specified as a profile ID or a pair of profile name and network name.

If, for example, the desired virtual NIC profile mapping includes the following lines:

Source network name Source network profile name Target virtual NIC profile ID\names

red

gold

738dd914-8ec8-4a8b-8628-34672a5d449b

<empty> (no network name)

<empty> (no network profile name)

892a12ec-2028-4451-80aa-ff3bf55d6bac

blue

silver

orange\copper

yellow

platinum

<empty> (no profile)

green

bronze

Then the following snippet should be added to RegistrationConfiguration

<vnic_profile_mappings>
  <registration_vnic_profile_mapping>
    <from>
      <name>gold</name>
      <network>
        <name>red</name>
      </network>
    </from>
    <to id="738dd914-8ec8-4a8b-8628-34672a5d449b"/>
  </registration_vnic_profile_mapping>
  <registration_vnic_profile_mapping>
    <from>
      <name></name>
      <network>
        <name></name>
      </network>
    </from>
    <to id="892a12ec-2028-4451-80aa-ff3bf55d6bac"/>
  </registration_vnic_profile_mapping>
  <registration_vnic_profile_mapping>
    <from>
      <name>silver</name>
      <network>
        <name>blue</name>
      </network>
    </from>
    <to>
      <name>copper</name>
      <network>
        <name>orange</name>
      </network>
    </to>
  </registration_vnic_profile_mapping>
  <registration_vnic_profile_mapping>
    <from>
      <name>platinum</name>
      <network>
        <name>yellow</name>
      </network>
    </from>
    <to>
      <name></name>
      <network>
        <name></name>
      </network>
    </to>
  </registration_vnic_profile_mapping>
  <registration_vnic_profile_mapping>
    <from>
      <name>bronze</name>
      <network>
        <name>green</name>
      </network>
    </from>
  </registration_vnic_profile_mapping>
</vnic_profile_mappings>

References to the external network and the external network profile. Both should be specified using their name.

Reference to to an existing virtual NIC profile. It should be specified using its name or id. Either name or id should be specified but not both.

ReportedConfiguration struct

Table 1231. Attributes summary
Name Type Summary

actual_value

String

expected_value

String

in_sync

Boolean

false when the network attachment contains uncommitted network configuration.

name

String

ReportedDevice struct

Table 1232. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

ips

Ip[]

mac

Mac

name

String

A human-readable name in plain text.

type

ReportedDeviceType

ReportedDeviceType enum

Table 1234. Values summary
Name Summary

network

ResolutionType enum

Table 1235. Values summary
Name Summary

add

copy

RngDevice struct

Random number generator (RNG) device model.

Table 1236. Attributes summary
Name Type Summary

rate

Rate

Determines maximum speed of consumption of bytes from random number generator device.

source

RngSource

Backend of the random number generator device.

RngSource enum

Representing the random generator backend types.

Table 1237. Values summary
Name Summary

hwrng

Obtains random data from the /dev/hwrng (usually specialized HW generator) device.

random

Obtains random data from the /dev/random device.

urandom

Obtains random data from the /dev/urandom device.

urandom

Obtains random data from the /dev/urandom device.

This RNG source is meant to replace random RNG source for non-cluster-aware entities (i.e. Blank template and instance types) and entities associated with clusters with compatibility version 4.1 or higher.

Role struct

Represents a system role.

Table 1238. Attributes summary
Name Type Summary

administrative

Boolean

Defines the role as administrative-only or not.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

mutable

Boolean

Defines the ability to update or delete the role.

name

String

A human-readable name in plain text.

mutable

Defines the ability to update or delete the role.

Roles with mutable set to false are predefined roles.

RoleType enum

Type representing whether a role is administrative or not. A user which was granted at least one administrative role is considered an administrator.

Table 1240. Values summary
Name Summary

admin

Administrative role.

user

User role.

SchedulingPolicy struct

Table 1241. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

default_policy

Boolean

description

String

A human-readable description in plain text.

id

String

A unique identifier.

locked

Boolean

name

String

A human-readable name in plain text.

properties

Property[]

SchedulingPolicyUnit struct

Table 1243. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

enabled

Boolean

id

String

A unique identifier.

internal

Boolean

name

String

A human-readable name in plain text.

properties

Property[]

type

PolicyUnitType

ScsiGenericIO enum

When a direct LUN disk is using SCSI passthrough the privileged I/O policy is determined by this enum.

Table 1244. Values summary
Name Summary

disabled

Disable SCSI passthrough.

filtered

Disallow privileged SCSI I/O.

unfiltered

Allow privileged SCSI I/O.

SeLinux struct

Represents SELinux in the system.

Table 1245. Attributes summary
Name Type Summary

mode

SeLinuxMode

SELinux current mode.

SeLinuxMode enum

Represents an SELinux enforcement mode.

Table 1246. Values summary
Name Summary

disabled

SELinux is disabled in the kernel.

enforcing

SELinux is running and enforcing permissions.

permissive

SELinux is running and logging but not enforcing permissions.

SerialNumber struct

Table 1247. Attributes summary
Name Type Summary

policy

SerialNumberPolicy

value

String

SerialNumberPolicy enum

Type representing the policy of a Serial Number.

Table 1248. Values summary
Name Summary

custom

This policy allows the user to provide an arbitrary string as the Serial Number.

host

This policy is the legacy policy.

none

This policy is used to remove the Serial Number Policy, moving it to default: null.

vm

This policy will use the Virtual Machine ID as the Serial Number.

host

This policy is the legacy policy. It will use the Host ID as the Serial Number.

Session struct

Describes a user session to a virtual machine.

Table 1249. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

console_user

Boolean

Indicates if this is a console session.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

ip

Ip

The IP address the user is connected from.

name

String

A human-readable name in plain text.

protocol

String

The protocol used by the session.

console_user

Indicates if this is a console session.

The value will be true for console users (SPICE or VNC), and false for others (such as RDP or SSH).

ip

The IP address the user is connected from.

Currently only available for console users.

protocol

The protocol used by the session.

Currently not used. Intended for info about how the user is connected: through SPICE, VNC, SSH, or RDP.

The user related to this session.

If the user is a console user, this is a link to the real {product-name} user. Otherwise, only the user name is provided.

SkipIfConnectivityBroken struct

Table 1251. Attributes summary
Name Type Summary

enabled

Boolean

If enabled, we will not fence a host in case more than a configurable percentage of hosts in the cluster lost connectivity as well.

threshold

Integer

Threshold for connectivity testing.

enabled

If enabled, we will not fence a host in case more than a configurable percentage of hosts in the cluster lost connectivity as well. This comes to prevent fencing storm in cases where there is a global networking issue in the cluster.

threshold

Threshold for connectivity testing. If at least the threshold percentage of hosts in the cluster lost connectivity then fencing will not take place.

SkipIfSdActive struct

This type represents the storage related configuration in the fencing policy.

Table 1252. Attributes summary
Name Type Summary

enabled

Boolean

If enabled, we will skip fencing in case the host maintains its lease in the storage.

enabled

If enabled, we will skip fencing in case the host maintains its lease in the storage. It means that if the host still has storage access then it won’t get fenced.

Snapshot struct

Represents a snapshot object.

Example XML representation:

<snapshot id="456" href="/ovirt-engine/api/vms/123/snapshots/456">
  <actions>
    <link rel="restore" href="/ovirt-engine/api/vms/123/snapshots/456/restore"/>
  </actions>
  <vm id="123" href="/ovirt-engine/api/vms/123"/>
  <description>Virtual Machine 1 - Snapshot A</description>
  <type>active</type>
  <date>2010-08-16T14:24:29</date>
  <persist_memorystate>false</persist_memorystate>
</snapshot>
Table 1253. Attributes summary
Name Type Summary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

custom_emulated_machine

String

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

date

Date

The date when this snapshot has been created.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

fqdn

String

Fully qualified domain name of the virtual machine.

guest_operating_system

GuestOperatingSystem

What operating system is installed on the virtual machine.

guest_time_zone

TimeZone

What time zone is used by the virtual machine (as returned by guest agent).

has_illegal_images

Boolean

Indicates whether the virtual machine has snapshots with disks in ILLEGAL state.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

next_run_configuration_exists

Boolean

Virtual machine configuration has been changed and requires restart of the virtual machine.

numa_tune_mode

NumaTuneMode

How the NUMA topology is applied.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

payloads

Payload[]

Optional payloads of the virtual machine, used for ISOs to configure it.

persist_memorystate

Boolean

Indicates if the content of the memory of the virtual machine is included in the snapshot.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

run_once

Boolean

If true, the virtual machine has been started using the run once command, meaning it’s configuration might differ from the stored one for the purpose of this single run.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

snapshot_status

SnapshotStatus

Status of the snapshot.

snapshot_type

SnapshotType

Type of the snapshot.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

start_time

Date

The date in which the virtual machine was started.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

status

VmStatus

The current status of the virtual machine.

status_detail

String

Human readable detail of current status.

stop_reason

String

The reason the virtual machine was stopped.

stop_time

Date

The date in which the virtual machine was stopped.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

use_latest_template_version

Boolean

If true, the virtual machine is reconfigured to the latest version of it’s template when it is started.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

initialization

Reference to the virtual machine’s initialization configuration.

Since {product-name} 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from {product-name} 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since {product-name} 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.
{engine-name} internally rounds values down to whole MiBs (1MiB = 220 bytes)

migration

Reference to configuration of migration of a running virtual machine to another host.

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

next_run_configuration_exists

Virtual machine configuration has been changed and requires restart of the virtual machine. Changed configuration is applied at processing the virtual machine’s shut down.

numa_tune_mode

How the NUMA topology is applied. Deprecated in favor of NUMA tune per vNUMA node.

origin

The origin of this virtual machine.

Possible values:

  • ovirt

  • rhev

  • vmware

  • xen

  • external

  • hosted_engine

  • managed_hosted_engine

  • kvm

  • physical_machine

  • hyperv

persist_memorystate

Indicates if the content of the memory of the virtual machine is included in the snapshot.

When a snapshot is created the default value is true.

placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

stop_reason

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual machine.

tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

Optional. Used for labeling of sub-clusters.

Lists all the Katello errata assigned to the virtual machine.

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

You will receive response in XML like this one:

<katello_errata>
  <katello_erratum href="/ovirt-engine/api/katelloerrata/456" id="456">
    <name>RHBA-2013:XYZ</name>
    <description>The description of the erratum</description>
    <title>some bug fix update</title>
    <type>bugfix</type>
    <issued>2013-11-20T02:00:00.000+02:00</issued>
    <solution>Few guidelines regarding the solution</solution>
    <summary>Updated packages that fix one bug are now available for XYZ</summary>
    <packages>
      <package>
        <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
      </package>
      ...
    </packages>
  </katello_erratum>
  ...
</katello_errata>

References the original template used to create the virtual machine.

If the virtual machine is cloned from a template or another virtual machine, the template links to the Blank template, and the original_template is used to track history.

Otherwise the template and original_template are the same.

Statistics data collected from this virtual machine.

Note that some statistics, notably memory.buffered and memory.cached are available only when {virt-product-fullname} guest agent is installed in the virtual machine.

SnapshotStatus enum

Represents the current status of the snapshot.

Table 1255. Values summary
Name Summary

in_preview

The snapshot is being previewed.

locked

The snapshot is locked.

ok

The snapshot is OK.

locked

The snapshot is locked.

The snapshot is locked when it is in process of being created, deleted, restored or previewed.

SnapshotType enum

Represents the type of the snapshot.

Table 1256. Values summary
Name Summary

active

Reference to the current configuration of the virtual machines.

preview

The active snapshot will become preview if some snapshot is being previewed.

regular

Snapshot created by user.

stateless

Snapshot created internally for stateless virtual machines.

preview

The active snapshot will become preview if some snapshot is being previewed.

In other words, this is the active snapshot before preview.

stateless

Snapshot created internally for stateless virtual machines.

This snapshot is created when the virtual machine is started and it is restored when the virtual machine is shut down.

SpecialObjects struct

This type contains references to special objects, such as blank templates and the root of a hierarchy of tags.

Spm struct

Table 1258. Attributes summary
Name Type Summary

priority

Integer

status

SpmStatus

SpmStatus enum

Table 1259. Values summary
Name Summary

contending

none

spm

Ssh struct

Table 1260. Attributes summary
Name Type Summary

authentication_method

SshAuthenticationMethod

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

fingerprint

String

Fingerprint of SSH public key for a host.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

port

Integer

public_key

String

SSH public key of the host using SSH public key format as defined in link:https://tools.

user

User

fingerprint

Fingerprint of SSH public key for a host. This field is deprecated since 4.4.5 and will be removed in the future.

Please use publicKey instead.

public_key

SSH public key of the host using SSH public key format as defined in RFC4253.

SshAuthenticationMethod enum

Table 1261. Values summary
Name Summary

password

publickey

SshPublicKey struct

Table 1262. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

content

String

Contains a saved SSH key.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Sso struct

Table 1264. Attributes summary
Name Type Summary

methods

Method[]

SsoMethod enum

Table 1265. Values summary
Name Summary

guest_agent

Statistic struct

A generic type used for all kinds of statistics.

Statistic contains the statistics values for various entities. The following object contain statistics:

  • Disk

  • Host

  • HostNic

  • NumaNode

  • Nic

  • Vm

  • GlusterBrick

  • Step

  • GlusterVolume

An example of a XML representation:

<statistics>
  <statistic id="1234" href="/ovirt-engine/api/hosts/1234/nics/1234/statistics/1234">
    <name>data.current.rx</name>
    <description>Receive data rate</description>
    <values type="DECIMAL">
      <value>
        <datum>0</datum>
      </value>
    </values>
    <type>GAUGE</type>
    <unit>BYTES_PER_SECOND</unit>
    <host_nic id="1234" href="/ovirt-engine/api/hosts/1234/nics/1234"/>
  </statistic>
  ...
</statistics>
This statistics sub-collection is read-only.
Table 1266. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

kind

StatisticKind

The type of statistic measures.

name

String

A human-readable name in plain text.

type

ValueType

The data type for the statistical values that follow.

unit

StatisticUnit

The unit or rate to measure of the statistical values.

values

Value[]

A data set that contains datum.

StatisticKind enum

Table 1268. Values summary
Name Summary

counter

gauge

StatisticUnit enum

Table 1269. Values summary
Name Summary

bits_per_second

bytes

bytes_per_second

count_per_second

none

percent

seconds

Step struct

Represents a step, which is part of job execution. Step is used to describe and track a specific execution unit which is part of a wider sequence. Some steps support reporting their progress.

Table 1270. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

end_time

Date

The end time of the step.

external

Boolean

Indicates if the step is originated by an external system.

external_type

ExternalSystemType

The external system which is referenced by the step.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

number

Integer

The order of the step in current hierarchy level.

progress

Integer

The step progress (if reported) in percentages.

start_time

Date

The start time of the step.

status

StepStatus

The status of the step.

type

StepEnum

The type of the step.

external

Indicates if the step is originated by an external system. External steps are managed externally, by the creator of the step.

StepEnum enum

Type representing a step type.

Table 1272. Values summary
Name Summary

executing

The executing step type.

finalizing

The finalizing step type.

rebalancing_volume

The rebalancing volume step type.

removing_bricks

The removing bricks step type.

unknown

The unknown step type.

validating

The validation step type.

executing

The executing step type. Used to track the main execution block of the job. Usually it will be a parent step of several sub-steps which describe portions of the execution step.

finalizing

The finalizing step type. Describes the post-execution steps requires to complete the job.

rebalancing_volume

The rebalancing volume step type. Describes a step type which is part of Gluster flow.

removing_bricks

The removing bricks step type. Describes a step type which is part of Gluster flow.

unknown

The unknown step type. Describes a step type which its origin is unknown.

validating

The validation step type. Used to verify the correctness of parameters and the validity of the parameters prior to the execution.

StepStatus enum

Represents the status of the step.

Table 1273. Values summary
Name Summary

aborted

The aborted step status.

failed

The failed step status.

finished

The finished step status.

started

The started step status.

unknown

The unknown step status.

aborted

The aborted step status. This status is applicable for an external step that was forcibly aborted.

finished

The finished step status. This status describes a completed step execution.

started

The started step status. This status represents a step which is currently being executed.

unknown

The unknown step status. This status represents steps which their resolution is not known, i.e. steps that were executed before the system was unexpectedly restarted.

StorageConnection struct

Represents a storage server connection.

Example XML representation:

<storage_connection id="123">
  <address>mynfs.example.com</address>
  <type>nfs</type>
  <path>/exports/mydata</path>
</storage_connection>
Table 1274. Attributes summary
Name Type Summary

address

String

A storage server connection’s address.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

mount_options

String

The mount options of an NFS storage server connection.

name

String

A human-readable name in plain text.

nfs_retrans

Integer

The NFS retrans value of an NFS storage server connection.

nfs_timeo

Integer

The NFS timeo value of an NFS storage server connection.

nfs_version

NfsVersion

The NFS version of an NFS storage server connection.

password

String

The password of an iSCSI storage server connection.

path

String

The path of an NFS storage server connection.

port

Integer

The port of an iSCSI storage server connection.

portal

String

The portal of an iSCSI storage server connection.

target

String

The target of an iSCSI storage server connection.

type

StorageType

A storage server connection’s type.

username

String

The user name of an iSCSI storage server connection.

vfs_type

String

The VFS type of an NFS storage server connection.

StorageConnectionExtension struct

Table 1276. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

password

String

target

String

username

String

StorageDomain struct

Storage domain.

An XML representation of a NFS storage domain with identifier 123:

<storage_domain href="/ovirt-engine/api/storagedomains/123" id="123">
  <name>mydata</name>
  <description>My data</description>
  <available>38654705664</available>
  <committed>1073741824</committed>
  <critical_space_action_blocker>5</critical_space_action_blocker>
  <external_status>ok</external_status>
  <master>true</master>
  <storage>
    <address>mynfs.example.com</address>
    <nfs_version>v3</nfs_version>
    <path>/exports/mydata</path>
    <type>nfs</type>
  </storage>
  <storage_format>v3</storage_format>
  <type>data</type>
  <used>13958643712</used>
  <warning_low_space_indicator>10</warning_low_space_indicator>
  <wipe_after_delete>false</wipe_after_delete>
  <data_centers>
    <data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
  </data_centers>
</storage_domain>
Table 1278. Attributes summary
Name Type Summary

available

Integer

backup

Boolean

This attribute indicates whether a data storage domain is used as backup domain or not.

block_size

Integer

Specifies block size in bytes for a storage domain.

comment

String

Free text containing comments about this object.

committed

Integer

critical_space_action_blocker

Integer

description

String

A human-readable description in plain text.

discard_after_delete

Boolean

Indicates whether disks' blocks on block storage domains will be discarded right before they are deleted.

external_status

ExternalStatus

id

String

A unique identifier.

import

Boolean

master

Boolean

name

String

A human-readable name in plain text.

status

StorageDomainStatus

storage

HostStorage

storage_format

StorageFormat

supports_discard

Boolean

Indicates whether a block storage domain supports discard operations.

supports_discard_zeroes_data

Boolean

Indicates whether a block storage domain supports the property that discard zeroes the data.

type

StorageDomainType

used

Integer

warning_low_space_indicator

Integer

wipe_after_delete

Boolean

Serves as the default value of wipe_after_delete for disks on this storage domain.

backup

This attribute indicates whether a data storage domain is used as backup domain or not. If the domain is set to backup then it will be used to store virtual machines and templates for disaster recovery purposes in the same way we use export storage domain. This attribute is only available with data storage domain and not with ISO domain or export storage domain. User can use this functionality while creating a data storage domain or importing a data storage domain.

block_size

Specifies block size in bytes for a storage domain. Can be omitted and in that case will be defaulted to 512 bytes. Not all storage domains support all possible sizes.

discard_after_delete

Indicates whether disks' blocks on block storage domains will be discarded right before they are deleted.

If true, and a disk on this storage domain has its wipe_after_delete value enabled, then when the disk is deleted:

  1. It is first wiped.

  2. Then its blocks are discarded.

  3. Finally it is deleted.

Note that:

  • Discard after delete will always be false for non block storage types.

  • Discard after delete can be set to true only if the storage domain supports discard.

supports_discard

Indicates whether a block storage domain supports discard operations. A storage domain only supports discard if all of the logical units that it is built from support discard; that is, if each logical unit’s discard_max_size value is greater than 0. This is one of the conditions necessary for a virtual disk in this storage domain to have its pass_discard attribute enabled.

supports_discard_zeroes_data

Indicates whether a block storage domain supports the property that discard zeroes the data. A storage domain only supports the property that discard zeroes the data if all of the logical units that it is built from support it; that is, if each logical unit’s discard_zeroes_data value is true.

Since version 4.2.1 of the system, the support for this attribute has been removed as the sysfs file, discard_zeroes_data, was deprecated in the kernel. It is preserved for backwards compatibility, but the value will always be false.

wipe_after_delete

Serves as the default value of wipe_after_delete for disks on this storage domain.

That is, newly created disks will get their wipe_after_delete value from their storage domains by default. Note that the configuration value SANWipeAfterDelete serves as the default value of block storage domains' wipe_after_delete value.

A link to the data center that the storage domain is attached to. This is preserved for backwards compatibility only, as the storage domain may be attached to multiple data centers (if it is an ISO domain). Use the dataCenters element instead.

StorageDomainLease struct

Represents a lease residing on a storage domain.

A lease is a Sanlock resource residing on a special volume on the storage domain, this Sanlock resource is used to provide storage base locking.

StorageDomainStatus enum

Table 1281. Values summary
Name Summary

activating

active

detaching

inactive

locked

maintenance

mixed

preparing_for_maintenance

unattached

unknown

StorageDomainType enum

Indicates the kind of data managed by a storage domain.

Table 1282. Values summary
Name Summary

data

Data domains are used to store the disks and snapshots of the virtual machines and templates in the system.

export

Export domains are temporary storage repositories used to copy and move virtual machines and templates between data centers and {product-name} environments.

image

Image domain store images that can be imported into from an external system.

iso

ISO domains store ISO files (or logical CDs) used to install and boot operating systems and applications for the virtual machines.

managed_block_storage

Managed block storage domains are created on block storage devices.

volume

Volume domains store logical volumes that can be used as disks for virtual machines.

data

Data domains are used to store the disks and snapshots of the virtual machines and templates in the system. In addition, snapshots of the disks are also stored in data domains. Data domains cannot be shared across data centers.

export

Export domains are temporary storage repositories used to copy and move virtual machines and templates between data centers and {product-name} environments. Export domains can also be used to backup virtual machines. An export domain can be moved between data centers but it can only be active in one data center at a time.

image

Image domain store images that can be imported into from an external system. For example, images from an OpenStack Glance image repository.

iso

ISO domains store ISO files (or logical CDs) used to install and boot operating systems and applications for the virtual machines. ISO domains remove the data center’s need for physical media. An ISO domain can be shared across different data centers.

managed_block_storage

Managed block storage domains are created on block storage devices. These domains are accessed and managed by cinder.

volume

Volume domains store logical volumes that can be used as disks for virtual machines. For example, volumes from an OpenStack Cincer block storage service.

StorageFormat enum

Type which represents a format of storage domain.

Table 1283. Values summary
Name Summary

v1

Version 1 of the storage domain format is applicable to NFS, iSCSI and FC storage domains.

v2

Version 2 of the storage domain format is applicable to iSCSI and FC storage domains.

v3

Version 3 of the storage domain format is applicable to NFS, POSIX, iSCSI and FC storage domains.

v4

Version 4 of the storage domain format.

v5

Version 5 of the storage domain format is applicable to NFS, POSIX, and Gluster storage domains.

v1

Version 1 of the storage domain format is applicable to NFS, iSCSI and FC storage domains.

Each storage domain contains metadata describing its own structure, and all of the names of physical volumes that are used to back virtual machine disk images. Master domains additionally contain metadata for all the domains and physical volume names in the storage pool. The total size of this metadata is limited to 2 KiB, limiting the number of storage domains that can be in a pool. Template and virtual machine base images are read only.

v2

Version 2 of the storage domain format is applicable to iSCSI and FC storage domains.

All storage domain and pool metadata is stored as logical volume tags rather than written to a logical volume. Metadata about virtual machine disk volumes is still stored in a logical volume on the domains. Physical volume names are no longer included in the metadata. Template and virtual machine base images are read only.

v3

Version 3 of the storage domain format is applicable to NFS, POSIX, iSCSI and FC storage domains.

All storage domain and pool metadata is stored as logical volume tags rather than written to a logical volume. Metadata about virtual machine disk volumes is still stored in a logical volume on the domains. Virtual machine and template base images are no longer read only. This change enables live snapshots, live storage migration, and clone from snapshot. Support for Unicode metadata is added, for non-English volume names.

v5

Version 5 of the storage domain format is applicable to NFS, POSIX, and Gluster storage domains.

Added support for 4096 bytes block sizes and variable sanlock alignments.

StorageType enum

Type representing a storage domain type.

Table 1284. Values summary
Name Summary

cinder

Cinder storage domain.

fcp

Fibre-Channel storage domain.

glance

Glance storage domain.

glusterfs

Gluster-FS storage domain.

iscsi

iSCSI storage domain.

localfs

Storage domain on Local storage.

managed_block_storage

Managed block storage domain.

nfs

NFS storage domain.

posixfs

POSIX-FS storage domain.

cinder

Cinder storage domain. For more details on Cinder please go to Cinder.

glance

Glance storage domain. For more details on Glance please go to Glance.

glusterfs

Gluster-FS storage domain. For more details on Gluster please go to Gluster.

managed_block_storage

Managed block storage domain. A storage domain managed using cinderlib. For supported storage drivers, see Available Drivers.

SwitchType enum

Describes all switch types supported by the Manager.

Table 1285. Values summary
Name Summary

legacy

The native switch type.

ovs

The Open vSwitch type.

SystemOption struct

Type representing a configuration option of the system.

Table 1286. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

values

SystemOptionValue[]

Values of the option for various system versions.

SystemOptionValue struct

Type representing a pair of value and version of a configuration option.

Table 1287. Attributes summary
Name Type Summary

value

String

Configuration option’s value for specific version.

version

String

Configuration option’s version.

Tag struct

Represents a tag in the system.

Table 1288. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Template struct

The type that represents a virtual machine template. Templates allow for a rapid instantiation of virtual machines with common configuration and disk states.

Table 1290. Attributes summary
Name Type Summary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

custom_emulated_machine

String

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

status

TemplateStatus

The status of the template.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

version

TemplateVersion

Indicates whether this is the base version or a sub-version of another template.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

vm

Vm

The virtual machine configuration associated with this template.

auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

initialization

Reference to the virtual machine’s initialization configuration.

Since {product-name} 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from {product-name} 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since {product-name} 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.
{engine-name} internally rounds values down to whole MiBs (1MiB = 220 bytes)

migration

Reference to configuration of migration of a running virtual machine to another host.

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

origin

The origin of this virtual machine.

Possible values:

  • ovirt

  • rhev

  • vmware

  • xen

  • external

  • hosted_engine

  • managed_hosted_engine

  • kvm

  • physical_machine

  • hyperv

placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

TemplateStatus enum

Type representing a status of a virtual machine template.

Table 1292. Values summary
Name Summary

illegal

This status indicates that at least one of the disks of the template is illegal.

locked

This status indicates that some operation that prevents other operations with the template is being executed.

ok

This status indicates that the template is valid and ready for use.

TemplateVersion struct

Type representing a version of a virtual machine template.

Table 1293. Attributes summary
Name Type Summary

version_name

String

The name of this version.

version_number

Integer

The index of this version in the versions hierarchy of the template.

version_number

The index of this version in the versions hierarchy of the template. The index 1 represents the original version of a template that is also called base version.

Ticket struct

Type representing a ticket that allows virtual machine access.

Table 1295. Attributes summary
Name Type Summary

expiry

Integer

Time to live for the ticket in seconds.

value

String

The virtual machine access ticket.

TimeZone struct

Time zone representation.

Table 1296. Attributes summary
Name Type Summary

name

String

Name of the time zone.

utc_offset

String

UTC offset.

utc_offset

UTC offset.

Offset from UTC.

TpmSupport enum

Table 1297. Values summary
Name Summary

required

TPM is required by the operating system

supported

TPM is supported but optional

unsupported

TransparentHugePages struct

Type representing a transparent huge pages (THP) support.

Table 1298. Attributes summary
Name Type Summary

enabled

Boolean

Enable THP support.

TransportType enum

Protocol used to access a Gluster volume.

Table 1299. Values summary
Name Summary

rdma

Remote direct memory access.

tcp

TCP.

UnmanagedNetwork struct

Table 1300. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Usb struct

Configuration of the USB device of a virtual machine.

Table 1302. Attributes summary
Name Type Summary

enabled

Boolean

Determines whether the USB device should be included or not.

type

UsbType

USB type, currently only native is supported.

UsbType enum

Type of USB device redirection.

Table 1303. Values summary
Name Summary

legacy

Legacy USB redirection.

native

Native USB redirection.

legacy

Legacy USB redirection.

This USB type has been deprecated since version 3.6 of the engine, and has been completely removed in version 4.1. It is preserved only to avoid syntax errors in existing scripts. If it is used it will be automatically replaced by native.

native

Native USB redirection.

Native USB redirection allows KVM/SPICE USB redirection for Linux and Windows virtual machines. Virtual (guest) machines require no guest-installed agents or drivers for native USB. On Linux clients, all packages required for USB redirection are provided by the virt-viewer package. On Windows clients, you must also install the usbdk package.

User struct

Represents a user in the system.

Table 1304. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

department

String

description

String

A human-readable description in plain text.

domain_entry_id

String

email

String

id

String

A unique identifier.

last_name

String

logged_in

Boolean

name

String

A human-readable name in plain text.

namespace

String

Namespace where the user resides.

password

String

principal

String

Similar to user_name.

user_name

String

The user’s username.

user_options

Property[]

User options allow you to save key/value properties which are used to customize the settings per individual user.

namespace

Namespace where the user resides. When using the authorization provider that stores users in the LDAP server, this attribute equals the naming context of the LDAP server. See oVirt Engine Extension AAA LDAP for more information. When using the built-in authorization provider that stores users in the database this attribute is ignored. See oVirt Engine extension - AAA - JDBC for more information.

principal

Similar to user_name. The format depends on the LDAP provider. With most LDAP providers it is the value of the uid LDAP attribute. In the case of Active Directory it is the User Principal Name (UPN).

user_name

The user’s username. The format depends on authorization provider type. In most LDAP providers it is the value of the uid LDAP attribute. In Active Directory it is the User Principal Name (UPN). UPN or uid must be followed by the authorization provider name. For example, in the case of LDAP’s uid attribute it is: myuser@myextension-authz. In the case of Active Directory using UPN it is: myuser@mysubdomain.mydomain.com@myextension-authz. This attribute is a required parameter when adding a new user.

user_options

User options allow you to save key/value properties which are used to customize the settings per individual user. Note that since version 4.4.5 this property is deprecated and preserved only for backwards compatibility. It will be removed in the future. Please use the options endpoint instead.

UserOption struct

User options allow you to save key/value properties which are used to customize the settings per individual user.

Table 1306. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

content

String

JSON content encoded as string.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

content

JSON content encoded as string. Any valid JSON is supported.

Value struct

Table 1308. Attributes summary
Name Type Summary

datum

Decimal

detail

String

ValueType enum

Table 1309. Values summary
Name Summary

decimal

integer

string

VcpuPin struct

Table 1310. Attributes summary
Name Type Summary

cpu_set

String

vcpu

Integer

Vendor struct

Table 1311. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Version struct

Table 1312. Attributes summary
Name Type Summary

build

Integer

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

full_version

String

id

String

A unique identifier.

major

Integer

minor

Integer

name

String

A human-readable name in plain text.

revision

Integer

VgpuPlacement enum

The vGPU placement strategy.

It can either put vGPUs on the first available physical cards, or spread them over multiple physical cards.

Table 1313. Values summary
Name Summary

consolidated

Use consolidated placement.

separated

Use separated placement.

consolidated

Use consolidated placement. Each vGPU is placed on the first physical card with available space.

This is the default placement, utilizing all available space on the physical cards.

separated

Use separated placement. Each vGPU is placed on a separate physical card, if possible.

This can be useful for improving vGPU performance.

VirtioScsi struct

Type representing the support of virtio-SCSI. If it supported we use virtio driver for SCSI guest device.

Table 1314. Attributes summary
Name Type Summary

enabled

Boolean

Enable Virtio SCSI support.

VirtualNumaNode struct

Represents the virtual NUMA node.

An example XML representation:

<vm_numa_node href="/ovirt-engine/api/vms/123/numanodes/456" id="456">
  <cpu>
    <cores>
      <core>
        <index>0</index>
      </core>
    </cores>
  </cpu>
  <index>0</index>
  <memory>1024</memory>
  <numa_node_pins>
    <numa_node_pin>
      <index>0</index>
    </numa_node_pin>
  </numa_node_pins>
  <vm href="/ovirt-engine/api/vms/123" id="123" />
</vm_numa_node>
Table 1315. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

cpu

Cpu

description

String

A human-readable description in plain text.

id

String

A unique identifier.

index

Integer

memory

Integer

Memory of the NUMA node in MB.

name

String

A human-readable name in plain text.

node_distance

String

numa_node_pins

NumaNodePin[]

numa_tune_mode

NumaTuneMode

How the NUMA topology is applied.

Each host NUMA node resource exposes a statistics sub-collection for host NUMA node specific statistics.

An example of an XML representation:

<statistics>
  <statistic href="/ovirt-engine/api/hosts/123/numanodes/456/statistics/789" id="789">
    <name>memory.total</name>
    <description>Total memory</description>
    <kind>gauge</kind>
    <type>integer</type>
    <unit>bytes</unit>
    <values>
      <value>
        <datum>25165824000</datum>
      </value>
    </values>
    <host_numa_node href="/ovirt-engine/api/hosts/123/numanodes/456" id="456" />
  </statistic>
    ...
</statistics>
This statistics sub-collection is read-only.

The following list shows the statistic types for a host NUMA node:

Name Description

memory.total

Total memory in bytes on the NUMA node.

memory.used

Memory in bytes used on the NUMA node.

memory.free

Memory in bytes free on the NUMA node.

cpu.current.user

Percentage of CPU usage for user slice.

cpu.current.system

Percentage of CPU usage for system.

cpu.current.idle

Percentage of idle CPU usage.

Vlan struct

Type representing a Virtual LAN (VLAN) type.

Table 1317. Attributes summary
Name Type Summary

id

Integer

Virtual LAN ID.

Vm struct

Represents a virtual machine.

Table 1318. Attributes summary
Name Type Summary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

custom_emulated_machine

String

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

fqdn

String

Fully qualified domain name of the virtual machine.

guest_operating_system

GuestOperatingSystem

What operating system is installed on the virtual machine.

guest_time_zone

TimeZone

What time zone is used by the virtual machine (as returned by guest agent).

has_illegal_images

Boolean

Indicates whether the virtual machine has snapshots with disks in ILLEGAL state.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

next_run_configuration_exists

Boolean

Virtual machine configuration has been changed and requires restart of the virtual machine.

numa_tune_mode

NumaTuneMode

How the NUMA topology is applied.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

payloads

Payload[]

Optional payloads of the virtual machine, used for ISOs to configure it.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

run_once

Boolean

If true, the virtual machine has been started using the run once command, meaning it’s configuration might differ from the stored one for the purpose of this single run.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

start_time

Date

The date in which the virtual machine was started.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

status

VmStatus

The current status of the virtual machine.

status_detail

String

Human readable detail of current status.

stop_reason

String

The reason the virtual machine was stopped.

stop_time

Date

The date in which the virtual machine was stopped.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

use_latest_template_version

Boolean

If true, the virtual machine is reconfigured to the latest version of it’s template when it is started.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

initialization

Reference to the virtual machine’s initialization configuration.

Since {product-name} 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from {product-name} 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since {product-name} 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.
{engine-name} internally rounds values down to whole MiBs (1MiB = 220 bytes)

migration

Reference to configuration of migration of a running virtual machine to another host.

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

next_run_configuration_exists

Virtual machine configuration has been changed and requires restart of the virtual machine. Changed configuration is applied at processing the virtual machine’s shut down.

numa_tune_mode

How the NUMA topology is applied. Deprecated in favor of NUMA tune per vNUMA node.

origin

The origin of this virtual machine.

Possible values:

  • ovirt

  • rhev

  • vmware

  • xen

  • external

  • hosted_engine

  • managed_hosted_engine

  • kvm

  • physical_machine

  • hyperv

placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

stop_reason

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual machine.

tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

Optional. Used for labeling of sub-clusters.

Lists all the Katello errata assigned to the virtual machine.

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

You will receive response in XML like this one:

<katello_errata>
  <katello_erratum href="/ovirt-engine/api/katelloerrata/456" id="456">
    <name>RHBA-2013:XYZ</name>
    <description>The description of the erratum</description>
    <title>some bug fix update</title>
    <type>bugfix</type>
    <issued>2013-11-20T02:00:00.000+02:00</issued>
    <solution>Few guidelines regarding the solution</solution>
    <summary>Updated packages that fix one bug are now available for XYZ</summary>
    <packages>
      <package>
        <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
      </package>
      ...
    </packages>
  </katello_erratum>
  ...
</katello_errata>

References the original template used to create the virtual machine.

If the virtual machine is cloned from a template or another virtual machine, the template links to the Blank template, and the original_template is used to track history.

Otherwise the template and original_template are the same.

Statistics data collected from this virtual machine.

Note that some statistics, notably memory.buffered and memory.cached are available only when {virt-product-fullname} guest agent is installed in the virtual machine.

VmAffinity enum

Table 1320. Values summary
Name Summary

migratable

pinned

user_migratable

VmBase struct

Represents basic virtual machine configuration. This is used by virtual machines, templates and instance types.

Table 1321. Attributes summary
Name Type Summary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

custom_emulated_machine

String

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

initialization

Reference to the virtual machine’s initialization configuration.

Since {product-name} 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from {product-name} 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since {product-name} 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.
{engine-name} internally rounds values down to whole MiBs (1MiB = 220 bytes)

migration

Reference to configuration of migration of a running virtual machine to another host.

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

origin

The origin of this virtual machine.

Possible values:

  • ovirt

  • rhev

  • vmware

  • xen

  • external

  • hosted_engine

  • managed_hosted_engine

  • kvm

  • physical_machine

  • hyperv

placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

VmDeviceType enum

Table 1323. Values summary
Name Summary

cdrom

floppy

VmMediatedDevice struct

VM mediated device is a fake device specifying properties of vGPU mediated devices. It is not an actual device, it just serves as a specification how to configure a part of a host device.

Table 1324. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

spec_params

Property[]

Properties of the device.

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

VmPlacementPolicy struct

Table 1326. Attributes summary
Name Type Summary

affinity

VmAffinity

VmPool struct

Type representing a virtual machines pool.

Table 1328. Attributes summary
Name Type Summary

auto_storage_select

Boolean

Indicates if the pool should automatically distribute the disks of the virtual machines across the multiple storage domains where the template is copied.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

display

Display

The display settings configured for virtual machines in the pool.

id

String

A unique identifier.

max_user_vms

Integer

The maximum number of virtual machines in the pool that could be assigned to a particular user.

name

String

A human-readable name in plain text.

prestarted_vms

Integer

The system attempts to prestart the specified number of virtual machines from the pool.

rng_device

RngDevice

The random number generator device configured for virtual machines in the pool.

size

Integer

The number of virtual machines in the pool.

soundcard_enabled

Boolean

Indicates if sound card should be configured for virtual machines in the pool.

stateful

Boolean

Virtual machine pool’s stateful flag.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

type

VmPoolType

The deallocation policy of virtual machines in the pool.

use_latest_template_version

Boolean

Indicates if virtual machines in the pool are updated to newer versions of the template the pool is based on.

auto_storage_select

Indicates if the pool should automatically distribute the disks of the virtual machines across the multiple storage domains where the template is copied.

When the template used by the pool is present in multiple storage domains, the disks of the virtual machines of the pool will be created in one of those storage domains. By default, or when the value of this attribute is false, that storage domain is selected when the pool is created, and all virtual machines will use the same. If this attribute is true, then, when a virtual machine is added to the pool, the storage domain that has more free space is selected.

display

The display settings configured for virtual machines in the pool.

Please note that this attribute is not working and is now deprecated. Please use Vm.display instead.

prestarted_vms

The system attempts to prestart the specified number of virtual machines from the pool.

These virtual machines are started without being attached to any user. That way, users can acquire virtual machines from the pool faster.

stateful

Virtual machine pool’s stateful flag.

Virtual machines from a stateful virtual machine pool are always started in stateful mode (stateless snapshot is not created). The state of the virtual machine is preserved even when the virtual machine is passed to a different user.

tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

Reference to the instance type on which this pool is based. It can be set only on pool creation and cannot be edited.

Reference to an arbitrary virtual machine that is part of the pool.

Note that this virtual machine may not be based to the latest version of the pool’s template.

VmPoolType enum

Type representing the deallocation policy of virtual machines in a virtual machines pool.

Table 1330. Values summary
Name Summary

automatic

This policy indicates that virtual machines in the pool are automcatically deallocated by the system.

manual

This policy indicates that virtual machines in the pool are deallocated manually by the administrator.

automatic

This policy indicates that virtual machines in the pool are automcatically deallocated by the system.

With this policy, when a virtual machine that is part of the pool and is assigned to a user is shut-down, it is detached from the user, its state is restored to the pool’s default state, and the virtual machine returns to pool (i.e., the virtual machine can then be assigned to another user).

manual

This policy indicates that virtual machines in the pool are deallocated manually by the administrator.

With this policy, a virtual machine that is part of the pool remains assigned to its user and preserves its state on shut-down. In order to return the virtual machine back to the pool, the administrator needs to deallocate it explicitly by removing the user’s permissions on that virtual machine.

VmStatus enum

Type representing a status of a virtual machine.

Table 1331. Values summary
Name Summary

down

This status indicates that the virtual machine process is not running.

image_locked

This status indicates that the virtual machine process is not running and there is some operation on the disks of the virtual machine that prevents it from being started.

migrating

This status indicates that the virtual machine process is running and the virtual machine is being migrated from one host to another.

not_responding

This status indicates that the hypervisor detected that the virtual machine is not responding.

paused

This status indicates that the virtual machine process is running and the virtual machine is paused.

powering_down

This status indicates that the virtual machine process is running and it is about to stop running.

powering_up

This status indicates that the virtual machine process is running and the guest operating system is being loaded.

reboot_in_progress

This status indicates that the virtual machine process is running and the guest operating system is being rebooted.

restoring_state

This status indicates that the virtual machine process is about to run and the virtual machine is going to awake from hibernation.

saving_state

This status indicates that the virtual machine process is running and the virtual machine is being hibernated.

suspended

This status indicates that the virtual machine process is not running and a running state of the virtual machine was saved.

unassigned

This status is set when an invalid status is received.

unknown

This status indicates that the system failed to determine the status of the virtual machine.

up

This status indicates that the virtual machine process is running and the guest operating system is loaded.

wait_for_launch

This status indicates that the virtual machine process is about to run.

paused

This status indicates that the virtual machine process is running and the virtual machine is paused. This may happen in two cases: when running a virtual machine is paused mode and when the virtual machine is being automatically paused due to an error.

powering_up

This status indicates that the virtual machine process is running and the guest operating system is being loaded. Note that if no guest-agent is installed, this status is set for a predefined period of time, that is by default 60 seconds, when running a virtual machine.

restoring_state

This status indicates that the virtual machine process is about to run and the virtual machine is going to awake from hibernation. In this status, the running state of the virtual machine is being restored.

saving_state

This status indicates that the virtual machine process is running and the virtual machine is being hibernated. In this status, the running state of the virtual machine is being saved. Note that this status does not mean that the guest operating system is being hibernated.

suspended

This status indicates that the virtual machine process is not running and a running state of the virtual machine was saved. This status is similar to Down, but when the VM is started in this status its saved running state is restored instead of being booted using the normal procedue.

unknown

This status indicates that the system failed to determine the status of the virtual machine. The virtual machine process may be running or not running in this status. For instance, when host becomes non-responsive the virtual machines that ran on it are set with this status.

up

This status indicates that the virtual machine process is running and the guest operating system is loaded. Note that if no guest-agent is installed, this status is set after a predefined period of time, that is by default 60 seconds, when running a virtual machine.

wait_for_launch

This status indicates that the virtual machine process is about to run. This status is set when a request to run a virtual machine arrives to the host. It is possible that the virtual machine process will fail to run.

VmStorageErrorResumeBehaviour enum

If the storage, on which this virtual machine has some disks gets unresponsive, the virtual machine gets paused.

This are the possible options, what should happen with the virtual machine in the moment the storage gets available again.

Table 1332. Values summary
Name Summary

auto_resume

The virtual machine gets resumed automatically in the moment the storage is available again.

kill

The virtual machine will be killed after a timeout (configurable on the hypervisor).

leave_paused

Do nothing with the virtual machine.

auto_resume

The virtual machine gets resumed automatically in the moment the storage is available again.

This is the only behavior available before 4.2.

kill

The virtual machine will be killed after a timeout (configurable on the hypervisor).

This is the only option supported for highly available virtual machines with leases. The reason is that the highly available virtual machine is restarted using the infrastructure and any kind of resume risks split brains.

leave_paused

Do nothing with the virtual machine.

Useful if there is a custom failover implemented and the user does not want the virtual machine to get resumed.

VmSummary struct

Type containing information related to virtual machines on a particular host.

Table 1333. Attributes summary
Name Type Summary

active

Integer

The number of virtual machines active on the host.

migrating

Integer

The number of virtual machines migrating to or from the host.

total

Integer

The number of virtual machines present on the host.

VmType enum

Type representing what the virtual machine is optimized for.

Table 1334. Values summary
Name Summary

desktop

The virtual machine is intended to be used as a desktop.

high_performance

The virtual machine is intended to be used as a high performance virtual machine.

server

The virtual machine is intended to be used as a server.

desktop

The virtual machine is intended to be used as a desktop.

Currently, its implication is that a sound device will automatically be added to the virtual machine.

high_performance

The virtual machine is intended to be used as a high performance virtual machine.

Currently, its implication is that the virtual machine configuration will automatically be set for running with the highest possible performance, and with performance metrics as close to bare metal as possible.

Some of the recommended configuration settings for the highest possible performance cannot be set automatically; manually setting them before running the virtual machine is recommended.

The following configuration changes are set automatically:

  • Enable headless mode.

  • Enable serial console.

  • Enable pass-through host CPU.

  • Enable I/O threads.

  • Enable I/O threads pinning and set the pinning topology.

  • Enable the paravirtualized random number generator PCI (virtio-rng) device.

  • Disable all USB devices.

  • Disable the soundcard device.

  • Disable the smartcard device.

  • Disable the memory balloon device.

  • Disable the watchdog device.

  • Disable migration.

  • Disable high availability.

The following recommended configuration changes have to be set manually by the user:

  • Enable CPU pinning topology.

  • Enable non-uniform memory access (NUMA) pinning topology.

  • Enable and set huge pages configuration.

  • Disable kernel same-page merging (KSM).

server

The virtual machine is intended to be used as a server.

Currently, its implication is that a sound device will not automatically be added to the virtual machine.

VnicPassThrough struct

Table 1335. Attributes summary
Name Type Summary

mode

VnicPassThroughMode

Defines whether the vNIC will be implemented as a virtual device, or as a pass-through to a host device.

VnicPassThroughMode enum

Describes whether the vNIC is to be implemented as a pass-through device or a virtual one.

Table 1336. Values summary
Name Summary

disabled

To be implemented as a virtual device.

enabled

To be implemented as a pass-through device.

VnicProfile struct

A vNIC profile is a collection of settings that can be applied to individual NIC.

Table 1337. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

custom_properties

CustomProperty[]

Custom properties applied to the vNIC profile.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

migratable

Boolean

Marks whether pass_through NIC is migratable or not.

name

String

A human-readable name in plain text.

pass_through

VnicPassThrough

Enables passthrough to an SR-IOV-enabled host NIC.

port_mirroring

Boolean

Enables port mirroring.

migratable

Marks whether pass_through NIC is migratable or not.

If pass_through.mode is set to disabled this option has no meaning, and it will be considered to be true. If you omit this option from a request, by default, this will be set to true.

When migrating a virtual machine, this virtual machine will be migrated only if all pass_through NICs are flagged as migratable.

pass_through

Enables passthrough to an SR-IOV-enabled host NIC.

A vNIC profile enables a NIC to be directly connected to a virtual function (VF) of an SR-IOV-enabled host NIC, if passthrough is enabled. The NIC will then bypass the software network virtualization and connect directly to the VF for direct device assignment.

Passthrough cannot be enabled if the vNIC profile is already attached to a NIC. If a vNIC profile has passthrough enabled, qos and port_mirroring are disabled for the vNIC profile.

port_mirroring

Enables port mirroring.

Port mirroring copies layer 3 network traffic on a given logical network and host to a NIC on a virtual machine. This virtual machine can be used for network debugging and tuning, intrusion detection, and monitoring the behavior of other virtual machines on the same host and logical network. The only traffic copied is internal to one logical network on one host. There is no increase in traffic on the network external to the host; however a virtual machine with port mirroring enabled uses more host CPU and RAM than other virtual machines.

Port mirroring has the following limitations:

  • Hot linking a NIC with a vNIC profile that has port mirroring enabled is not supported.

  • Port mirroring cannot be altered when the vNIC profile is attached to a virtual machine.

Given the above limitations, it is recommended that you enable port mirroring on an additional, dedicated vNIC profile.

Enabling port mirroring reduces the privacy of other network users.

Reference to the top-level network filter that applies to the NICs that use this profile.

Network filters enhance the ability to manage the network packets traffic to and from virtual machines. The network filter may either contain a reference to other filters, rules for traffic filtering, or a combination of both.

Reference to the quality of service attributes to apply to the vNIC profile.

Quality of Service attributes regulate inbound and outbound network traffic of the NIC.

VnicProfileMapping struct

Deprecated type that maps an external virtual NIC profile to one that exists in the {engine-name}.

If, for example, the desired virtual NIC profile’s mapping includes the following two lines:

Source network name Source network profile name Target virtual NIC profile ID

red

gold

738dd914-8ec8-4a8b-8628-34672a5d449b

blue

silver

892a12ec-2028-4451-80aa-ff3bf55d6bac

The following form is deprecated since 4.2.1 and will be removed in the future:

<vnic_profile_mappings>
  <vnic_profile_mapping>
    <source_network_name>red</source_network_name>
    <source_network_profile_name>gold</source_network_profile_name>
    <target_vnic_profile id="738dd914-8ec8-4a8b-8628-34672a5d449b"/>
  </vnic_profile_mapping>
  <vnic_profile_mapping>
    <source_network_name>blue</source_network_name>
    <source_network_profile_name>silver</source_network_profile_name>
    <target_vnic_profile id="892a12ec-2028-4451-80aa-ff3bf55d6bac"/>
  </vnic_profile_mapping>
</vnic_profile_mappings>
Table 1339. Attributes summary
Name Type Summary

source_network_name

String

Deprecated attribute describing the name of the external network.

source_network_profile_name

String

Deprecated attribute describing the name of the external network profile.

source_network_name

Deprecated attribute describing the name of the external network.

Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future.

source_network_profile_name

Deprecated attribute describing the name of the external network profile.

Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future.

Deprecated attribute describing an existing virtual NIC profile.

Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future.

VolumeGroup struct

Table 1341. Attributes summary
Name Type Summary

id

String

logical_units

LogicalUnit[]

name

String

Watchdog struct

This type represents a watchdog configuration.

Table 1342. Attributes summary
Name Type Summary

action

WatchdogAction

Watchdog action to be performed when watchdog is triggered.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

model

WatchdogModel

Model of watchdog device.

name

String

A human-readable name in plain text.

model

Model of watchdog device. Currently supported only I6300ESB.

References to the virtual machines that are using this device. A device may be used by several virtual machines; for example, a shared disk my be used simultaneously by two or more virtual machines.

WatchdogAction enum

This type describes available watchdog actions.

Table 1344. Values summary
Name Summary

dump

Virtual machine process will get core dumped to the default path on the host.

none

No action will be performed when watchdog action is triggered.

pause

Virtual machine will be paused when watchdog action is triggered.

poweroff

Virtual machine will be powered off when watchdog action is triggered.

reset

Virtual machine will be rebooted when watchdog action is triggered.

none

No action will be performed when watchdog action is triggered. However log message will still be generated.

WatchdogModel enum

This type represents the watchdog model.

Table 1345. Values summary
Name Summary

diag288

The watchdog model for S390X machines.

i6300esb

PCI based watchdog model.

diag288

The watchdog model for S390X machines.

S390X has an integrated watchdog facility that is controlled via the DIAG288 instruction. Use this model for S390X virtual machines.

i6300esb

PCI based watchdog model.

Use the I6300ESB watchdog for x86_64 and PPC64 virtual machines.

Weight struct

Table 1346. Attributes summary
Name Type Summary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

factor

Integer

id

String

A unique identifier.

name

String

A human-readable name in plain text.

Appendix A: Primitive types

This section describes the primitive data types supported by the API.

String primitive

A finite sequence of Unicode characters.

Boolean primitive

Represents the false and true concepts used in mathematical logic.

The valid values are the strings false and true.

Case is ignored by the engine, so for example False and FALSE also valid values. However the server will always return lower case values.

For backwards compatibility with older versions of the engine, the values 0 and 1 are also accepted. The value 0 has the same meaning than false, and 1 has the same meaning than true. Try to avoid using these values, as support for them may be removed in the future.

Integer primitive

Represents the mathematical concept of integer number.

The valid values are finite sequences of decimal digits.

Currently the engine implements this type using a signed 32 bit integer, so the minimum value is -231 (-2147483648) and the maximum value is 231-1 (2147483647).

However, there are some attributes in the system where the range of values possible with 32 bit isn’t enough. In those exceptional cases the engine uses 64 bit integers, in particular for the following attributes:

  • Disk.actual_size

  • Disk.provisioned_size

  • GlusterClient.bytes_read

  • GlusterClient.bytes_written

  • Host.max_scheduling_memory

  • Host.memory

  • HostNic.speed

  • LogicalUnit.size

  • MemoryPolicy.guaranteed

  • NumaNode.memory

  • QuotaStorageLimit.limit

  • StorageDomain.available

  • StorageDomain.used

  • StorageDomain.committed

  • VmBase.memory

For these exception cases the minimum value is -263 (-9223372036854775808) and the maximum value is 263-1 (9223372036854775807).

In the future the integer type will be implemented using unlimited precission integers, so the above limitations and exceptions will eventually disappear.

Decimal primitive

Represents the mathematical concept of real number.

Currently the engine implements this type using 32-bit IEEE 754 single precision floating point numbers.

For some attributes this isn’t enough precision. In those exceptional cases the engine uses 64 bit double precision floating point numbers, in particular for the following attributes:

  • QuotaStorageLimit.usage

  • QuotaStorageLimit.memory_limit

  • QuotaStorageLimit.memory_usage

In the future the decimal type will be implemented using unlimited precision decimal numbers, so the above limitations and exceptions will eventually disappear.

Date primitive

Represents a date and time.

The format returned by the engine is the one described in the XML Schema specification when requesting XML. For example, if you send a request like this to retrieve the XML representation of a virtual machine:

GET /ovirt-engine/api/vms/123
Accept: application/xml

The response body will contain the following XML document:

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <creation_time>2016-09-08T09:53:35.138+02:00</creation_time>
  ...
</vm>

When requesting the JSON representation the engine uses a different, format: an integer containing the number of milliseconds since Jan 1st 1970, also known as epoch time. For example, if you send a request like this to retrieve the JSON representation of a virtual machine:

GET /ovirt-engine/api/vms/123
Accept: application/json

The response body will contain the following JSON document:

{
  "id": "123",
  "href="/ovirt-engine/api/vms/123",
  ...
  "creation_time": 1472564909990,
  ...
}

In both cases, the dates returned by the engine use the time zone configured in the server where it is running. In these examples, the time zone is UTC+2.

Appendix B: Changes in version 4 of the API

This section enumerates the backwards-compatibility breaking changes that have been introduced in and since version 4 of the API.

Changes in API version 4.0 (succeeding version 3.6)

Removed YAML support

The support for YAML has been completely removed.

Renamed complex types

The following XML schema complex types have been renamed:

Version 3 Version 4

API

Api

CPU

Cpu

CPUs

Cpus

CdRom

Cdrom

CdRoms

Cdroms

DNS

Dns

GuestNicConfiguration

NicConfiguration

GuestNicsConfiguration

NicConfigurations

HostNICStates

HostNicStates

HostNIC

HostNic

HostStorage

HostStorages

IO

Io

IP

Ip

IPs

Ips

KSM

Ksm

MAC

Mac

NIC

Nic

PreviewVMs

PreviewVms

QoS

Qos

QoSs

Qoss

RSDL

Rsdl

SELinux

SeLinux

SPM

Spm

SSHPublicKey

SshPublicKey

SSHPublicKeys

SshPublicKeys

SSH

Ssh

SkipIfSDActive

SkipIfSdActive

Slaves

HostNics

Storage

HostStorage

SupportedVersions

Versions

VCpuPin

VcpuPin

VLAN

Vlan

VM

Vm

VMs

Vms

VirtIO_SCSI

VirtioScsi

WatchDog

Watchdog

WatchDogs

Watchdogs

Replaced the Status type with enum types

Currently the status of different objects is reported using the Status type, which contains a state string describing the status and another detail string for additional details. For example, the status of a virtual machine that is paused due to an IO error is currently reported as follows:

<vm>
  ...
  <status>
    <state>paused</state>
    <detail>eio</detail>
  </status>
  ...
</vm>

In version 4 of the API this Status type has been removed and replaced by enum types. When the additional detail string is needed it has been replaced with an additional status_detail attribute. So, for example, the status of the same virtual machine will now be reported as follows:

<vm>
  ...
  <status>paused</status>
  <status_detail>eio</status_detail>
  ...
</vm>

Remove the NIC network and port_mirroring properties

The NIC network and port_mirroring elements have been replaced by the vnic_profile element, so when creating or updating a NIC instead of specifying the network and port mirroring configuration, these are previusly specified creating a vNIC profile:

POST /ovirt-engine/api/vnicprofiles
<vnic_profile>
  <name>myprofile</name>
  <network id="..."/>
  <port_mirroring>true</port_mirroring>
</vnic_profile>

And then the NIC is created or referencing the existing vNIC profile:

PUT /ovirt-engine/api/vms/123/nics/456
<nic>
  <vnic_profile id="/vnicprofiles/...">
</nic>

The old elements and their meaning were preserved for backwards compatibility, but they have now been completely removed.

Note that the network element hasn’t been removed from the XML schema because it is still used by the initialization element, but it will be completely ignored if provided when creating or updating a NIC.

Remove the NIC active property

The NIC active property was replaced by plugged some time ago. It has been completely removed now.

Remove the disk type property

The type property of disks has been removed, but kept in the XML schema and ignored. It has been completely removed now.

Remove the disk size property

The disk size property has been replaced by provisioned_size long ago. It has been completely removed now.

Removed support for pinning a VM to a single host

Before version 3.6 the API had the possibility to pin a VM to a single host, using the placement_policy element of the VM entity:

PUT /ovirt-engine/api/vms/123
<vm>
  <placement_policy>
    <host id="456"/>
  </placement_policy>
<vm>

In version 3.6 this capability was enhanced to support multiple hosts, and to do so a new hosts element was added:

PUT /ovirt-engine/api/vms/123
<vm>
  <placement_policy>
    <hosts>
      <host id="456"/>
      <host id="789"/>
      ...
    </hosts>
  </placement_policy>
<vm>

To preserve backwards compatibility the single host element was preserved. In 4.0 this has been removed, so applications will need to use the hosts element even if when pinning to a single host.

Removed the capabilities.permits element

The list of permits is potentiall different for each cluster level, and it has been added to the version element long ago, but it has been kept into the capabilities element as well, just for backwards compatibility.

In 4.0 it the capabilities service has been completely removed, and replaced by the new clusterlevels service. To find the permits supported by cluster level 4.0 a request like this should be used:

GET /ovirt-engine/api/clusterlevels/4.0

The result will be a document containing the information specific to that cluster level, in particular the set of supported permits:

<cluster_level id="4.0" href="/clusterlevels/4.0">
  ...
  <permits>
    <permit id="1">
      <name>create_vm</name>
      <administrative>false</administrative>
    </permit>
    ...
  </permits>
</cluster_level>

Removed the storage_manager element

The storage_manager element was replaced by the spm element some time ago. The old one was kept for backwards compatibility, but it has been completely removed now.

Removed the data center storage_type element

Data centers used to be associated to a specific storage type (NFS, Fiber Channel, iSCSI, etc) but they have been changed some time so that there are only two types: with local storage and with shared storage. A new local element was introduced to indicate this, and the old storage_type was element was preserved for backwards compatibility. This old element has now been completely removed.

Remove the timezone element

The VM resource used to contain a timezone element to represent the time zone. This element only allowed a string:

<vm>
  <timezone>Europe/Madrid</timezone>
</vm>

This doesn’t allow extension, and as a it was necessary to add the UTC offset, it was replaced with a new structured time_zone element:

<vm>
  <time_zone>
    <name>Europe/Madrid</name>
    <utc_offset>GMT+1</utc_offset>
  </time_zone>
</vm>

The old timezone element was preserved, but it has been completely removed now.

Removed the guest_info element

The guest_info element was used to hold information gathered by the guest agent, like the IP addresses and the fully qualified host name. This information is also available in other places. For example, the IP addresses are available within VM resource:

GET /ovirt-engine/api/vms/123
<vm>
  <guest_info>
    <ips>
      <ip address="192.168.122.30"/>
    </ips>
    <fqdn>myvm.example.com</fqdn>
  </guest_info>
</vm>

And also within the NIC resource, using the newer reported_devices element:

GET /ovirt-engine/api/vms/{vm:id}/nics/{nic:id}
<nic>
  <reported_devices>
    <reported_device>
      <name>eth0</name>
      <mac address="00:1a:4a:b5:4c:94"/>
      <ips>
        <ip address="192.168.1.115" version="v4"/>
        <ip address="fe80::21a:4aff:feb5:4c94" version="v6"/>
        <ip address="::1:21a:4aff:feb5:4c94" version="v6"/>
      </ips>
    </reported_device>
  </reported_devices>
</nic>

In addition this newer reported_devices element provides more complete information, like multiple IP addresses, MAC addresses, etc.

To remove this duplication the guest_info element has been removed.

To support the fully qualified domain name a new fqdn element has been added to the VM resource:

GET /ovirt-engine/api/vms/123
<vm>
  <fqdn>myvm.example.com</fqdn>
</vms>

This will contain the same information that guest_info.fqdn used to contain.

Replaced CPU id attribute with type element

The cpu element used to have an id attribute that indicates the type of CPU:

<cpu id="Intel Nehalem Family">
  <architecture>X86_64</architecture>
  ...
</cpu>

This is in contradiction with the rest of the elements of the API model, where the id attribute is used for opaque identifiers. This id attribute has been replaced with a new type element:

<cpu>
  <type>Intel Nehalem Family</type>
  <architecture>X86_64</architecture>
</cpu>

Use elements instead of attributes in CPU topology

In the past the CPU topology element used attributes for its properties:

<cpu>
  <topology sockets="1" cores="1" threads="1"/>
  ...
</cpu>

This is contrary to the common practice in the API. They have been replaced by inner elements:

<cpu>
  <topology>
    <sockets>1<sockets>
    <cores>1<cores>
    <threads>1<threads>
  </topology>
  ...
</cpu>

Use elements instead of attributes in VCPU pin

In the past the VCPU pin element used attributes for its properties:

<cpu_tune>
  <vcpu_pin vcpu="0" cpu_set="0"/>
</cpu_tune>

This is contrary to the common practice in the API. They have been replaced by inner elements:

<cpu_tune>
  <vcpu_pin>
    <vcpu>0</vcpu>
    <cpu_set>0</cpu_set>
  </vcpu_pin>
</cpu_tune>

Use elements instead of attributes in VCPU pin

In the past the version element used attributes for its properties:

<version major="3" minor="5" ../>

This is contrary to the common practice in the API. They have been replaced by inner elements:

<version>
  <major>3</minor>
  <minor>5</minor>
  ...
</version>

Use elements instead of attributes in memory overcommit

In the past the overcommit element used attributes for its properties:

<memory_policy>
  <overcommit percent="100"/>
  ...
</memory_policy>

This is contrary to the common practice in the API. They have been replaced by inner elements:

<memory_policy>
  <overcommit>
    <percent>100</percent>
  </overcommit>
  ...
</memory_policy>

Use elements instead of attributes in console

In the past the console element used attributes for its properties:

<console enabled="true"/>

This is contrary to the common practice in the API. They have been replaced by inner elements:

<console>
  <enabled>true</enabled>
</console>

Use elements instead of attributes in VIRTIO SCSI

In the past the VIRTIO ISCSI element used attributes for its properties:

<virtio_scsi enabled="true"/>

This is contrary to the common practice in the API. They have been replaced by inner elements:

<virtio_scsi>
  <enabled>true</enabled>
</virtio_scsi>

Use element instead of attribute for power management agent type

The power management type property was represented as an attribute:

<agent type="apc">
  <username>myuser</username>
  ...
</agent>

This is contrary to the common practice in the API. It has been replaced with an inner element:

<agent>
  <type>apc</type>
  <username>myuser</username>
  ...
</agent>

Use elements instead of attributes in power management agent options

In the past the power management agent options element used attributes for its properties:

<options>
  <option name="port" value="22"/>
  <option name="slot" value="5"/>
  ...
</options>

This is contrary to the common practice in the API. They have been replaced with inner elements:

<options>
  <option>
    <name>port</name>
    <value>22</value>
  </option>
  <option>
    <name>slot</name>
    <value>5</value>
  </option>
  ...
</options>

Use elements instead of attributes in IP address:

In the past the IP address element used attributes for its properties:

<ip address="192.168.122.1" netmask="255.255.255.0"/>

This is contrary to the common practice in the API. They have been replaced with inner elements:

<ip>
  <address>192.168.122.1</address>
  <netmask>255.255.255.0</netmask>
</ip>

Use elements instead of attributes in MAC address:

In the past the MAC address element used attributes for its properties:

<mac address="66:f2:c5:5f:bb:8d"/>

This is contrary to the common practice in the API. They have been replaced by inner elements:

<mac>
  <address>66:f2:c5:5f:bb:8d</address>
</mac>

Use elements instead of attributes in boot device:

In the past the boot device element used attributes for its properties:

<boot dev="cdrom"/>

This is contrary to the common practice in the API. They have been replaced by inner elements:

<boot>
  <dev>cdrom</dev>
</boot>

Use element instead of attribute for operating system type

The operating system type property was represented as an attribute:

<os type="other">
  ...
</os>

This is contrary to the common practice in the API. It has been replaced with an inner element:

<os>
  <type>other</type>
  ...
</os>

Removed the force parameter from the request to retrieve a host

The request to retrieve a host used to support a force matrix parameter to indicate that the data of the host should be refreshed (calling VDSM to reload host capabilities and devices) before retrieving it from the database:

GET /ovirt-engine/api/hosts/123;force

This force parameter has been superseded by the host refresh action, but kept for backwards compatibility. It has been completely removed now. Applications that require this functionality should perform two requests, first one to refresh the host:

POST /ovirt-engine/api/hosts/123/refresh
<action/>

And then one to retrieve it, without the force parameter:

GET /ovirt-engine/api/hosts/123

Removed deprecated host power management configuration

The host power management configuration used to be part of the host resource, using embedded configuration elements:

<power_management type="apc">
  <enabled>true</enabled>
  <address>myaddress</address>
  <username>myaddress</username>
  <options>
    <option name="port" value="22/>
    </option name="slot" value="5/>
  </options>
  ...
</power_management>

This has been changed some time ago, in order to support multiple power management agents, introducing a new /hosts/123/fenceagents collection.

The old type attribute, the old address, username and password elements, and the inner agents element directly inside power_management were preserved for backwards compatibility. All these elements have been completely removed, so the only way to query or modify the power management agents is now the /hosts/123/fenceagents sub-collection.

Use multiple boot.devices.device instead of multiple boot

In the past the way to specify the boot sequence when starting a virtual machine was to use multiple boot elements, each containing a dev element. For example, to specify that the virtual machine should first try to boot from CDROM and then from hard disk the following request was used:

POST /ovirt-engine/api/vms/123/start
<action>
  <vm>
    ...
    <boot>
      <dev>cdrom</dev>
    </boot>
    <boot>
      <dev>hd</dev>
    </boot>
  </vm>
</action>

The common practice in other parts of the API is to represent arrays with a wrapper element. In that case that wrapper element could be named boots, but that doesn’t make much sense, as what can have multiple values here is the boot device, not the boot sequence. To fix this inconsistence this has been replaced with a single boot element that can contain multiple devices:

POST /ovirt-engine/api/vms/123/start
<action>
  <vm>
    ...
    <boot>
      <devices>
        <device>cdrom</device>
        <device>hd</device>
      </devices>
    </boot>
  </vm>
</action>

Removed the disks.clone and disks.detach_only elements

These elements aren’t really part of the representation of disks, but parameters of the operations to add and remove virtual machines.

The disks.clone element was used to indicate that the disks of a new virtual machine have to be cloned:

POST /ovirt-engine/api/vms
<vm>
  ...
  <disks>
    <clone>true</clone>
  </disks>
<vm>

This has been now removed, and replaced by a new clone query parameter:

POST /ovirt-engine/api/vms?clone=true
<vm>
  ...
</vm>

The disks.detach_only element was used to indicate that when removing a virtual machine the disks do not have to be removed, but just detached from the virtual machine:

DELETE /ovirt-engine/api/vms/123
<action>
  <vm>
    <disks>
      <detach_only>true</detach_only>
    </disks>
  </vm>
</action>

This has been now removed, and replaced by a new detach_only query parameter:

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

Rename element vmpool to vm_pool

The names of the elements that represent pools of virtual machines used to be vmpool and vmpools. They have been renamed to vm_pool and vm_pools in order to have a consistent correspondence between names of complex types (VmPool and VmPools in this case) and elements.

Use logical_units instead of multiple logical_unit

The logical units that are part of a volume group used to be reported as an unbounded number of logical_unit elements. For example, when reporting the details of a storage domain:

GET /ovirt-engine/api/storagedomains/123
<storage_domain>
  ...
  <storage>
    ...
    <volume_group>
      <logical_unit>
        <!-- First LU -->
      </logical_unit>
      <logical_unit>
        <!-- Second LU -->
      </logical_unit>
      ...
    </volume_group>
  </storage>
</storage_domain>

This is contrary to the usual practice in the API, as list of elements are always wrapped with an element. This has been fixed now, so the list of logical units will be wrapped with the logical_units element:

GET /ovirt-engine/api/storagedomains/123
<storage_domain>
  ...
  <storage>
    ...
    <volume_group>
      <logical_units>
        <logical_unit>
          <!-- First LU -->
        </logical_unit>
        <logical_unit>
          <!-- Second LU -->
        </logical_unit>
        ...
      </logical_units>
    </volume_group>
  </storage>
</storage_domain>

Removed the snapshots.collapse_snapshots element

This element isn’t really part of the representation of snapshots, but a parameter of the operation that imports a virtual machine from an export storage domain:

POST /ovirt-engine/api/storagedomains/123/vms/456/import
<action>
  <vm>
    <snapshots>
      <collapse_snapshots>true</collapse_snapshots>
    </snapshots>
  </vm>
</action>

This has been now removed, and replaced by a new collapse_snapshots query parameter:

POST /ovirt-engine/api/storagedomains/123/vms/456/import?collapse_snapshots=true
<action/>

Renamed storage and host_storage elements

The host storage collection used the storage and host_storage elements and the Storage and HostStorage complex types to report the storage associated to a host:

GET /ovirt-engine/api/hosts/123/storage
<host_storage>
  <storage>
    ...
  </storage>
  <storage>
    ...
  </storage>
  ...
</host_storage>

This doesn’t follow the pattern used in the rest of the API, where the outer element is a plural name and the inner element is the same name but in singular. This has now been changed to use host_storages as the outer element and host_storage as the inner element:

GET /ovirt-engine/api/hosts/123/storage
<host_storages>
  <host_storage>
    ...
  </host_storage>
  <host_storage>
    ...
  </host_storage>
  ...
</host_storage>

Removed the permissions.clone element

This element isn’t really part of the representation of permissions, but a parameter of the operations to create virtual machines or templates:

POST /ovirt-engine/api/vms
<vm>
  <template id="...">
    <permissions>
      <clone>true</clone>
    </permissions>
  </template>
</action>
POST /ovirt-engine/api/templates
<template>
  <vm id="...">
    <permissions>
      <clone>true</clone>
    </permissions>
  </vm>
</template>

This has been now removed, and replaced by a new clone_permissions query parameter:

POST /ovirt-engine/api/vms?clone_permissions=true
<vm>
  <template id="..."/>
</vm>
POST /ovirt-engine/api/templates?clone_permissions=true
<template>
  <vm id="..."/>
</template>

Renamed the random number generator source elements

The random number generator sources used to be reported using a collection of source elements wrapped by an element with a name reflecting its use. For example, the required random number generator sources of a cluster used to be reported as follows:

GET /ovirt-engine/api/clusters/123
<cluster>
  ...
  <required_rng_sources>
    <source>random</source>
  </required_rng_sources>
  ...
</cluster>

And the random number generator sources suported by a host used to be reported as follows:

GET /ovirt-engine/api/hosts/123
<host>
  ...
  <hardware_information>
    <supported_rng_sources>
      <source>random</source>
    </supported_rng_sources>
  </hardware_information>
  ...
</host>

This isn’t consistent with the rest of the API, where collections are wrapped by a name in plural and elements by the same name in singular. This has been now fixed. The required random number generator sources will now be reported as follows:

GET /ovirt-engine/api/clusters/123
<cluster>
  <required_rng_sources>
    <required_rng_sources>random</required_rng_source>
  </required_rng_sources>
  ...
</cluster>

And the random number generator sources supported by a host will be reported as follows:

GET /ovirt-engine/api/hosts/123
<host>
  ...
  <hardware_information>
    <supported_rng_sources>
      <supported_rng_source>random</supported_rng_source>
    </supported_rng_sources>
  </hardware_information>
  ...
</host>

Note the use of required_rng_source and supported_rng_source instead of just source.

Removed the intermediate tag.parent element

The relationship bettween a tag and it’s parent tag used to be represented using an intermedite parent tag, that in turn contains another tag element:

<tag>
  <name>mytag</name>
  <parent>
    <tag id="..." href="..."/>
  </parent>
</tag>

This structure has been simplified so that only one parent element is used now:

<tag>
  <name>mytag</name>
  <parent id="..." href="..."/>
</tag>

Remove scheduling built-in names and thresholds

In the past the specification of scheduling policies for clusters was based in built-in names and thresholds. For example a cluster that used the evenly distributed scheduling policy was represented as follows:

<cluster>
  <name>mycluster</name>
  <scheduling_policy>
    <policy>evenly_distributed</policy>
    <thresholds high="80" duration="120"/>
  </scheduling_policy>
  ...
</cluster>

This mechanism was replaced with a top level /schedulingpolicies collection where scheduling policies can be defined with arbitrary names and properties. For example, the same scheduling policy is represented as follows in that top level collection:

<scheduling_policy>
  <name>evenly_distributed</name>
  <properties>
    <property>
      <name>CpuOverCommitDurationMinutes</name>
      <value>2</value>
    </property>
    <property>
      <name>HighUtilization</name>
      <value>80</value>
    </property>
  </properties>
</scheduling_policy>

The representation of the cluster references the scheduling policy with its identifier:

<cluster>
  <name>mycluster</name>
  <scheduling_policy id="..."/>
  ...
</cluster>

To preserve backwards compatibility the old policy and thresholds elements were preserved. The scheduling policy representation embedded within the cluster was also preserved. All these things have been completely removed now, so the only way to reference a scheduling policy when retrieving, creating or updating a cluster is to reference an existing one using its identifier. For example, when retrieving a cluster only the id (and href) will be populated:

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

When creating or updating a cluster only the id will be accepted.

Removed the bricks.replica_count and bricks.stripe_count elements

These elements aren’t really part of the representation of a collection of bricks, but parameters of the operations to add and remove bricks. They have now been removed, and replaced by new replica_count and stripe_count parameters:

POST .../bricks?replica_count=3&stripe_count=2
DELETE .../bricks?replica_count=3

Renamed the statistics type property to kind

The statistics used to be represented using a type element that indicates the kind of statistic (gauge, counter, etc) and also a type attribute that indicates the type of the values (integer, string, etc):

<statistic>
  <type>GAUGE</type>
  <values type="INTEGER">
    <value>...</value>
    <value>...</value>
    ...
  </values>
</statistic>

To avoid the use of the type concept for both things the first has been replaced by kind, and both kind and type are now elements:

<statistic>
  <kind>gauge</kind>
  <type>integer</type>
  <values>
    <value>...</value>
    <value>...</value>
    ...
  </values>
</statistic>

Use multiple vcpu_pins.vcpu_pin instead of multiple vcpu_pin

In the past the way to specify the virtual to physical CPU pinning of a virtual machine was to use multiple vcpu_pin elements:

<vm>
  <cpu>
    <cpu_tune>
      <vcpu_pin>...</vcpu_pin>
      <vcpu_pin>...</vcpu_pin>
      ...
    </cpu_tune>
  </cpu>
</vm>

In order to conform to the common practice in other parts of the API this has been changed to use a wrapper element, in this case vcpu_pins:

<vm>
  <cpu>
    <cpu_tune>
      <vcpu_pins>
        <vcpu_pin>...</vcpu_pin>
        <vcpu_pin>...</vcpu_pin>
        ...
      </vcpu_pins>
    </cpu_tune>
  </cpu>
</vm>

Use force parameter to force remove a data center

The operation that removes a data center supports a force parameter. In order to use it the DELETE operation used to support an optional action parameter:

DELETE /ovirt-engine/api/datacenters/123
<action>
  <force>true</force>
</action>

This optional action parameter has been replaced with an optional parameter:

DELETE /ovirt-engine/api/datacenters/123?force=true

Use force parameter to force remove a host

The operation that removes a host supports a force parameter. In order to use it the DELETE operation used to support an optional action parameter:

DELETE /ovirt-engine/api/host/123
<action>
  <force>true</force>
</action>

This optional action parameter has been replaced with an optional parameter:

DELETE /ovirt-engine/api/host/123?force=true

Use parameters for force remove storage domain

The operation that removes a storage domain supports the force, destroy and host parameters. These parameters were passed to the DELETE method using the representation of the storage domain as the body:

DELETE /ovirt-engine/api/storagedomains/123
<storage_domain>
  <force>...</force>
  <destroy>...</destroy>
  <host id="...">
    <name>...</name>
  </host>
</storage_domain>

This was problematic, as the HTTP DELETE parameters shouldn’t have a body, and the representation of the storage domain shouldn’t include things that aren’t attributes of the storage domain, rather parameters of the operation.

The force, delete and host attributes have been replaced by equivalent parameters, and the operation doesn’t now accept a body. For example, now the correct way to delete a storage domain with the force parameter is the following:

DELETE /ovirt-engine/api/storagedomain/123?host=myhost&force=true

To delete with the destroy parameter:

DELETE /ovirt-engine/api/storagedomain/123?host=myhost&destroy=true

Use host parameter to remove storage server connection

The operation that removes a storage server connection supports a host parameter. In order to use it the DELETE method used to support an optional action parameter:

DELETE /ovirt-engine/api/storageconnections/123
<action>
  <host id="...">
    <name>...</name>
  </host>
</action>

This optional action parameter has been replaced with an optional parameter:

DELETE /ovirt-engine/api/storageconnections/123?host=myhost

Use force and storage_domain parameters to remove template disks

The operation that removes a template disk supports the force and storage_domain parameters. In order to use it them the DELETE method used to support an optional action parameter:

DELETE /ovirt-engine/api/templates/123/disks/456
<action>
  <force>...</force>
  <storage_domain id="..."/>
</action>

In version 4 of the API this operation has been moved to the new diskattachments collection, and the request body has been replaced with the query parameters force and storage_domain:

DELETE /ovirt-engine/api/templates/123/disksattachments/456?force=true
DELETE /ovirt-engine/api/templates/123/disksattachments/456?storage_domain=123

Do not remove disks via the VM disk API

Removing an entity by deleting /vms/123/disks/456 means removing the relationship between the VM and the disk - i.e., this operation should just detach the disk from the VM. This operation is no longer able to remove disks completely from the system, which was prone to user errors and had unreverseable consequences. To remove a disk, instead use the /disk/456 API:

DELETE /ovirt-engine/api/disks/456

Use force query parameter to force remove a virtual machine

The operation that removes a virtual machine supports a force parameter. In order to use it the DELETE method used to support an optional action parameter:

DELETE /ovirt-engine/api/vms/123
<action>
  <force>true</force>
</action>

This optional action parameter has been replaced with an optional query parameter:

DELETE /ovirt-engine/api/vms/123?force=true

Use POST instead of DELETE to remove multiple bricks

The operation that removes multiple Gluster bricks was implemented using the DELETE method and passing the list of bricks as the body of the request:

DELETE /ovirt-engine/api/clusters/123/glustervolumes/456/bricks
<bricks>
  <bricks id="..."/>
  <bricks id="..."/>
  ...
</bricks>

This is problematic because the DELETE method shouldn’t have a body, so it has been replaced with a new remove action that uses the POST method:

POST /ovirt-engine/api/clusters/123/glustervolumes/456/bricks/remove
<bricks>
  <bricks id="..."/>
  <bricks id="..."/>
  ...
</bricks>

Removed the scheduling_policy.policy element

The element was kept for backward compatibility. Use scheduling_policy.name instead.

POST /ovirt-engine/api/schedulingpolicies
<scheduling_policy>
  ...
  <name>policy_name</name>
  ...
</scheduling_policy>
PUT /ovirt-engine/api/schedulingpolicies/123
<scheduling_policy>
  ...
  <name>policy_name</name>
  ...
</scheduling_policy>

Added snapshot.snapshot_type

Enums are being gradually introduces to the API. Some fields which were string until now, are replaced with an appropriate enum. One such field is vm.type. But this field is inherited by snapshot, and snapshot type is different than vm type. So a new field has been added to snapshot entity: snapshot.snapshot_type.

<snapshot>
  ...
  <snapshot_type>regular|active|stateless|preview</snapshot_type>
  ...
</snapshot>

Removed move action from VM

The deprecated move action of the VM entity has been removed. Instead, you can move inidividual disks.

Moved reported_configurations.in_sync to network_attachment

In version 3 of the API the XML schema type ReportedConfigurations had a in_sync property:

<network_attachment>
  <reported_configurations>
    <in_sync>true</in_sync>
    <reported_configuration>
      ...
    </reported_configuration>
    ...
  </reported_configurations>
</network_attachment>

In the specification mechanism used by version 4 of the API this can’t be expressed, because list types (the list of reported configurations) can’t have attributes. To be able to represent it the attribute has been moved to the enclosing network_attachment:

<network_attachment>
  <in_sync>true</in_sync>
  <reported_configurations>
    <reported_configuration>
      ...
    </reported_configuration>
    ...
  </reported_configurations>
</network_attachment>

Replaced capabilities with clusterlevels

The top level capabilities collection has been replaced by the new clusterlevels collection. This new collection will contain the information that isn’t available in the model, like the list of CPU types available for each cluster level:

GET /ovirt-engine/api/clusterlevels

This will return a list of ClusterLevel objects containing the details for all the cluster levels supported by the system:

<cluster_levels>
  <cluster_level id="3.6" href="/clusterlevels/3.6">
    <cpu_types>
      <cpu_type>
        <name>Intel Nehalem Family</name>
        <level>2</level>
        <architecture>x86_64</architecture>
      </cpu_type>
      ...
    </cpu_types>
    ...
  </cluster_level>
</cluster_levels>

Each specific cluster level has it’s own subresource, identified by the version itself:

GET /ovirt-engine/api/clusterlevels/3.6

This will return the details of that version:

<cluster_level id="3.6" href="/clusterlevels/3.6">
  <cpu_types>
    <cpu_type>
      <name>Intel Nehalem Family</name>
      <level>2</level>
      <architecture>x86_64</architecture>
    </cpu_type>
    ...
  </cpu_types>
  ...
</cluster_level>

Replaced disks with diskattachments

In version 3 of the API virtual machines and templates had a disks collection containing all the information of the disks attached to them. In version 4 of the API these disks collections have been removed and replaced with a new diskattachments collection that will contain only the references to the disk and the attributes that are specific of the relationship between disks and the virtual machine or template that they are attached to: interface and bootable.

To find what disks are attached to a virtual machine, for example, send a request like this:

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

That will return a response like this:

<disk_attachments>
  <disk_attachment href="/vms/123/diskattachments/456" id="456">
    <bootable>false</bootable>
    <interface>virtio</interface>
    <disk href="/disks/456" id="456"/>
    <vm href="/vms/123" id="123"/>
  </disk_attachment>
  ...
<disk_attachments>

To find the rest of the details of the disk, follow the link provided.

Adding disks to a virtual machine or template uses the new disk_attachment element as well: request like this:

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

With the following body if the disk doesn’t exist and you want to create it:

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

Or with the following body if the disk already exists, and you just want to attach it to the virtual machine:

<disk_attachment>
  <bootable>false</bootable>
  <interface>virtio</interface>
  <disk id="456"/>
</disk_attachment>

Take into account that the vm.disks and template.disks attribtes have disk_attachments for all usages. For example, when creating a template the vm.disks element was used to indicate in which storage domain to create the disks of the template. This usage has also been replaced by vm.disk_attachments, so the request to creaate a template with disks in specific storage domains will now look like this:

<template>
  <name>mytemplate</name>
  <vm id="123">
    <disk_attachments>
      <disk_attachment>
        <disk id="456">
          <storage_domains>
            <storage_domain id="789"/>
          </storage_domains>
        </disk>
      </disk_attachment>
      ...
    </disk_attachments>
  </vm>
</template>

Use iscsi_targets element to discover unregistered storage

In version 3 of the API the operation to discover unregistered storage domains used to receive a list of iSCSI targets, using multiple iscsi_target elements:

POST /ovirt-engine/api/hosts/123/unregisteredstoragedomaindiscover
<action>
  <iscsi>
    <address>myiscsiserver</address>
  </iscsi>
  <iscsi_target>iqn.2016-07.com.example:mytarget1</iscsi_target>
  <iscsi_target>iqn.2016-07.com.example:mytarget2</iscsi_target>
</action>

In version 4 of the API all repeating elements, like iscsi_target in this case, are wrapped with another element, iscsi_targets in case. So the same request should now look like this:

POST /ovirt-engine/api/hosts/123/unregisteredstoragedomaindiscover
<action>
  <iscsi>
    <address>myiscsiserver</address>
  </iscsi>
  <iscsi_targets>
    <iscsi_target>iqn.2016-07.com.example:mytarget1</iscsi_target>
    <iscsi_target>iqn.2016-07.com.example:mytarget2</iscsi_target>
  </iscsi_targets>
</action>

Changes in Engine version 4.5

Openstack Volume (Cinder) integration replaced by Managed Block Storage.