Red Hat Summit Red Hat SummitApoyoConsolaDesarrolladoresIniciar una pruebaContacto

Este contenido no está disponible en el idioma seleccionado.

REST API Guide

Red Hat Virtualization 4.1

Using the Red Hat Virtualization REST Application Programming Interface

Red Hat Virtualization Documentation Team

Abstract

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

Chapter 1. Introduction
Copiar enlace

The Red Hat Virtualization Manager provides a Representational State Transfer (REST) API. The API provides software developers and system administrators with control over their Red Hat Virtualization environment outside of the standard web interface. The API is useful for developers and administrators to integrate the functionality of a Red Hat Virtualization environment with custom scripts or external applications that access the API via the standard Hypertext Transfer Protocol (HTTP).

The benefits of the API are:

  • Broad client support - Any programming language, framework, or system with support for HTTP protocol can use the API.
  • Self descriptive - Client applications require minimal knowledge of the virtualization infrastructure, as many details are discovered at runtime.
  • Resource-based model - The resource-based REST model provides a natural way to manage a virtualization platform.

This provides developers and administrators with the ability to:

  • Integrate with enterprise IT systems.
  • Integrate with third-party virtualization software.
  • Perform automated maintenance or error-checking tasks.
  • Automate repetitive tasks in a Red Hat Virtualization environment with scripts.

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

1.1. Representational State Transfer
Copiar enlace

Representational State Transfer (REST) is a design architecture that focuses on resources for a specific service and their representations. A resource representation is a key abstraction of information that corresponds to one specific managed element on a server. A client sends a request to a server element located at a Uniform Resource Identifier (URI) and performs operations with standard HTTP methods, such as GET, POST, PUT, and DELETE. This provides a stateless communication between the client and server where each request acts independently of any other request, and contains all the information necessary to complete the request.

1.2. API Prerequisites
Copiar enlace

Prerequisites for using the Red Hat Virtualization API:

  • A networked installation of Red Hat Virtualization Manager, which includes the API.

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

  • Knowledge of Hypertext Transfer Protocol (HTTP), the protocol used for REST API interactions. The Internet Engineering Task Force provides a Request for Comments (RFC) explaining the Hypertext Transfer Protocol at http://www.ietf.org/rfc/rfc2616.txt.
  • Knowledge of Extensible Markup Language (XML) or JavaScript Object Notation (JSON), which the API uses to construct resource representations. The W3C provides a full specification on XML at http://www.w3.org/TR/xml. ECMA International provide a free publication on JSON at http://www.ecma-international.org.

Chapter 2. Authentication and Security
Copiar enlace

2.1. TLS/SSL Certification
Copiar enlace

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

2.1.1. Obtaining the CA Certificate
Copiar enlace

You can obtain the CA certificate from the Red Hat Virtualization Manager and transfer it to the client machine using one of these methods:

Method 1

The preferred method for obtaining the CA certificate is to use the openssl s_client command line tool to perform a real TLS handshake with the server, and then extract the certificates that it presents. Run a command like this: 

$ openssl s_client \
-connect myengine.example.com:443 \
-showcerts \
< /dev/null

This command will connect to the server and display output similar to the following: 

CONNECTED(00000003)
depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416
verify error:num=19:self signed certificate in certificate chain
---
Certificate chain
 0 s:/C=US/O=Example Inc./CN=myengine.example.com
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
-----END CERTIFICATE-----
 1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----

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

-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----
Important

This is the most reliable method to obtain the CA certificate used by the server. The rest of the methods described here will work in most cases, but they will not obtain the correct CA certificate if it has been manually replaced by the administrator of the server.

Method 2

If you cannot use the openssl s_client method described above, you can instead use a command line tool to download the CA certificate from the Red Hat Virtualization Manager.

Examples of command line tools include curl and wget, both of which are available on multiple platforms.

If using curl: 

$ curl \
--output ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'

If using wget: 

$ wget \
--output-document ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
Method 3

Use a web browser to navigate to the certificate located at: 

https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA

Depending on the chosen browser, the certificate either downloads or imports into the browser’s keystore.

  1. If the browser downloads the certificate: save the file as ca.crt.
  2. If the browser imports the certificate: export it from the browser’s certification options and save it as ca.crt.
Method 4

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

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

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

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

    This creates a certificate file called ca.crt.

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

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

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

2.1.2. Importing a Certificate to a Client
Copiar enlace

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

2.2. Authentication
Copiar enlace

Any user with a Red Hat Virtualization Manager account has access to the API. All requests must be authenticated using either OAuth or basic authentication, as described below.

2.2.1. OAuth Authentication
Copiar enlace

Since version 4.0 of Red Hat Virtualization the preferred authentication mechanism is OAuth 2.0, as described in RFC 6749.

OAuth is a sophisticated protocol, with several mechanisms for obtaining authorization and access tokens. For use with the Red Hat Virtualization API, the only supported one is the Resource Owner Password Credentials Grant, as described in section 4.3 of RFC 6749.

You must first obtain a token, sending the user name and password to the Red Hat Virtualization Manager single sign-on service: 

POST /ovirt-engine/sso/oauth/token HTTP/1.1
Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

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

Expand
Table 2.1. OAuth token request parameters
NameValue

grant_type

password

scope

ovirt-app-api

username

admin@internal

password

mypassword

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

grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
Important

The scope parameter is described as optional in the OAuth RFC, but when using it with the Red Hat Virtualization API it is mandatory, and its value must be ovirt-app-api.

If the user name and password are valid, the Red Hat Virtualization Manager single sign-on service will respond with a JSON document similar to this one: 

{
  "access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
  "token_type": "bearer",
  "scope": "...",
  ...
}

For API authentication purposes, the only relevant name/value pair is the access_token. Do not manipulate this in any way; use it exactly as provided by the SSO service.

Once the token has been obtained, it can be used to perform requests to the API by including it in the HTTP Authorization header, and using the Bearer scheme. For example, to get the list of virtual machines, send a request like this: 

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

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

HTTP/1.1 401 Unauthorized

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

2.2.2. Basic Authentication
Copiar enlace

Important

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

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

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

HTTP/1.1 401 Authorization Required

Request are issued with an Authorization header for the specified realm. Encode an appropriate Red Hat Virtualization Manager domain and user in the supplied credentials with the username@domain:password convention.

The following table shows the process for encoding credentials in Base64.

Expand
Table 2.2. Encoding credentials for API access
ItemValue

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
Important

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

Important

Some Base64 libraries break the result into multiple lines and terminate each line with a newline character. This breaks the header and causes a faulty request. The Authorization header requires the encoded credentials on a single line within the header.

2.2.3. Authentication Sessions
Copiar enlace

The API also provides authentication session support. Send an initial request with authentication details, then send all subsequent requests using a session cookie to authenticate.

2.2.3.1. Requesting an Authenticated Session
Copiar enlace

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


[1] HTTPS is described in RFC 2818 HTTP Over TLS.

Chapter 3. Common concepts
Copiar enlace

3.1. Types
Copiar enlace

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

There are three relevant kinds of types:

Primitive types
Describe simple kinds of objects, like strings or integers.
Enumerated types
Describe lists of valid values like VmStatus or DiskFormat.
Structured types
Describe structured objects, with multiple attributes and links, like Vm or Disk.

3.2. Identified types
Copiar enlace

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:

Expand
AttributeTypeDescription

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.

Important

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

3.3. Objects
Copiar enlace

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

3.4. Collections
Copiar enlace

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

3.5. Representations
Copiar enlace

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

3.5.1. XML representation
Copiar enlace

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

In the XML representation of objects the id and href attributes are the only ones that are represented as XML attributes, the rest are represented as nested XML elements.

3.5.2. JSON representation
Copiar enlace

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

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

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

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

3.6. Services
Copiar enlace

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:

Expand
Method nameHTTP 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 action method used to start a virtual machine (see here) has a vm parameter to describe how the virtual machine should be started, and a use_cloud_init parameter to specify if cloud-init should be used to configure the guest operating system. So the complete request to start virtual machine 123 using cloud-init will look like this when using XML: 

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

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

3.7. Searching
Copiar enlace

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

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

3.7.1. Maximum results parameter
Copiar enlace

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

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

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

3.7.2. Case sensitivity
Copiar enlace

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

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

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

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

3.7.3. Search syntax
Copiar enlace

The search parameters uses the same format as the Red Hat Virtualization query language: 

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

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

Example search queries:

Expand
CollectionCriteriaResult

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 equals sign should be encoded as %3D: 

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

3.7.4. Wildcards
Copiar enlace

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

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

3.7.5. Pagination
Copiar enlace

Some Red Hat Virtualization 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
Note

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
Important

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

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

3.8. Permissions
Copiar enlace

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

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

The response body will look like this: 

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

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

3.9. Handling errors
Copiar enlace

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>

Chapter 4. Quick start example
Copiar enlace

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

  • A networked and configured Red Hat Virtualization installation;
  • An ISO file containing a desired virtual machine operating system to install. This chapter uses CentOS 7 for our installation ISO example; and
  • Red Hat Virtualization’s engine-iso-uploader tool to upload your chosen operating system ISO file.

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

Important

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

Important

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

Note

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

Note

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

4.1. Example: Access API entry point
Copiar enlace

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

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

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

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

Same request, using the curl command: 

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

The result will be an object of type Api: 

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

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

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

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

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

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

4.2. Example: List data centers
Copiar enlace

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

The following request retrieves a representation of the data centers: 

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

Same request, using the curl command: 

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

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

<data_centers>
  <data_center href="/ovirt-engine/api/datacenters/001" id="001">
    <name>Default</name>
    <description>The default Data Center</description>
    <link href="/ovirt-engine/api/datacenters/001/clusters" rel="clusters"/>
    <link href="/ovirt-engine/api/datacenters/001/storagedomains" rel="storagedomains"/>
    ...
    <local>false</local>
    <quota_mode>disabled</quota_mode>
    <status>up</status>
    <supported_versions>
      <version>
        <major>4</major>
        <minor>0</minor>
      </version>
    </supported_versions>
    <version>
      <major>4</major>
      <minor>0</minor>
    </version>
  </data_center>
  ...
</data_centers>

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

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

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

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

4.3. Example: List host clusters
Copiar enlace

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

The following request retrieves a representation of the cluster collection: 

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

Same request, using the curl command: 

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

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

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

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

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

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

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

4.4. Example: List logical networks
Copiar enlace

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

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

The following request retrieves the list of logical networks: 

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

Same request, using the curl command: 

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

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

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

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

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

4.5. Example: List hosts
Copiar enlace

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

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

Same request, using the curl command: 

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

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

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

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

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

4.6. Example: Create NFS data storage
Copiar enlace

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

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

The request should be like this: 

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

And the request body should be like this: 

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

The same request, using the curl command: 

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

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

<storage_domain href="/ovirt-engine/api/storagedomains/005" id="005">
  <name>mydata</name>
  <description>My data</description>
  <available>42949672960</available>
  <committed>0</committed>
  <master>false</master>
  <status>unattached</status>
  <storage>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
    <type>nfs</type>
  </storage>
  <storage_format>v3</storage_format>
  <type>data</type>
  <used>9663676416</used>
</storage_domain>

4.7. Example: Create NFS ISO storage
Copiar enlace

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

The request should be like this: 

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

And the request body should be like this: 

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

The same request, using the curl command: 

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

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

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

4.8. Example: Attach storage domains to data center
Copiar enlace

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

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

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

With a request body like this: 

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

Same request, using the curl command: 

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

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

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

With a request body like this: 

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

Same request, using the curl command: 

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

4.9. Example: Create virtual machine
Copiar enlace

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

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

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

And the request body should be like this: 

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
  <memory>536870912</memory>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
  </os>
</vm>

Same request, using the curl command: 

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

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

<vm href="/ovirt-engine/api/vms/007" id="007">
  <name>myvm</name>
  <link href="/ovirt-engine/api/vms/007/diskattachments" rel="diskattachments"/>
  <link href="/ovirt-engine/api/vms/007/nics" rel="nics"/>
  ...
  <cpu>
    <architecture>x86_64</architecture>
    <topology>
      <cores>1</cores>
      <sockets>1</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
  <memory>1073741824</memory>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
    <type>other</type>
  </os>
  <type>desktop</type>
  <cluster href="/ovirt-engine/api/clusters/002" id="002"/>
  <status>down</status>
  <original_template href="/ovirt-engine/api/templates/000" id="00"/>
  <template href="/ovirt-engine/api/templates/000" id="000"/>
</vm>

4.10. Example: Create a virtual machine NIC
Copiar enlace

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

The request should be like this: 

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

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

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

Same request, using the curl command: 

# curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<nic>
  <name>mynic</name>
  <description>My network interface card</description>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/nics

4.11. Example: Create virtual machine disk
Copiar enlace

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

The request should be like this: 

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

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

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

Same request, using the curl command: 

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

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

4.12. Example: Attach ISO image to virtual machine
Copiar enlace

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

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

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

GET /ovirt-engine/api/storagedomains/006/files HTTP/1.1
Accept: application/xml

Same request, using the curl command: 

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

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

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

An API user attaches the CentOS-7-x86_64-Minimal.iso to our example virtual machine. Attaching an ISO image is equivalent to using the Change CD button in the administration or user portal applications.

The request should be like this: 

PUT /ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

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

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

Same request, using the curl command: 

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

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

4.13. Example: Start the virtual machine
Copiar enlace

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

The request should be like this: 

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

The request body should be like this: 

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

Same request, using the curl command: 

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

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

Chapter 5. Requests
Copiar enlace

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

Chapter 6. Services
Copiar enlace

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

6.1. AffinityGroup
Copiar enlace

This service manages a single affinity group.

Expand
Table 6.1. Methods summary
NameSummary

get

Retrieve the affinity group details.

remove

Remove the affinity group.

update

Update the affinity group.

6.1.1. get GET
Copiar enlace

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>
Expand
Table 6.2. Parameters summary
NameTypeDirectionSummary

group

AffinityGroup

Out

The affinity group.

6.1.2. remove DELETE
Copiar enlace

Remove the affinity group. 

DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456
Expand
Table 6.3. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.1.3. update PUT
Copiar enlace

Update the affinity group.

Expand
Table 6.4. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

group

AffinityGroup

In/Out

The affinity group.

6.2. AffinityGroupVm
Copiar enlace

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

Expand
Table 6.5. Methods summary
NameSummary

remove

Remove this virtual machine from the affinity group.

6.2.1. remove DELETE
Copiar enlace

Remove this virtual machine from the affinity group.

Expand
Table 6.6. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.3. AffinityGroupVms
Copiar enlace

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

Expand
Table 6.7. Methods summary
NameSummary

add

Add a virtual machine to the affinity group.

list

List all virtual machines assigned to this affinity group.

6.3.1. add POST
Copiar enlace

Add a virtual machine to the affinity group.

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

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

With the following body: 

<vm id="000-000"/>
Expand
Table 6.8. Parameters summary
NameTypeDirectionSummary

vm

Vm

In/Out

 

6.3.2. list GET
Copiar enlace

List all virtual machines assigned to this affinity group.

Expand
Table 6.9. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of virtual machines to return.

vms

Vm[]

Out

 
6.3.2.1. max
Copiar enlace

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

6.4. AffinityGroups
Copiar enlace

The affinity groups service manages virtual machine relationships and dependencies.

Expand
Table 6.10. Methods summary
NameSummary

add

Create a new affinity group.

list

List existing affinity groups.

6.4.1. add POST
Copiar enlace

Create a new affinity group.

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

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

And use the following example in its body: 

<affinity_group>
  <name>AF_GROUP_001</name>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
Expand
Table 6.11. Parameters summary
NameTypeDirectionSummary

group

AffinityGroup

In/Out

The affinity group object to create.

6.4.2. list GET
Copiar enlace

List existing affinity groups.

Expand
Table 6.12. Parameters summary
NameTypeDirectionSummary

groups

AffinityGroup[]

Out

The list of existing affinity groups.

max

Integer

In

Sets the maximum number of affinity groups to return.

6.4.2.1. max
Copiar enlace

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

6.5. AffinityLabel
Copiar enlace

The details of a single affinity label.

Expand
Table 6.13. Methods summary
NameSummary

get

Retrieves the details of a label.

remove

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

update

Updates a label.

6.5.1. get GET
Copiar enlace

Retrieves the details of a label.

Expand
Table 6.14. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

Out

 

6.5.2. remove DELETE
Copiar enlace

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

6.5.3. update PUT
Copiar enlace

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

Expand
Table 6.15. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.6. AffinityLabelHost
Copiar enlace

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

Expand
Table 6.16. Methods summary
NameSummary

get

Retrieves details about a host that has this label assigned.

remove

Remove a label from a host.

6.6.1. get GET
Copiar enlace

Retrieves details about a host that has this label assigned.

Expand
Table 6.17. Parameters summary
NameTypeDirectionSummary

host

Host

Out

 

6.6.2. remove DELETE
Copiar enlace

Remove a label from a host.

6.7. AffinityLabelHosts
Copiar enlace

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

Expand
Table 6.18. Methods summary
NameSummary

add

Add a label to a host.

list

List all hosts with the label.

6.7.1. add POST
Copiar enlace

Add a label to a host.

Expand
Table 6.19. Parameters summary
NameTypeDirectionSummary

host

Host

In/Out

 

6.7.2. list GET
Copiar enlace

List all hosts with the label.

Expand
Table 6.20. Parameters summary
NameTypeDirectionSummary

hosts

Host[]

Out

 

6.8. AffinityLabelVm
Copiar enlace

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

Expand
Table 6.21. Methods summary
NameSummary

get

Retrieves details about a vm that has this label assigned.

remove

Remove a label from a vm.

6.8.1. get GET
Copiar enlace

Retrieves details about a vm that has this label assigned.

Expand
Table 6.22. Parameters summary
NameTypeDirectionSummary

vm

Vm

Out

 

6.8.2. remove DELETE
Copiar enlace

Remove a label from a vm.

6.9. AffinityLabelVms
Copiar enlace

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

Expand
Table 6.23. Methods summary
NameSummary

add

Add a label to a vm.

list

List all vms with the label.

6.9.1. add POST
Copiar enlace

Add a label to a vm.

Expand
Table 6.24. Parameters summary
NameTypeDirectionSummary

vm

Vm

In/Out

 

6.9.2. list GET
Copiar enlace

List all vms with the label.

Expand
Table 6.25. Parameters summary
NameTypeDirectionSummary

vms

Vm[]

Out

 

6.10. AffinityLabels
Copiar enlace

Manages the affinity labels available in the system.

Expand
Table 6.26. Methods summary
NameSummary

add

Creates a new label.

list

Lists all labels present in the system.

6.10.1. add POST
Copiar enlace

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

Expand
Table 6.27. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.10.2. list GET
Copiar enlace

Lists all labels present in the system.

Expand
Table 6.28. Parameters summary
NameTypeDirectionSummary

labels

AffinityLabel[]

Out

 

max

Integer

In

Sets the maximum number of labels to return.

6.10.2.1. max
Copiar enlace

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

6.11. AssignedAffinityLabel
Copiar enlace

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

Expand
Table 6.29. Methods summary
NameSummary

get

Retrieves details about the attached label.

remove

Removes the label from an entity.

6.11.1. get GET
Copiar enlace

Retrieves details about the attached label.

Expand
Table 6.30. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

Out

 

6.11.2. remove DELETE
Copiar enlace

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

6.12. AssignedAffinityLabels
Copiar enlace

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

Expand
Table 6.31. Methods summary
NameSummary

add

Attaches a label to an entity.

list

Lists all labels that are attached to an entity.

6.12.1. add POST
Copiar enlace

Attaches a label to an entity.

Expand
Table 6.32. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.12.2. list GET
Copiar enlace

Lists all labels that are attached to an entity.

Expand
Table 6.33. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel[]

Out

 

6.13. AssignedCpuProfile
Copiar enlace

Expand
Table 6.34. Methods summary
NameSummary

get

 

remove

 

6.13.1. get GET
Copiar enlace

Expand
Table 6.35. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

Out

 

6.13.2. remove DELETE
Copiar enlace

Expand
Table 6.36. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.14. AssignedCpuProfiles
Copiar enlace

Expand
Table 6.37. Methods summary
NameSummary

add

 

list

 

6.14.1. add POST
Copiar enlace

Expand
Table 6.38. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

6.14.2. list GET
Copiar enlace

Expand
Table 6.39. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

CpuProfile[]

Out

 
6.14.2.1. max
Copiar enlace

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

6.15. AssignedDiskProfile
Copiar enlace

Expand
Table 6.40. Methods summary
NameSummary

get

 

remove

 

6.15.1. get GET
Copiar enlace

Expand
Table 6.41. Parameters summary
NameTypeDirectionSummary

disk_profile

DiskProfile

Out

 

6.15.2. remove DELETE
Copiar enlace

Expand
Table 6.42. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.16. AssignedDiskProfiles
Copiar enlace

Expand
Table 6.43. Methods summary
NameSummary

add

 

list

 

6.16.1. add POST
Copiar enlace

Expand
Table 6.44. Parameters summary
NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

6.16.2. list GET
Copiar enlace

Expand
Table 6.45. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

DiskProfile[]

Out

 
6.16.2.1. max
Copiar enlace

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

6.17. AssignedPermissions
Copiar enlace

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

Expand
Table 6.46. Methods summary
NameSummary

add

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

list

List all the permissions of the specific entity.

6.17.1. add POST
Copiar enlace

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>
Expand
Table 6.47. Parameters summary
NameTypeDirectionSummary

permission

Permission

In/Out

The permission.

6.17.2. list GET
Copiar enlace

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>
Expand
Table 6.48. Parameters summary
NameTypeDirectionSummary

permissions

Permission[]

Out

The list of permissions.

6.18. AssignedRoles
Copiar enlace

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

Expand
Table 6.49. Methods summary
NameSummary

list

 

6.18.1. list GET
Copiar enlace

Expand
Table 6.50. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out

 
6.18.1.1. max
Copiar enlace

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

6.19. AssignedTag
Copiar enlace

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

Expand
Table 6.51. Methods summary
NameSummary

get

Gets the information about the assigned tag.

remove

Unassign tag from specific entity in the system.

6.19.1. get GET
Copiar enlace

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>
Expand
Table 6.52. Parameters summary
NameTypeDirectionSummary

tag

Tag

Out

The assigned tag.

6.19.2. remove DELETE
Copiar enlace

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
Expand
Table 6.53. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.20. AssignedTags
Copiar enlace

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

Expand
Table 6.54. Methods summary
NameSummary

add

Assign tag to specific entity in the system.

list

List all tags assigned to the specific entity.

6.20.1. add POST
Copiar enlace

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>
Expand
Table 6.55. Parameters summary
NameTypeDirectionSummary

tag

Tag

In/Out

The assigned tag.

6.20.2. list GET
Copiar enlace

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>
Expand
Table 6.56. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

The list of assigned tags.

6.20.2.1. max
Copiar enlace

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

6.21. AssignedVnicProfile
Copiar enlace

Expand
Table 6.57. Methods summary
NameSummary

get

 

remove

 

6.21.1. get GET
Copiar enlace

Expand
Table 6.58. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

Out

 

6.21.2. remove DELETE
Copiar enlace

Expand
Table 6.59. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.22. AssignedVnicProfiles
Copiar enlace

Expand
Table 6.60. Methods summary
NameSummary

add

 

list

 

6.22.1. add POST
Copiar enlace

Expand
Table 6.61. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

In/Out

 

6.22.2. list GET
Copiar enlace

Expand
Table 6.62. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

Out

 
6.22.2.1. max
Copiar enlace

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

6.23. AttachedStorageDomain
Copiar enlace

Expand
Table 6.63. Methods summary
NameSummary

activate

This operation activates an attached storage domain.

deactivate

This operation deactivates an attached storage domain.

get

 

remove

 

6.23.1. activate POST
Copiar enlace

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/>
Expand
Table 6.64. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.23.2. deactivate POST
Copiar enlace

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

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

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

<action/>
Expand
Table 6.65. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

6.23.3. get GET
Copiar enlace

Expand
Table 6.66. Parameters summary
NameTypeDirectionSummary

storage_domain

StorageDomain

Out

 

6.23.4. remove DELETE
Copiar enlace

Expand
Table 6.67. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.24. AttachedStorageDomains
Copiar enlace

Expand
Table 6.68. Methods summary
NameSummary

add

 

list

 

6.24.1. add POST
Copiar enlace

Expand
Table 6.69. Parameters summary
NameTypeDirectionSummary

storage_domain

StorageDomain

In/Out

 

6.24.2. list GET
Copiar enlace

Expand
Table 6.70. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of storage domains to return.

storage_domains

StorageDomain[]

Out

 
6.24.2.1. max
Copiar enlace

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

6.25. Balance
Copiar enlace

Expand
Table 6.71. Methods summary
NameSummary

get

 

remove

 

6.25.1. get GET
Copiar enlace

Expand
Table 6.72. Parameters summary
NameTypeDirectionSummary

balance

Balance

Out

 

filter

Boolean

In

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

6.25.2. remove DELETE
Copiar enlace

Expand
Table 6.73. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.26. Balances
Copiar enlace

Expand
Table 6.74. Methods summary
NameSummary

add

 

list

 

6.26.1. add POST
Copiar enlace

Expand
Table 6.75. Parameters summary
NameTypeDirectionSummary

balance

Balance

In/Out

 

6.26.2. list GET
Copiar enlace

Expand
Table 6.76. Parameters summary
NameTypeDirectionSummary

balances

Balance[]

Out

 

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of balances to return.

6.26.2.1. max
Copiar enlace

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

6.27. Bookmark
Copiar enlace

A service to manage a bookmark.

Expand
Table 6.77. Methods summary
NameSummary

get

Get a bookmark.

remove

Remove a bookmark.

update

Update a bookmark.

6.27.1. get GET
Copiar enlace

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>
Expand
Table 6.78. Parameters summary
NameTypeDirectionSummary

bookmark

Bookmark

Out

The requested bookmark.

6.27.2. remove DELETE
Copiar enlace

Remove a bookmark.

An example for removing a bookmark: 

DELETE /ovirt-engine/api/bookmarks/123
Expand
Table 6.79. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.27.3. update PUT
Copiar enlace

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>
Expand
Table 6.80. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bookmark

Bookmark

In/Out

The updated bookmark.

6.28. Bookmarks
Copiar enlace

A service to manage bookmarks.

Expand
Table 6.81. Methods summary
NameSummary

add

Adding a new bookmark.

list

Listing all the available bookmarks.

6.28.1. add POST
Copiar enlace

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>
Expand
Table 6.82. Parameters summary
NameTypeDirectionSummary

bookmark

Bookmark

In/Out

The added bookmark.

6.28.2. list GET
Copiar enlace

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>
Expand
Table 6.83. Parameters summary
NameTypeDirectionSummary

bookmarks

Bookmark[]

Out

The list of available bookmarks.

max

Integer

In

Sets the maximum number of bookmarks to return.

6.28.2.1. max
Copiar enlace

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

6.29. Cluster
Copiar enlace

A service to manage specific cluster.

Expand
Table 6.84. Methods summary
NameSummary

get

Get information about the cluster.

remove

Removes cluster from the system.

resetemulatedmachine

 

update

Updates information about the cluster.

6.29.1. get GET
Copiar enlace

Get information about the cluster.

An example of getting a cluster: 

GET /ovirt-engine/api/clusters/123
 
<cluster href="/ovirt-engine/api/clusters/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/clusters/123/resetemulatedmachine" rel="resetemulatedmachine"/>
  </actions>
  <name>Default</name>
  <description>The default server cluster</description>
  <link href="/ovirt-engine/api/clusters/123/networks" rel="networks"/>
  <link href="/ovirt-engine/api/clusters/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/clusters/123/glustervolumes" rel="glustervolumes"/>
  <link href="/ovirt-engine/api/clusters/123/glusterhooks" rel="glusterhooks"/>
  <link href="/ovirt-engine/api/clusters/123/affinitygroups" rel="affinitygroups"/>
  <link href="/ovirt-engine/api/clusters/123/cpuprofiles" rel="cpuprofiles"/>
  <ballooning_enabled>false</ballooning_enabled>
  <cpu>
    <architecture>x86_64</architecture>
    <type>Intel Penryn Family</type>
  </cpu>
  <error_handling>
    <on_error>migrate</on_error>
  </error_handling>
  <fencing_policy>
    <enabled>true</enabled>
    <skip_if_connectivity_broken>
      <enabled>false</enabled>
      <threshold>50</threshold>
    </skip_if_connectivity_broken>
    <skip_if_sd_active>
      <enabled>false</enabled>
    </skip_if_sd_active>
  </fencing_policy>
  <gluster_service>false</gluster_service>
  <ha_reservation>false</ha_reservation>
  <ksm>
    <enabled>true</enabled>
    <merge_across_nodes>true</merge_across_nodes>
  </ksm>
  <maintenance_reason_required>false</maintenance_reason_required>
  <memory_policy>
    <over_commit>
      <percent>100</percent>
    </over_commit>
    <transparent_hugepages>
      <enabled>true</enabled>
    </transparent_hugepages>
  </memory_policy>
  <migration>
    <auto_converge>inherit</auto_converge>
    <bandwidth>
      <assignment_method>auto</assignment_method>
    </bandwidth>
    <compressed>inherit</compressed>
  </migration>
  <optional_reason>false</optional_reason>
  <required_rng_sources>
    <required_rng_source>random</required_rng_source>
  </required_rng_sources>
  <scheduling_policy href="/ovirt-engine/api/schedulingpolicies/456" id="456"/>
  <threads_as_cores>false</threads_as_cores>
  <trusted_service>false</trusted_service>
  <tunnel_migration>false</tunnel_migration>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  <virt_service>true</virt_service>
  <data_center href="/ovirt-engine/api/datacenters/111" id="111"/>
</cluster>
Expand
Table 6.85. Parameters summary
NameTypeDirectionSummary

cluster

Cluster

Out

 

filter

Boolean

In

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

6.29.2. remove DELETE
Copiar enlace

Removes cluster from the system. 

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
Expand
Table 6.86. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.29.3. resetemulatedmachine POST
Copiar enlace

Expand
Table 6.87. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

6.29.4. update PUT
Copiar enlace

Updates information about the cluster.

Only specified fields are updated, others remain unchanged.

E.g. update cluster’s CPU: 

PUT /ovirt-engine/api/clusters/123

With request body like: 

<cluster>
  <cpu>
    <type>Intel Haswell-noTSX Family</type>
  </cpu>
</cluster>
Expand
Table 6.88. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

cluster

Cluster

In/Out

 

6.30. ClusterLevel
Copiar enlace

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

Expand
Table 6.89. Methods summary
NameSummary

get

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

6.30.1. get GET
Copiar enlace

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

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

GET /ovirt-engine/api/clusterlevels/3.6

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

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

level

ClusterLevel

Out

Retreived cluster level.

6.31. ClusterLevels
Copiar enlace

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.

Expand
Table 6.91. Methods summary
NameSummary

list

Lists the cluster levels supported by the system.

6.31.1. list GET
Copiar enlace

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>
Expand
Table 6.92. Parameters summary
NameTypeDirectionSummary

levels

ClusterLevel[]

Out

Retrieved cluster levels.

6.32. ClusterNetwork
Copiar enlace

A service to manage a specific cluster network.

Expand
Table 6.93. Methods summary
NameSummary

get

Retrieves the cluster network details.

remove

Unassigns the network from a cluster.

update

Updates the network in the cluster.

6.32.1. get GET
Copiar enlace

Retrieves the cluster network details.

Expand
Table 6.94. Parameters summary
NameTypeDirectionSummary

network

Network

Out

The cluster network.

6.32.2. remove DELETE
Copiar enlace

Unassigns the network from a cluster.

6.32.3. update PUT
Copiar enlace

Updates the network in the cluster.

Expand
Table 6.95. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The cluster network.

6.33. ClusterNetworks
Copiar enlace

A service to manage cluster networks.

Expand
Table 6.96. Methods summary
NameSummary

add

Assigns the network to a cluster.

list

Lists the networks that are assigned to the cluster.

6.33.1. add POST
Copiar enlace

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" />
Expand
Table 6.97. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The network object to be assigned to the cluster.

6.33.2. list GET
Copiar enlace

Lists the networks that are assigned to the cluster.

Expand
Table 6.98. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

The list of networks that are assigned to the cluster.

6.33.2.1. max
Copiar enlace

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

6.34. Clusters
Copiar enlace

A service to manage clusters.

Expand
Table 6.99. Methods summary
NameSummary

add

Creates a new cluster.

list

 

6.34.1. add POST
Copiar enlace

Creates a new cluster.

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

POST /ovirt-engine/api/clusters

With a request body like this: 

<cluster>
  <name>mycluster</name>
  <cpu>
    <type>Intel Penryn Family</type>
  </cpu>
  <data_center id="123"/>
</cluster>
Expand
Table 6.100. Parameters summary
NameTypeDirectionSummary

cluster

Cluster

In/Out

 

6.34.2. list GET
Copiar enlace

Expand
Table 6.101. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

clusters

Cluster[]

Out

 

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of clusters to return.

search

String

In

A query string used to restrict the returned clusters.

6.34.2.1. case_sensitive
Copiar enlace

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.

6.34.2.2. max
Copiar enlace

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

6.35. Copyable
Copiar enlace

Expand
Table 6.102. Methods summary
NameSummary

copy

 

6.35.1. copy POST
Copiar enlace

Expand
Table 6.103. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

6.36. CpuProfile
Copiar enlace

Expand
Table 6.104. Methods summary
NameSummary

get

 

remove

 

update

 

6.36.1. get GET
Copiar enlace

Expand
Table 6.105. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

Out

 

6.36.2. remove DELETE
Copiar enlace

Expand
Table 6.106. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.36.3. update PUT
Copiar enlace

Expand
Table 6.107. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

CpuProfile

In/Out

 

6.37. CpuProfiles
Copiar enlace

Expand
Table 6.108. Methods summary
NameSummary

add

 

list

 

6.37.1. add POST
Copiar enlace

Expand
Table 6.109. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

6.37.2. list GET
Copiar enlace

Expand
Table 6.110. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profile

CpuProfile[]

Out

 
6.37.2.1. max
Copiar enlace

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

6.38. DataCenter
Copiar enlace

A service to manage a data center.

Expand
Table 6.111. Methods summary
NameSummary

get

Get a data center.

remove

Removes the data center.

update

Updates the data center.

6.38.1. get GET
Copiar enlace

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>
Expand
Table 6.112. Parameters summary
NameTypeDirectionSummary

data_center

DataCenter

Out

 

filter

Boolean

In

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

6.38.2. remove DELETE
Copiar enlace

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.

Expand
Table 6.113. Parameters summary
NameTypeDirectionSummary

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.

6.38.2.1. force
Copiar enlace

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

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

6.38.3. update PUT
Copiar enlace

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>
Expand
Table 6.114. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

data_center

DataCenter

In/Out

The data center that is being updated.

6.39. DataCenterNetwork
Copiar enlace

A service to manage a specific data center network.

Expand
Table 6.115. Methods summary
NameSummary

get

Retrieves the data center network details.

remove

Removes the network.

update

Updates the network in the data center.

6.39.1. get GET
Copiar enlace

Retrieves the data center network details.

Expand
Table 6.116. Parameters summary
NameTypeDirectionSummary

network

Network

Out

The data center network.

6.39.2. remove DELETE
Copiar enlace

Removes the network.

6.39.3. update PUT
Copiar enlace

Updates the network in the data center.

Expand
Table 6.117. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The data center network.

6.40. DataCenterNetworks
Copiar enlace

A service to manage data center networks.

Expand
Table 6.118. Methods summary
NameSummary

add

Create a new network in a data center.

list

Lists networks in the data center.

6.40.1. add POST
Copiar enlace

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>
Expand
Table 6.119. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The network object to be created in the data center.

6.40.2. list GET
Copiar enlace

Lists networks in the data center.

Expand
Table 6.120. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

The list of networks which are in the data center.

6.40.2.1. max
Copiar enlace

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

6.41. DataCenters
Copiar enlace

A service to manage data centers.

Expand
Table 6.121. Methods summary
NameSummary

add

Creates a new data center.

list

Lists the data centers.

6.41.1. add POST
Copiar enlace

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>
Expand
Table 6.122. Parameters summary
NameTypeDirectionSummary

data_center

DataCenter

In/Out

The data center that is being added.

6.41.2. list GET
Copiar enlace

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.

Expand
Table 6.123. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

data_centers

DataCenter[]

Out

 

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of data centers to return.

search

String

In

A query string used to restrict the returned data centers.

6.41.2.1. case_sensitive
Copiar enlace

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.

6.41.2.2. max
Copiar enlace

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

6.42. Disk
Copiar enlace

Manages a single disk.

Expand
Table 6.124. Methods summary
NameSummary

copy

This operation copies a disk to the specified storage domain.

export

 

get

 

move

Moves a disk to another storage domain.

remove

 

sparsify

Sparsify the disk.

6.42.1. copy POST
Copiar enlace

This operation copies a disk to the specified storage domain.

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

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

With a request body like this: 

<action>
  <storage_domain id="456"/>
  <disk>
    <name>mydisk</name>
  </disk>
</action>
Expand
Table 6.125. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

disk

Disk

In

 

filter

Boolean

In

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

storage_domain

StorageDomain

In

 

6.42.2. export POST
Copiar enlace

Expand
Table 6.126. Parameters summary
NameTypeDirectionSummary

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

 

6.42.3. get GET
Copiar enlace

Expand
Table 6.127. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.42.4. move POST
Copiar enlace

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>
Expand
Table 6.128. Parameters summary
NameTypeDirectionSummary

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

 

6.42.5. remove DELETE
Copiar enlace

Expand
Table 6.129. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.42.6. sparsify POST
Copiar enlace

Sparsify the disk.

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

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

6.43. DiskAttachment
Copiar enlace

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

Expand
Table 6.130. Methods summary
NameSummary

get

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

remove

Removes the disk attachment.

update

Update the disk attachment and the disk properties within it.

6.43.1. get GET
Copiar enlace

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>
Expand
Table 6.131. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

Out

 

6.43.2. remove DELETE
Copiar enlace

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
Expand
Table 6.132. Parameters summary
NameTypeDirectionSummary

detach_only

Boolean

In

Indicates if the disk should only be detached from the virtual machine, but not removed from the system.

6.43.2.1. detach_only
Copiar enlace

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

6.43.3. update PUT
Copiar enlace

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>
Expand
Table 6.133. Parameters summary
NameTypeDirectionSummary

disk_attachment

DiskAttachment

In/Out

 

6.44. DiskAttachments
Copiar enlace

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.

Expand
Table 6.134. Methods summary
NameSummary

add

Adds a new disk attachment to the virtual machine.

list

List the disk that are attached to the virtual machine.

6.44.1. add POST
Copiar enlace

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
Important

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

Expand
Table 6.135. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

In/Out

 

6.44.2. list GET
Copiar enlace

List the disk that are attached to the virtual machine.

Expand
Table 6.136. Parameters summary
NameTypeDirectionSummary

attachments

DiskAttachment[]

Out

 

6.45. DiskProfile
Copiar enlace

Expand
Table 6.137. Methods summary
NameSummary

get

 

remove

 

update

 

6.45.1. get GET
Copiar enlace

Expand
Table 6.138. Parameters summary
NameTypeDirectionSummary

profile

DiskProfile

Out

 

6.45.2. remove DELETE
Copiar enlace

Expand
Table 6.139. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.45.3. update PUT
Copiar enlace

Expand
Table 6.140. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

DiskProfile

In/Out

 

6.46. DiskProfiles
Copiar enlace

Expand
Table 6.141. Methods summary
NameSummary

add

 

list

 

6.46.1. add POST
Copiar enlace

Expand
Table 6.142. Parameters summary
NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

6.46.2. list GET
Copiar enlace

Expand
Table 6.143. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profile

DiskProfile[]

Out

 
6.46.2.1. max
Copiar enlace

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

6.47. DiskSnapshot
Copiar enlace

Expand
Table 6.144. Methods summary
NameSummary

get

 

remove

 

6.47.1. get GET
Copiar enlace

Expand
Table 6.145. Parameters summary
NameTypeDirectionSummary

snapshot

DiskSnapshot

Out

 

6.47.2. remove DELETE
Copiar enlace

Expand
Table 6.146. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.48. DiskSnapshots
Copiar enlace

Expand
Table 6.147. Methods summary
NameSummary

list

 

6.48.1. list GET
Copiar enlace

Expand
Table 6.148. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

DiskSnapshot[]

Out

 
6.48.1.1. max
Copiar enlace

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

6.49. Disks
Copiar enlace

Manages the collection of disks available in the system.

Expand
Table 6.149. Methods summary
NameSummary

add

Adds a new floating disk.

list

Get list of disks.

6.49.1. add POST
Copiar enlace

Adds a new floating disk.

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

Adding a new image disk:

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

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

POST /ovirt-engine/api/disks

With a request body as follows: 

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

Adding a new direct LUN disk:

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

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

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

POST /ovirt-engine/api/disks

With a request body as follows: 

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

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

Adding a new Cinder disk:

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

POST /ovirt-engine/api/disks

With a request body as follows: 

<disk>
  <openstack_volume_type>
    <name>myceph</name>
  </openstack_volume_type>
  <storage_domains>
    <storage_domain>
      <name>cinderDomain</name>
    </storage_domain>
  </storage_domains>
  <provisioned_size>1073741824</provisioned_size>
  <interface>virtio</interface>
  <format>raw</format>
</disk>
Expand
Table 6.150. Parameters summary
NameTypeDirectionSummary

disk

Disk

In/Out

The disk.

6.49.2. list GET
Copiar enlace

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>
Expand
Table 6.151. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

disks

Disk[]

Out

List of retrieved disks.

max

Integer

In

Sets the maximum number of disks to return.

search

String

In

A query string used to restrict the returned disks.

unregistered

Boolean

In

Indicates whether to retrieve a list of registered or unregistered disks in the storage domain.

6.49.2.1. case_sensitive
Copiar enlace

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.

6.49.2.2. max
Copiar enlace

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

6.49.2.3. unregistered
Copiar enlace

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.

Important

This parameter only applies to the disks sub-collection of attached storage domains, it does not apply to the top level disks collection.

6.50. Domain
Copiar enlace

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

Expand
Table 6.152. Methods summary
NameSummary

get

Gets the authentication domain information.

6.50.1. get GET
Copiar enlace

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>
Expand
Table 6.153. Parameters summary
NameTypeDirectionSummary

domain

Domain

Out

The authentication domain.

6.51. DomainGroup
Copiar enlace

Expand
Table 6.154. Methods summary
NameSummary

get

 

6.51.1. get GET
Copiar enlace

Expand
Table 6.155. Parameters summary
NameTypeDirectionSummary

get

Group

Out

 

6.52. DomainGroups
Copiar enlace

Expand
Table 6.156. Methods summary
NameSummary

list

 

6.52.1. list GET
Copiar enlace

Expand
Table 6.157. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

groups

Group[]

Out

 

max

Integer

In

Sets the maximum number of groups to return.

search

String

In

A query string used to restrict the returned groups.

6.52.1.1. case_sensitive
Copiar enlace

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.

6.52.1.2. max
Copiar enlace

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

6.53. DomainUser
Copiar enlace

A service to view a domain user in the system.

Expand
Table 6.158. Methods summary
NameSummary

get

Gets the domain user information.

6.53.1. get GET
Copiar enlace

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>
Expand
Table 6.159. Parameters summary
NameTypeDirectionSummary

user

User

Out

The domain user.

6.54. DomainUsers
Copiar enlace

A service to list all domain users in the system.

Expand
Table 6.160. Methods summary
NameSummary

list

List all the users in the domain.

6.54.1. list GET
Copiar enlace

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>
Expand
Table 6.161. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

max

Integer

In

Sets the maximum number of users to return.

search

String

In

A query string used to restrict the returned users.

users

User[]

Out

The list of users in the domain.

6.54.1.1. case_sensitive
Copiar enlace

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.

6.54.1.2. max
Copiar enlace

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

6.55. Domains
Copiar enlace

A service to list all authentication domains in the system.

Expand
Table 6.162. Methods summary
NameSummary

list

List all the authentication domains in the system.

6.55.1. list GET
Copiar enlace

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>
Expand
Table 6.163. Parameters summary
NameTypeDirectionSummary

domains

Domain[]

Out

The list of domains.

max

Integer

In

Sets the maximum number of domains to return.

6.55.1.1. max
Copiar enlace

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

6.56. EngineKatelloErrata
Copiar enlace

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

Expand
Table 6.164. Methods summary
NameSummary

list

Retrieves the representation of the Katello errata.

6.56.1. list GET
Copiar enlace

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>
Expand
Table 6.165. Parameters summary
NameTypeDirectionSummary

errata

KatelloErratum[]

Out

A representation of Katello errata.

max

Integer

In

Sets the maximum number of errata to return.

6.56.1.1. max
Copiar enlace

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

6.57. Event
Copiar enlace

A service to manage an event in the system.

Expand
Table 6.166. Methods summary
NameSummary

get

Get an event.

remove

Removes an event from internal audit log.

6.57.1. get GET
Copiar enlace

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.

Expand
Table 6.167. Parameters summary
NameTypeDirectionSummary

event

Event

Out

 

6.57.2. remove DELETE
Copiar enlace

Removes an event from internal audit log.

An event can be removed by sending following request 

DELETE /ovirt-engine/api/events/123
Expand
Table 6.168. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.58. Events
Copiar enlace

A service to manage events in the system.

Expand
Table 6.169. Methods summary
NameSummary

add

Adds an external event to the internal audit log.

list

Get list of events.

undelete

 

6.58.1. add POST
Copiar enlace

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

When using links, like the vm in the previous example, only the id attribute is accepted. The name attribute, if provided, is simply ignored.

Expand
Table 6.170. Parameters summary
NameTypeDirectionSummary

event

Event

In/Out

 

6.58.2. list GET
Copiar enlace

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.
Expand
Table 6.171. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

events

Event[]

Out

 

from

Integer

In

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

max

Integer

In

Sets the maximum number of events to return.

search

String

In

The events service provides search queries similar to other resource services.

6.58.2.1. case_sensitive
Copiar enlace

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.

6.58.2.2. from
Copiar enlace

Indicates the identifier of the the first event that should be returned. The identifiers of events are strictly increasing, so when this parameter is used only the events with that identifiers equal or greater than the given value will be returned. For example, the following request will return only the events with identifiers greater or equal than 123: 

GET /ovirt-engine/api/events?from=123

This parameter is optional, and if not specified then the first event returned will be most recently generated.

6.58.2.3. max
Copiar enlace

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

6.58.3. undelete POST
Copiar enlace

Expand
Table 6.172. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the un-delete should be performed asynchronously.

6.59. ExternalComputeResource
Copiar enlace

Expand
Table 6.173. Methods summary
NameSummary

get

 

6.59.1. get GET
Copiar enlace

Expand
Table 6.174. Parameters summary
NameTypeDirectionSummary

resource

ExternalComputeResource

Out

 

6.60. ExternalComputeResources
Copiar enlace

Expand
Table 6.175. Methods summary
NameSummary

list

 

6.60.1. list GET
Copiar enlace

Expand
Table 6.176. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of resources to return.

resources

ExternalComputeResource[]

Out

 
6.60.1.1. max
Copiar enlace

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

6.61. ExternalDiscoveredHost
Copiar enlace

Expand
Table 6.177. Methods summary
NameSummary

get

 

6.61.1. get GET
Copiar enlace

Expand
Table 6.178. Parameters summary
NameTypeDirectionSummary

host

ExternalDiscoveredHost

Out

 

6.62. ExternalDiscoveredHosts
Copiar enlace

Expand
Table 6.179. Methods summary
NameSummary

list

 

6.62.1. list GET
Copiar enlace

Expand
Table 6.180. Parameters summary
NameTypeDirectionSummary

hosts

ExternalDiscoveredHost[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

6.62.1.1. max
Copiar enlace

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

6.63. ExternalHost
Copiar enlace

Expand
Table 6.181. Methods summary
NameSummary

get

 

6.63.1. get GET
Copiar enlace

Expand
Table 6.182. Parameters summary
NameTypeDirectionSummary

host

ExternalHost

Out

 

6.64. ExternalHostGroup
Copiar enlace

Expand
Table 6.183. Methods summary
NameSummary

get

 

6.64.1. get GET
Copiar enlace

Expand
Table 6.184. Parameters summary
NameTypeDirectionSummary

group

ExternalHostGroup

Out

 

6.65. ExternalHostGroups
Copiar enlace

Expand
Table 6.185. Methods summary
NameSummary

list

 

6.65.1. list GET
Copiar enlace

Expand
Table 6.186. Parameters summary
NameTypeDirectionSummary

groups

ExternalHostGroup[]

Out

 

max

Integer

In

Sets the maximum number of groups to return.

6.65.1.1. max
Copiar enlace

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

6.66. ExternalHostProvider
Copiar enlace

Expand
Table 6.187. Methods summary
NameSummary

get

 

importcertificates

 

remove

 

testconnectivity

 

update

 

6.66.1. get GET
Copiar enlace

Expand
Table 6.188. Parameters summary
NameTypeDirectionSummary

provider

ExternalHostProvider

Out

 

6.66.2. importcertificates POST
Copiar enlace

Expand
Table 6.189. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.66.3. remove DELETE
Copiar enlace

Expand
Table 6.190. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.66.4. testconnectivity POST
Copiar enlace

Expand
Table 6.191. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.66.5. update PUT
Copiar enlace

Expand
Table 6.192. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

ExternalHostProvider

In/Out

 

6.67. ExternalHostProviders
Copiar enlace

Expand
Table 6.193. Methods summary
NameSummary

add

 

list

 

6.67.1. add POST
Copiar enlace

Expand
Table 6.194. Parameters summary
NameTypeDirectionSummary

provider

ExternalHostProvider

In/Out

 

6.67.2. list GET
Copiar enlace

Expand
Table 6.195. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

ExternalHostProvider[]

Out

 
6.67.2.1. max
Copiar enlace

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

6.68. ExternalHosts
Copiar enlace

Expand
Table 6.196. Methods summary
NameSummary

list

 

6.68.1. list GET
Copiar enlace

Expand
Table 6.197. Parameters summary
NameTypeDirectionSummary

hosts

ExternalHost[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

6.68.1.1. max
Copiar enlace

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

6.69. ExternalProvider
Copiar enlace

Expand
Table 6.198. Methods summary
NameSummary

importcertificates

 

testconnectivity

 

6.69.1. importcertificates POST
Copiar enlace

Expand
Table 6.199. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.69.2. testconnectivity POST
Copiar enlace

Expand
Table 6.200. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.70. ExternalProviderCertificate
Copiar enlace

Expand
Table 6.201. Methods summary
NameSummary

get

 

6.70.1. get GET
Copiar enlace

Expand
Table 6.202. Parameters summary
NameTypeDirectionSummary

certificate

Certificate

Out

 

6.71. ExternalProviderCertificates
Copiar enlace

Expand
Table 6.203. Methods summary
NameSummary

list

 

6.71.1. list GET
Copiar enlace

Expand
Table 6.204. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

Out

 

max

Integer

In

Sets the maximum number of certificates to return.

6.71.1.1. max
Copiar enlace

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

6.72. ExternalVmImports
Copiar enlace

Provides capability to import external virtual machines.

Expand
Table 6.205. Methods summary
NameSummary

add

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

6.72.1. add POST
Copiar enlace

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>
Expand
Table 6.206. Parameters summary
NameTypeDirectionSummary

import

ExternalVmImport

In/Out

 

6.73. FenceAgent
Copiar enlace

Expand
Table 6.207. Methods summary
NameSummary

get

 

remove

 

update

 

6.73.1. get GET
Copiar enlace

Expand
Table 6.208. Parameters summary
NameTypeDirectionSummary

agent

Agent

Out

 

6.73.2. remove DELETE
Copiar enlace

Expand
Table 6.209. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.73.3. update PUT
Copiar enlace

Expand
Table 6.210. Parameters summary
NameTypeDirectionSummary

agent

Agent

In/Out

 

async

Boolean

In

Indicates if the update should be performed asynchronously.

6.74. FenceAgents
Copiar enlace

Expand
Table 6.211. Methods summary
NameSummary

add

 

list

 

6.74.1. add POST
Copiar enlace

Expand
Table 6.212. Parameters summary
NameTypeDirectionSummary

agent

Agent

In/Out

 

6.74.2. list GET
Copiar enlace

Expand
Table 6.213. Parameters summary
NameTypeDirectionSummary

agents

Agent[]

Out

 

max

Integer

In

Sets the maximum number of agents to return.

6.74.2.1. max
Copiar enlace

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

6.75. File
Copiar enlace

Expand
Table 6.214. Methods summary
NameSummary

get

 

6.75.1. get GET
Copiar enlace

Expand
Table 6.215. Parameters summary
NameTypeDirectionSummary

file

File

Out

 

6.76. Files
Copiar enlace

Provides a way for clients to list available files.

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

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

Expand
Table 6.216. Methods summary
NameSummary

list

 

6.76.1. list GET
Copiar enlace

Expand
Table 6.217. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

file

File[]

Out

 

max

Integer

In

Sets the maximum number of files to return.

search

String

In

A query string used to restrict the returned files.

6.76.1.1. case_sensitive
Copiar enlace

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.

6.76.1.2. max
Copiar enlace

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

6.77. Filter
Copiar enlace

Expand
Table 6.218. Methods summary
NameSummary

get

 

remove

 

6.77.1. get GET
Copiar enlace

Expand
Table 6.219. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

result

Filter

Out

 

6.77.2. remove DELETE
Copiar enlace

Expand
Table 6.220. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.78. Filters
Copiar enlace

Expand
Table 6.221. Methods summary
NameSummary

add

 

list

 

6.78.1. add POST
Copiar enlace

Expand
Table 6.222. Parameters summary
NameTypeDirectionSummary

filter

Filter

In/Out

 

6.78.2. list GET
Copiar enlace

Expand
Table 6.223. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

filters

Filter[]

Out

 

max

Integer

In

Sets the maximum number of filters to return.

6.78.2.1. max
Copiar enlace

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

6.79. GlusterBrick
Copiar enlace

This service manages a single gluster brick.

Expand
Table 6.224. Methods summary
NameSummary

get

Get details of a brick.

remove

Removes a brick.

replace

Replaces this brick with a new one.

6.79.1. get GET
Copiar enlace

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>
Expand
Table 6.225. Parameters summary
NameTypeDirectionSummary

brick

GlusterBrick

Out

 

6.79.2. remove DELETE
Copiar enlace

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
Expand
Table 6.226. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.79.3. replace POST
Copiar enlace

Replaces this brick with a new one.

Important

This operation has been deprecated since version 3.5 of the engine and will be removed in the future. Use add brick(s) and migrate brick(s) instead.

Expand
Table 6.227. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the replacement should be performed asynchronously.

force

Boolean

In

 

6.80. GlusterBricks
Copiar enlace

This service manages the gluster bricks in a gluster volume

Expand
Table 6.228. Methods summary
NameSummary

activate

Activate the bricks post data migration of remove brick operation.

add

Adds a list of bricks to gluster volume.

list

Lists the bricks of a gluster volume.

migrate

Start migration of data prior to removing bricks.

remove

Removes bricks from gluster volume.

stopmigrate

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

6.80.1. activate POST
Copiar enlace

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>
Expand
Table 6.229. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

bricks

GlusterBrick[]

In

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

6.80.2. add POST
Copiar enlace

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>
Expand
Table 6.230. Parameters summary
NameTypeDirectionSummary

bricks

GlusterBrick[]

In/Out

The list of bricks to be added to the volume

replica_count

Integer

In

Replica count of volume post add operation.

stripe_count

Integer

In

Stripe count of volume post add operation.

6.80.3. list GET
Copiar enlace

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>
Expand
Table 6.231. Parameters summary
NameTypeDirectionSummary

bricks

GlusterBrick[]

Out

 

max

Integer

In

Sets the maximum number of bricks to return.

6.80.3.1. max
Copiar enlace

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

6.80.4. migrate POST
Copiar enlace

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

Expand
Table 6.232. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the migration should be performed asynchronously.

bricks

GlusterBrick[]

In

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

6.80.5. remove DELETE
Copiar enlace

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>
Expand
Table 6.233. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

bricks

GlusterBrick[]

In

The list of bricks to be removed

replica_count

Integer

In

Replica count of volume post add operation.

6.80.6. stopmigrate POST
Copiar enlace

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>
Expand
Table 6.234. Parameters summary
NameTypeDirectionSummary

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.

6.80.6.1. bricks
Copiar enlace

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

6.81. GlusterHook
Copiar enlace

Expand
Table 6.235. Methods summary
NameSummary

disable

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

enable

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

get

 

remove

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

resolve

Resolves missing hook conflict depending on the resolution type.

6.81.1. disable POST
Copiar enlace

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.

Expand
Table 6.236. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.81.2. enable POST
Copiar enlace

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.

Expand
Table 6.237. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.81.3. get GET
Copiar enlace

Expand
Table 6.238. Parameters summary
NameTypeDirectionSummary

hook

GlusterHook

Out

 

6.81.4. remove DELETE
Copiar enlace

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

Expand
Table 6.239. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.81.5. resolve POST
Copiar enlace

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.

Expand
Table 6.240. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

host

Host

In

 

resolution_type

String

In

 

6.82. GlusterHooks
Copiar enlace

Expand
Table 6.241. Methods summary
NameSummary

list

 

6.82.1. list GET
Copiar enlace

Expand
Table 6.242. Parameters summary
NameTypeDirectionSummary

hooks

GlusterHook[]

Out

 

max

Integer

In

Sets the maximum number of hooks to return.

6.82.1.1. max
Copiar enlace

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

6.83. GlusterVolume
Copiar enlace

This service manages a single gluster volume.

Expand
Table 6.243. Methods summary
NameSummary

get

Get the gluster volume details.

getprofilestatistics

Get gluster volume profile statistics.

rebalance

Rebalance the gluster volume.

remove

Removes the gluster volume.

resetalloptions

Resets all the options set in the gluster volume.

resetoption

Resets a particular option in the gluster volume.

setoption

Sets a particular option in the gluster volume.

start

Starts the gluster volume.

startprofile

Start profiling the gluster volume.

stop

Stops the gluster volume.

stopprofile

Stop profiling the gluster volume.

stoprebalance

Stop rebalancing the gluster volume.

6.83.1. get GET
Copiar enlace

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>
Expand
Table 6.244. Parameters summary
NameTypeDirectionSummary

volume

GlusterVolume

Out

Representation of the gluster volume.

6.83.2. getprofilestatistics POST
Copiar enlace

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
Expand
Table 6.245. Parameters summary
NameTypeDirectionSummary

details

GlusterVolumeProfileDetails

Out

Gluster volume profiling information returned from the action.

6.83.3. rebalance POST
Copiar enlace

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
Expand
Table 6.246. Parameters summary
NameTypeDirectionSummary

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.

6.83.3.1. fix_layout
Copiar enlace

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.

6.83.3.2. force
Copiar enlace

Indicates if the rebalance should be force started. The rebalance command can be executed with the force option even when the older clients are connected to the cluster. However, this could lead to a data loss situation. Default is false.

6.83.4. remove DELETE
Copiar enlace

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
Expand
Table 6.247. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.83.5. resetalloptions POST
Copiar enlace

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
Expand
Table 6.248. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

6.83.6. resetoption POST
Copiar enlace

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>
Expand
Table 6.249. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

force

Boolean

In

 

option

Option

In

Option to reset.

6.83.7. setoption POST
Copiar enlace

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>
Expand
Table 6.250. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

option

Option

In

Option to set.

6.83.8. start POST
Copiar enlace

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
Expand
Table 6.251. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

Indicates if the volume should be force started.

6.83.8.1. force
Copiar enlace

Indicates if the volume should be force started. If a gluster volume is started already but few/all bricks are down then force start can be used to bring all the bricks up. Default is false.

6.83.9. startprofile POST
Copiar enlace

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
Expand
Table 6.252. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.83.10. stop POST
Copiar enlace

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
Expand
Table 6.253. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

 

6.83.11. stopprofile POST
Copiar enlace

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
Expand
Table 6.254. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.83.12. stoprebalance POST
Copiar enlace

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
Expand
Table 6.255. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.84. GlusterVolumes
Copiar enlace

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

Expand
Table 6.256. Methods summary
NameSummary

add

Creates a new gluster volume.

list

Lists all gluster volumes in the cluster.

6.84.1. add POST
Copiar enlace

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>
Expand
Table 6.257. Parameters summary
NameTypeDirectionSummary

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.

6.84.2. list GET
Copiar enlace

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
Expand
Table 6.258. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

max

Integer

In

Sets the maximum number of volumes to return.

search

String

In

A query string used to restrict the returned volumes.

volumes

GlusterVolume[]

Out

 
6.84.2.1. case_sensitive
Copiar enlace

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.

6.84.2.2. max
Copiar enlace

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

6.85. Group
Copiar enlace

Expand
Table 6.259. Methods summary
NameSummary

get

 

remove

 

6.85.1. get GET
Copiar enlace

Expand
Table 6.260. Parameters summary
NameTypeDirectionSummary

get

Group

Out

 

6.85.2. remove DELETE
Copiar enlace

Expand
Table 6.261. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.86. Groups
Copiar enlace

Expand
Table 6.262. Methods summary
NameSummary

add

Add group from a directory service.

list

 

6.86.1. add POST
Copiar enlace

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>
Expand
Table 6.263. Parameters summary
NameTypeDirectionSummary

group

Group

In/Out

 

6.86.2. list GET
Copiar enlace

Expand
Table 6.264. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

groups

Group[]

Out

 

max

Integer

In

Sets the maximum number of groups to return.

search

String

In

A query string used to restrict the returned groups.

6.86.2.1. case_sensitive
Copiar enlace

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.

6.86.2.2. max
Copiar enlace

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

6.87. Host
Copiar enlace

A service to manage a host.

Expand
Table 6.265. Methods summary
NameSummary

activate

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

approve

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

commitnetconfig

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

deactivate

Deactivate the host to perform maintenance tasks.

enrollcertificate

Enroll certificate of the host.

fence

Controls host’s power management device.

forceselectspm

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

get

Get the host details.

install

Install VDSM and related software on the host.

iscsidiscover

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

iscsilogin

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

refresh

Refresh the host devices and capabilities.

remove

Remove the host from the system.

setupnetworks

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

unregisteredstoragedomainsdiscover

 

update

Update the host properties.

upgrade

Upgrade VDSM and selected software on the host.

upgradecheck

Check if there are upgrades available for the host.

6.87.1. activate POST
Copiar enlace

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

Expand
Table 6.266. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.87.2. approve POST
Copiar enlace

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.

Expand
Table 6.267. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the approval should be performed asynchronously.

cluster

Cluster

In

 

6.87.3. commitnetconfig POST
Copiar enlace

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.

Important

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

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

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

With a request body like this: 

<action/>
Expand
Table 6.268. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.87.4. deactivate POST
Copiar enlace

Deactivate the host to perform maintenance tasks.

Expand
Table 6.269. Parameters summary
NameTypeDirectionSummary

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.

6.87.4.1. stop_gluster_service
Copiar enlace

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.

6.87.5. enrollcertificate POST
Copiar enlace

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

Expand
Table 6.270. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the enrollment should be performed asynchronously.

6.87.6. fence POST
Copiar enlace

Controls host’s power management device.

For example, let’s assume you want to start the host. This can be done via: 

#!/bin/sh -ex

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

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

async

Boolean

In

Indicates if the fencing should be performed asynchronously.

fence_type

String

In

 

power_management

PowerManagement

Out

 

6.87.7. forceselectspm POST
Copiar enlace

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

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

With a request body like this: 

<action/>
Expand
Table 6.272. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.87.8. get GET
Copiar enlace

Get the host details.

Expand
Table 6.273. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

host

Host

Out

 

6.87.9. install POST
Copiar enlace

Install VDSM and related software on the host. The host type defines additional parameters for the action.

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

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

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

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

Since version 4.1.2 of the engine when a host is reinstalled we override the host firewall definitions by default.

Expand
Table 6.274. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the installation should be performed asynchronously.

deploy_hosted_engine

Boolean

In

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

host

Host

In

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

image

String

In

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

root_password

String

In

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

ssh

Ssh

In

The SSH details used to connect to the host.

undeploy_hosted_engine

Boolean

In

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

6.87.9.1. deploy_hosted_engine
Copiar enlace

When set to true it means this host should deploy also hosted engine components. Missing value is treated as true i.e deploy. Omitting this parameter means false and will perform no operation in hosted engine area.

6.87.9.2. undeploy_hosted_engine
Copiar enlace

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

6.87.10. iscsidiscover POST
Copiar enlace

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

Expand
Table 6.275. Parameters summary
NameTypeDirectionSummary

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.

6.87.11. iscsilogin POST
Copiar enlace

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

Expand
Table 6.276. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the login should be performed asynchronously.

iscsi

IscsiDetails

In

The target iSCSI device.

6.87.12. refresh POST
Copiar enlace

Refresh the host devices and capabilities.

Expand
Table 6.277. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the refresh should be performed asynchronously.

6.87.13. remove DELETE
Copiar enlace

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"
Expand
Table 6.278. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.87.14. setupnetworks POST
Copiar enlace

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

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

#!/bin/sh -ex

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

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
  <modified_bonds>
    <host_nic>
      <name>bond0</name>
      <bonding>
        <options>
          <option>
            <name>mode</name>
            <value>4</value>
          </option>
          <option>
            <name>miimon</name>
            <value>100</value>
          </option>
        </options>
        <slaves>
          <host_nic>
            <name>eth1</name>
          </host_nic>
          <host_nic>
            <name>eth2</name>
          </host_nic>
        </slaves>
      </bonding>
    </host_nic>
  </modified_bonds>
  <modified_network_attachments>
    <network_attachment>
      <network>
        <name>myvlan</name>
      </network>
      <host_nic>
        <name>bond0</name>
      </host_nic>
      <ip_address_assignments>
        <assignment_method>static</assignment_method>
        <ip_address_assignment>
          <ip>
            <address>192.168.122.10</address>
            <netmask>255.255.255.0</netmask>
          </ip>
        </ip_address_assignment>
      </ip_address_assignments>
      <dns_resolver_configuration>
        <name_servers>
          <name_server>1.1.1.1</name_server>
          <name_server>2.2.2.2</name_server>
        </name_servers>
      </dns_resolver_configuration>
    </network_attachment>
  </modified_network_attachments>
 </action>
' \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc/setupnetworks"

Note that this is valid for version 4 of the API. In previous versions some elements were represented as XML attributes instead of XML elements. In particular the options and ip elements were represented as follows: 

<options name="mode" value="4"/>
<options name="miimon" value="100"/>
<ip address="192.168.122.10" netmask="255.255.255.0"/>

Using the Python SDK the same can be done with the following code: 

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

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

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

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

# After modifying the network configuration it is very important to make it
# persistent:
host_service.commit_net_config()
Important

To make sure that the network configuration has been saved in the host, and that it will be applied when the host is rebooted, remember to call commitnetconfig.

Expand
Table 6.279. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

check_connectivity

Boolean

In

 

connectivity_timeout

Integer

In

 

modified_bonds

HostNic[]

In

 

modified_labels

NetworkLabel[]

In

 

modified_network_attachments

NetworkAttachment[]

In

 

removed_bonds

HostNic[]

In

 

removed_labels

NetworkLabel[]

In

 

removed_network_attachments

NetworkAttachment[]

In

 

synchronized_network_attachments

NetworkAttachment[]

In

 

6.87.15. unregisteredstoragedomainsdiscover POST
Copiar enlace

Expand
Table 6.280. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the discovery should be performed asynchronously.

iscsi

IscsiDetails

In

 

storage_domains

StorageDomain[]

Out

 

6.87.16. update PUT
Copiar enlace

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>
Expand
Table 6.281. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

host

Host

In/Out

 

6.87.17. upgrade POST
Copiar enlace

Upgrade VDSM and selected software on the host.

Expand
Table 6.282. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the upgrade should be performed asynchronously.

6.87.18. upgradecheck POST
Copiar enlace

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

6.88. HostDevice
Copiar enlace

A service to access a particular device of a host.

Expand
Table 6.283. Methods summary
NameSummary

get

Retrieve information about a particular host’s device.

6.88.1. get GET
Copiar enlace

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>
Expand
Table 6.284. Parameters summary
NameTypeDirectionSummary

device

HostDevice

Out

 

6.89. HostDevices
Copiar enlace

A service to access host devices.

Expand
Table 6.285. Methods summary
NameSummary

list

List the devices of a host.

6.89.1. list GET
Copiar enlace

List the devices of a host.

Expand
Table 6.286. Parameters summary
NameTypeDirectionSummary

devices

HostDevice[]

Out

 

max

Integer

In

Sets the maximum number of devices to return.

6.89.1.1. max
Copiar enlace

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

6.90. HostHook
Copiar enlace

Expand
Table 6.287. Methods summary
NameSummary

get

 

6.90.1. get GET
Copiar enlace

Expand
Table 6.288. Parameters summary
NameTypeDirectionSummary

hook

Hook

Out

 

6.91. HostHooks
Copiar enlace

Expand
Table 6.289. Methods summary
NameSummary

list

 

6.91.1. list GET
Copiar enlace

Expand
Table 6.290. Parameters summary
NameTypeDirectionSummary

hooks

Hook[]

Out

 

max

Integer

In

Sets the maximum number of hooks to return.

6.91.1.1. max
Copiar enlace

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

6.92. HostNic
Copiar enlace

A service to manage a network interface of a host.

Expand
Table 6.291. Methods summary
NameSummary

get

 

updatevirtualfunctionsconfiguration

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

6.92.1. get GET
Copiar enlace

Expand
Table 6.292. Parameters summary
NameTypeDirectionSummary

nic

HostNic

Out

 

6.92.2. updatevirtualfunctionsconfiguration POST
Copiar enlace

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.

Expand
Table 6.293. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

In

 

6.93. HostNics
Copiar enlace

A service to manage the network interfaces of a host.

Expand
Table 6.294. Methods summary
NameSummary

list

 

6.93.1. list GET
Copiar enlace

Expand
Table 6.295. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

HostNic[]

Out

 
6.93.1.1. max
Copiar enlace

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

6.94. HostNumaNode
Copiar enlace

Expand
Table 6.296. Methods summary
NameSummary

get

 

6.94.1. get GET
Copiar enlace

Expand
Table 6.297. Parameters summary
NameTypeDirectionSummary

node

NumaNode

Out

 

6.95. HostNumaNodes
Copiar enlace

Expand
Table 6.298. Methods summary
NameSummary

list

 

6.95.1. list GET
Copiar enlace

Expand
Table 6.299. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of nodes to return.

nodes

NumaNode[]

Out

 
6.95.1.1. max
Copiar enlace

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

6.96. HostStorage
Copiar enlace

A service to manage host storages.

Expand
Table 6.300. Methods summary
NameSummary

list

Get list of storages.

6.96.1. list GET
Copiar enlace

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>
Expand
Table 6.301. Parameters summary
NameTypeDirectionSummary

report_status

Boolean

In

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

storages

HostStorage[]

Out

Retrieved list of storages.

6.96.1.1. report_status
Copiar enlace

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>

6.97. Hosts
Copiar enlace

A service that manages hosts.

Expand
Table 6.302. Methods summary
NameSummary

add

Creates a new host.

list

Get a list of all available hosts.

6.97.1. add POST
Copiar enlace

Creates a new host.

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

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

POST /ovirt-engine/api/hosts

With the following request body: 

<host>
  <name>myhost</name>
  <address>myhost.example.com</address>
  <root_password>myrootpassword</root_password>
</host>
Note

The root_password element is only included in the client-provided initial representation and is not exposed in the representations returned from subsequent requests.

Important

Since version 4.1.2 of the engine when a host is newly added we override the host firewall definitions by default.

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

POST /ovirt-engine/api/hosts?deploy_hosted_engine=true
Expand
Table 6.303. Parameters summary
NameTypeDirectionSummary

deploy_hosted_engine

Boolean

In

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

host

Host

In/Out

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

undeploy_hosted_engine

Boolean

In

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

6.97.1.1. deploy_hosted_engine
Copiar enlace

When set to true it means this host should deploy also hosted engine components. Missing value is treated as true i.e deploy. Omitting this parameter means false and will perform no operation in hosted engine area.

6.97.1.2. undeploy_hosted_engine
Copiar enlace

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

6.97.2. list GET
Copiar enlace

Get a list of all available hosts.

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

GET /ovirt-engine/api/hosts

The response body will be something like this: 

<hosts>
  <host href="/ovirt-engine/api/hosts/123" id="123">
    ...
  </host>
  <host href="/ovirt-engine/api/hosts/456" id="456">
    ...
  </host>
  ...
</host>
Expand
Table 6.304. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

filter

Boolean

In

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

hosts

Host[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

search

String

In

A query string used to restrict the returned hosts.

6.97.2.1. case_sensitive
Copiar enlace

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.

6.97.2.2. max
Copiar enlace

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

6.98. Icon
Copiar enlace

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

Expand
Table 6.305. Methods summary
NameSummary

get

Get an icon.

6.98.1. get GET
Copiar enlace

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>
Expand
Table 6.306. Parameters summary
NameTypeDirectionSummary

icon

Icon

Out

Retrieved icon.

6.99. Icons
Copiar enlace

A service to manage icons.

Expand
Table 6.307. Methods summary
NameSummary

list

Get a list of icons.

6.99.1. list GET
Copiar enlace

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>
Expand
Table 6.308. Parameters summary
NameTypeDirectionSummary

icons

Icon[]

Out

Retrieved list of icons.

max

Integer

In

Sets the maximum number of icons to return.

6.99.1.1. max
Copiar enlace

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

6.100. Image
Copiar enlace

Expand
Table 6.309. Methods summary
NameSummary

get

 

import

Imports an image.

6.100.1. get GET
Copiar enlace

Expand
Table 6.310. Parameters summary
NameTypeDirectionSummary

image

Image

Out

 

6.100.2. import POST
Copiar enlace

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.

Expand
Table 6.311. Parameters summary
NameTypeDirectionSummary

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.

6.101. ImageTransfer
Copiar enlace

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

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

E.g., for uploading to the disk image with id 52cb593f-837c-4633-a444-35a0a0383706, the client can use oVirt’s Python’s SDK as follows: 

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

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

E.g: 

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

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

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

For example: 

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

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

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

  • proxy_url is the address of a proxy server to the image, to do I/O to.
  • signed_ticket is the content that needs to be added to the Authentication header in the HTTPS request, in order to perform a trusted communication.

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

transfer_headers = {
   'Authorization' :  transfer.signed_ticket,
}

Using Python’s HTTPSConnection, a new connection is established: 

# Extract the URI, port, and path from the transfer's proxy_url.
url = urlparse.urlparse(transfer.proxy_url)

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

For upload, the specific content range being sent must be noted in the Content-Range HTTPS header. This can be used in order to split the transfer into several requests for a more flexible process.

For doing that, the client will have to repeatedly extend the transfer session to keep the channel open. Otherwise, the session will terminate and the transfer will get into paused_system phase, and HTTPS requests to the server will be rejected.

E.g., the client can iterate on chunks of the file, and send them to the proxy server while asking the service to extend the session: 

path = "/path/to/image"
MB_per_request = 32
with open(path, "rb") as disk:
   size = os.path.getsize(path)
   chunk_size = 1024*1024*MB_per_request
   pos = 0
   while (pos < size):
      transfer_service.extend()
      transfer_headers['Content-Range'] = "bytes %d-%d/%d" % (pos, min(pos + chunk_size, size)-1, size)
      proxy_connection.request(
         'PUT',
         url.path,
         disk.read(chunk_size),
         headers=transfer_headers
      )
      r = proxy_connection.getresponse()
      print r.status, r.reason, "Completed", "{:.0%}".format(pos/ float(size))
      pos += chunk_size

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

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

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

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

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

For example: 

transfer_service.finalize()

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

Expand
Table 6.312. Methods summary
NameSummary

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.

6.101.1. extend POST
Copiar enlace

Extend the image transfer session.

6.101.2. finalize POST
Copiar enlace

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.

6.101.3. get GET
Copiar enlace

Get the image transfer entity.

Expand
Table 6.313. Parameters summary
NameTypeDirectionSummary

image_transfer

ImageTransfer

Out

 

6.101.4. pause POST
Copiar enlace

Pause the image transfer session.

6.101.5. resume POST
Copiar enlace

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

6.102. ImageTransfers
Copiar enlace

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

Expand
Table 6.314. Methods summary
NameSummary

add

Add a new image transfer.

list

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

6.102.1. add POST
Copiar enlace

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

Expand
Table 6.315. Parameters summary
NameTypeDirectionSummary

image_transfer

ImageTransfer

In/Out

 

6.102.2. list GET
Copiar enlace

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

Expand
Table 6.316. Parameters summary
NameTypeDirectionSummary

image_transfer

ImageTransfer[]

Out

 

6.103. Images
Copiar enlace

Expand
Table 6.317. Methods summary
NameSummary

list

 

6.103.1. list GET
Copiar enlace

Expand
Table 6.318. Parameters summary
NameTypeDirectionSummary

images

Image[]

Out

 

max

Integer

In

Sets the maximum number of images to return.

6.103.1.1. max
Copiar enlace

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

6.104. InstanceType
Copiar enlace

Expand
Table 6.319. Methods summary
NameSummary

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.

6.104.1. get GET
Copiar enlace

Get a specific instance type and it’s attributes. 

GET /ovirt-engine/api/instancetypes/123
Expand
Table 6.320. Parameters summary
NameTypeDirectionSummary

instance_type

InstanceType

Out

 

6.104.2. remove DELETE
Copiar enlace

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
Expand
Table 6.321. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.104.3. update PUT
Copiar enlace

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>
Expand
Table 6.322. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

instance_type

InstanceType

In/Out

 

6.105. InstanceTypeGraphicsConsole
Copiar enlace

Expand
Table 6.323. Methods summary
NameSummary

get

Gets graphics console configuration of the instance type.

remove

Remove the graphics console from the instance type.

6.105.1. get GET
Copiar enlace

Gets graphics console configuration of the instance type.

Expand
Table 6.324. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

Out

The information about the graphics console of the instance type.

6.105.2. remove DELETE
Copiar enlace

Remove the graphics console from the instance type.

Expand
Table 6.325. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.106. InstanceTypeGraphicsConsoles
Copiar enlace

Expand
Table 6.326. Methods summary
NameSummary

add

Add new graphics console to the instance type.

list

Lists all the configured graphics consoles of the instance type.

6.106.1. add POST
Copiar enlace

Add new graphics console to the instance type.

Expand
Table 6.327. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

In/Out

 

6.106.2. list GET
Copiar enlace

Lists all the configured graphics consoles of the instance type.

Expand
Table 6.328. Parameters summary
NameTypeDirectionSummary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the instance type.

max

Integer

In

Sets the maximum number of consoles to return.

6.106.2.1. max
Copiar enlace

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

6.107. InstanceTypeNic
Copiar enlace

Expand
Table 6.329. Methods summary
NameSummary

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.

6.107.1. get GET
Copiar enlace

Gets network interface configuration of the instance type.

Expand
Table 6.330. Parameters summary
NameTypeDirectionSummary

nic

Nic

Out

 

6.107.2. remove DELETE
Copiar enlace

Remove the network interface from the instance type.

Expand
Table 6.331. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.107.3. update PUT
Copiar enlace

Updates the network interface configuration of the instance type.

Expand
Table 6.332. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

 

6.108. InstanceTypeNics
Copiar enlace

Expand
Table 6.333. Methods summary
NameSummary

add

Add new network interface to the instance type.

list

Lists all the configured network interface of the instance type.

6.108.1. add POST
Copiar enlace

Add new network interface to the instance type.

Expand
Table 6.334. Parameters summary
NameTypeDirectionSummary

nic

Nic

In/Out

 

6.108.2. list GET
Copiar enlace

Lists all the configured network interface of the instance type.

Expand
Table 6.335. Parameters summary
NameTypeDirectionSummary

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.

6.108.2.1. max
Copiar enlace

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

6.109. InstanceTypeWatchdog
Copiar enlace

Expand
Table 6.336. Methods summary
NameSummary

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.

6.109.1. get GET
Copiar enlace

Gets watchdog configuration of the instance type.

Expand
Table 6.337. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

Out

 

6.109.2. remove DELETE
Copiar enlace

Remove a watchdog from the instance type.

Expand
Table 6.338. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.109.3. update PUT
Copiar enlace

Updates the watchdog configuration of the instance type.

Expand
Table 6.339. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

 

6.110. InstanceTypeWatchdogs
Copiar enlace

Expand
Table 6.340. Methods summary
NameSummary

add

Add new watchdog to the instance type.

list

Lists all the configured watchdogs of the instance type.

6.110.1. add POST
Copiar enlace

Add new watchdog to the instance type.

Expand
Table 6.341. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

In/Out

 

6.110.2. list GET
Copiar enlace

Lists all the configured watchdogs of the instance type.

Expand
Table 6.342. Parameters summary
NameTypeDirectionSummary

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

 
6.110.2.1. max
Copiar enlace

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

6.111. InstanceTypes
Copiar enlace

Expand
Table 6.343. Methods summary
NameSummary

add

Creates a new instance type.

list

Lists all existing instance types in the system.

6.111.1. add POST
Copiar enlace

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>
Expand
Table 6.344. Parameters summary
NameTypeDirectionSummary

instance_type

InstanceType

In/Out

 

6.111.2. list GET
Copiar enlace

Lists all existing instance types in the system.

Expand
Table 6.345. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

instance_type

InstanceType[]

Out

 

max

Integer

In

Sets the maximum number of instance types to return.

search

String

In

A query string used to restrict the returned templates.

6.111.2.1. case_sensitive
Copiar enlace

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.

6.111.2.2. max
Copiar enlace

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

6.112. IscsiBond
Copiar enlace

Expand
Table 6.346. Methods summary
NameSummary

get

 

remove

Removes of an existing iSCSI bond.

update

Updates an iSCSI bond.

6.112.1. get GET
Copiar enlace

Expand
Table 6.347. Parameters summary
NameTypeDirectionSummary

bond

IscsiBond

Out

 

6.112.2. remove DELETE
Copiar enlace

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
Expand
Table 6.348. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.112.3. update PUT
Copiar enlace

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>
Expand
Table 6.349. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bond

IscsiBond

In/Out

 

6.113. IscsiBonds
Copiar enlace

Expand
Table 6.350. Methods summary
NameSummary

add

Create a new iSCSI bond on a data center.

list

 

6.113.1. add POST
Copiar enlace

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>
Expand
Table 6.351. Parameters summary
NameTypeDirectionSummary

bond

IscsiBond

In/Out

 

6.113.2. list GET
Copiar enlace

Expand
Table 6.352. Parameters summary
NameTypeDirectionSummary

bonds

IscsiBond[]

Out

 

max

Integer

In

Sets the maximum number of bonds to return.

6.113.2.1. max
Copiar enlace

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

6.114. Job
Copiar enlace

A service to manage a job.

Expand
Table 6.353. Methods summary
NameSummary

clear

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

end

Marks an external job execution as ended.

get

Retrieves a job.

6.114.1. clear POST
Copiar enlace

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/>
Expand
Table 6.354. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.114.2. end POST
Copiar enlace

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>
Expand
Table 6.355. Parameters summary
NameTypeDirectionSummary

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.

6.114.2.1. succeeded
Copiar enlace

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

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

6.114.3. get GET
Copiar enlace

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>
Expand
Table 6.356. Parameters summary
NameTypeDirectionSummary

job

Job

Out

Retrieves the representation of the job.

6.115. Jobs
Copiar enlace

A service to manage jobs.

Expand
Table 6.357. Methods summary
NameSummary

add

Add an external job.

list

Retrieves the representation of the jobs.

6.115.1. add POST
Copiar enlace

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>
Expand
Table 6.358. Parameters summary
NameTypeDirectionSummary

job

Job

In/Out

Job that will be added.

6.115.2. list GET
Copiar enlace

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>
Expand
Table 6.359. Parameters summary
NameTypeDirectionSummary

jobs

Job[]

Out

A representation of jobs.

max

Integer

In

Sets the maximum number of jobs to return.

6.115.2.1. max
Copiar enlace

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

6.116. KatelloErrata
Copiar enlace

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

Expand
Table 6.360. Methods summary
NameSummary

list

Retrieves the representation of the Katello errata.

6.116.1. list GET
Copiar enlace

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>
Expand
Table 6.361. Parameters summary
NameTypeDirectionSummary

errata

KatelloErratum[]

Out

A representation of Katello errata.

max

Integer

In

Sets the maximum number of errata to return.

6.116.1.1. max
Copiar enlace

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

6.117. KatelloErratum
Copiar enlace

A service to manage a Katello erratum.

Expand
Table 6.362. Methods summary
NameSummary

get

Retrieves a Katello erratum.

6.117.1. get GET
Copiar enlace

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>
Expand
Table 6.363. Parameters summary
NameTypeDirectionSummary

erratum

KatelloErratum

Out

Retrieves the representation of the Katello erratum.

6.118. MacPool
Copiar enlace

Expand
Table 6.364. Methods summary
NameSummary

get

 

remove

Removes a MAC address pool.

update

Updates a MAC address pool.

6.118.1. get GET
Copiar enlace

Expand
Table 6.365. Parameters summary
NameTypeDirectionSummary

pool

MacPool

Out

 

6.118.2. remove DELETE
Copiar enlace

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
Expand
Table 6.366. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.118.3. update PUT
Copiar enlace

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>
Expand
Table 6.367. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

pool

MacPool

In/Out

 

6.119. MacPools
Copiar enlace

Expand
Table 6.368. Methods summary
NameSummary

add

Creates a new MAC address pool.

list

 

6.119.1. add POST
Copiar enlace

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>
Expand
Table 6.369. Parameters summary
NameTypeDirectionSummary

pool

MacPool

In/Out

 

6.119.2. list GET
Copiar enlace

Expand
Table 6.370. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of pools to return.

pools

MacPool[]

Out

 
6.119.2.1. max
Copiar enlace

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

6.120. Measurable
Copiar enlace

6.121. Moveable
Copiar enlace

Expand
Table 6.371. Methods summary
NameSummary

move

 

6.121.1. move POST
Copiar enlace

Expand
Table 6.372. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the move should be performed asynchronously.

6.122. Network
Copiar enlace

A service managing a network

Expand
Table 6.373. Methods summary
NameSummary

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.

6.122.1. get GET
Copiar enlace

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>
Expand
Table 6.374. Parameters summary
NameTypeDirectionSummary

network

Network

Out

 

6.122.2. remove DELETE
Copiar enlace

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
Expand
Table 6.375. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.122.3. update PUT
Copiar enlace

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>
Expand
Table 6.376. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

network

Network

In/Out

 

6.123. NetworkAttachment
Copiar enlace

Expand
Table 6.377. Methods summary
NameSummary

get

 

remove

 

update

 

6.123.1. get GET
Copiar enlace

Expand
Table 6.378. Parameters summary
NameTypeDirectionSummary

attachment

NetworkAttachment

Out

 

6.123.2. remove DELETE
Copiar enlace

Expand
Table 6.379. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.123.3. update PUT
Copiar enlace

Expand
Table 6.380. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

attachment

NetworkAttachment

In/Out

 

6.124. NetworkAttachments
Copiar enlace

Expand
Table 6.381. Methods summary
NameSummary

add

 

list

 

6.124.1. add POST
Copiar enlace

Expand
Table 6.382. Parameters summary
NameTypeDirectionSummary

attachment

NetworkAttachment

In/Out

 

6.124.2. list GET
Copiar enlace

Expand
Table 6.383. Parameters summary
NameTypeDirectionSummary

attachments

NetworkAttachment[]

Out

 

max

Integer

In

Sets the maximum number of attachments to return.

6.124.2.1. max
Copiar enlace

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

6.125. NetworkFilter
Copiar enlace

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.

Expand
Table 6.384. Methods summary
NameSummary

get

Retrieves a representation of the network filter.

6.125.1. get GET
Copiar enlace

Retrieves a representation of the network filter.

Expand
Table 6.385. Parameters summary
NameTypeDirectionSummary

network_filter

NetworkFilter

Out

 

6.126. NetworkFilters
Copiar enlace

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>
Expand
Table 6.386. Methods summary
NameSummary

list

Retrieves the representations of the network filters.

6.126.1. list GET
Copiar enlace

Retrieves the representations of the network filters.

Expand
Table 6.387. Parameters summary
NameTypeDirectionSummary

filters

NetworkFilter[]

Out

 

6.127. NetworkLabel
Copiar enlace

Expand
Table 6.388. Methods summary
NameSummary

get

 

remove

Removes a label from a logical network.

6.127.1. get GET
Copiar enlace

Expand
Table 6.389. Parameters summary
NameTypeDirectionSummary

label

NetworkLabel

Out

 

6.127.2. remove DELETE
Copiar enlace

Removes a label from a logical network.

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

DELETE /ovirt-engine/api/networks/123/labels/exemplary
Expand
Table 6.390. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.128. NetworkLabels
Copiar enlace

Expand
Table 6.391. Methods summary
NameSummary

add

Attaches label to logical network.

list

 

6.128.1. add POST
Copiar enlace

Attaches label to logical network.

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

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

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

With a request body like this: 

<label id="mylabel"/>
Expand
Table 6.392. Parameters summary
NameTypeDirectionSummary

label

NetworkLabel

In/Out

 

6.128.2. list GET
Copiar enlace

Expand
Table 6.393. Parameters summary
NameTypeDirectionSummary

labels

NetworkLabel[]

Out

 

max

Integer

In

Sets the maximum number of labels to return.

6.128.2.1. max
Copiar enlace

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

6.129. Networks
Copiar enlace

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.

Expand
Table 6.394. Methods summary
NameSummary

add

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

list

List logical networks.

6.129.1. add POST
Copiar enlace

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>
Expand
Table 6.395. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

 

6.129.2. list GET
Copiar enlace

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>
Expand
Table 6.396. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

 

search

String

In

A query string used to restrict the returned networks.

6.129.2.1. case_sensitive
Copiar enlace

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.

6.129.2.2. max
Copiar enlace

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

6.130. OpenstackImage
Copiar enlace

Expand
Table 6.397. Methods summary
NameSummary

get

 

import

Imports a virtual machine from a Glance image storage domain.

6.130.1. get GET
Copiar enlace

Expand
Table 6.398. Parameters summary
NameTypeDirectionSummary

image

OpenStackImage

Out

 

6.130.2. import POST
Copiar enlace

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>
Expand
Table 6.399. Parameters summary
NameTypeDirectionSummary

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

 

6.131. OpenstackImageProvider
Copiar enlace

Expand
Table 6.400. Methods summary
NameSummary

get

 

importcertificates

 

remove

 

testconnectivity

 

update

 

6.131.1. get GET
Copiar enlace

Expand
Table 6.401. Parameters summary
NameTypeDirectionSummary

provider

OpenStackImageProvider

Out

 

6.131.2. importcertificates POST
Copiar enlace

Expand
Table 6.402. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.131.3. remove DELETE
Copiar enlace

Expand
Table 6.403. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.131.4. testconnectivity POST
Copiar enlace

Expand
Table 6.404. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.131.5. update PUT
Copiar enlace

Expand
Table 6.405. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackImageProvider

In/Out

 

6.132. OpenstackImageProviders
Copiar enlace

Expand
Table 6.406. Methods summary
NameSummary

add

 

list

 

6.132.1. add POST
Copiar enlace

Expand
Table 6.407. Parameters summary
NameTypeDirectionSummary

provider

OpenStackImageProvider

In/Out

 

6.132.2. list GET
Copiar enlace

Expand
Table 6.408. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

OpenStackImageProvider[]

Out

 
6.132.2.1. max
Copiar enlace

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

6.133. OpenstackImages
Copiar enlace

Expand
Table 6.409. Methods summary
NameSummary

list

Lists the images of a Glance image storage domain.

6.133.1. list GET
Copiar enlace

Lists the images of a Glance image storage domain.

Expand
Table 6.410. Parameters summary
NameTypeDirectionSummary

images

OpenStackImage[]

Out

 

max

Integer

In

Sets the maximum number of images to return.

6.133.1.1. max
Copiar enlace

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

6.134. OpenstackNetwork
Copiar enlace

Expand
Table 6.411. Methods summary
NameSummary

get

 

import

This operation imports an external network into oVirt.

6.134.1. get GET
Copiar enlace

Expand
Table 6.412. Parameters summary
NameTypeDirectionSummary

network

OpenStackNetwork

Out

 

6.134.2. import POST
Copiar enlace

This operation imports an external network into oVirt. The network will be added to the data center specified.

Expand
Table 6.413. Parameters summary
NameTypeDirectionSummary

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.

6.134.2.1. data_center
Copiar enlace

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.

6.135. OpenstackNetworkProvider
Copiar enlace

This service manages OpenStack network provider.

Expand
Table 6.414. Methods summary
NameSummary

get

Returns the representation of the object managed by this service.

importcertificates

 

remove

Removes the provider.

testconnectivity

 

update

Updates the provider.

6.135.1. get GET
Copiar enlace

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
Expand
Table 6.415. Parameters summary
NameTypeDirectionSummary

provider

OpenStackNetworkProvider

Out

 

6.135.2. importcertificates POST
Copiar enlace

Expand
Table 6.416. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.135.3. remove DELETE
Copiar enlace

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
Expand
Table 6.417. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.135.4. testconnectivity POST
Copiar enlace

Expand
Table 6.418. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.135.5. update PUT
Copiar enlace

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>
Expand
Table 6.419. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackNetworkProvider

In/Out

The provider to update.

6.136. OpenstackNetworkProviders
Copiar enlace

This service manages OpenStack network providers.

Expand
Table 6.420. Methods summary
NameSummary

add

The operation adds a new network provider to the system.

list

 

6.136.1. add POST
Copiar enlace

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.

Expand
Table 6.421. Parameters summary
NameTypeDirectionSummary

provider

OpenStackNetworkProvider

In/Out

 

6.136.2. list GET
Copiar enlace

Expand
Table 6.422. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

OpenStackNetworkProvider[]

Out

 
6.136.2.1. max
Copiar enlace

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

6.137. OpenstackNetworks
Copiar enlace

Expand
Table 6.423. Methods summary
NameSummary

list

 

6.137.1. list GET
Copiar enlace

Expand
Table 6.424. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

OpenStackNetwork[]

Out

 
6.137.1.1. max
Copiar enlace

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

6.138. OpenstackSubnet
Copiar enlace

Expand
Table 6.425. Methods summary
NameSummary

get

 

remove

 

6.138.1. get GET
Copiar enlace

Expand
Table 6.426. Parameters summary
NameTypeDirectionSummary

subnet

OpenStackSubnet

Out

 

6.138.2. remove DELETE
Copiar enlace

Expand
Table 6.427. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.139. OpenstackSubnets
Copiar enlace

Expand
Table 6.428. Methods summary
NameSummary

add

 

list

 

6.139.1. add POST
Copiar enlace

Expand
Table 6.429. Parameters summary
NameTypeDirectionSummary

subnet

OpenStackSubnet

In/Out

 

6.139.2. list GET
Copiar enlace

Expand
Table 6.430. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of sub-networks to return.

subnets

OpenStackSubnet[]

Out

 
6.139.2.1. max
Copiar enlace

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

6.140. OpenstackVolumeAuthenticationKey
Copiar enlace

Expand
Table 6.431. Methods summary
NameSummary

get

 

remove

 

update

 

6.140.1. get GET
Copiar enlace

Expand
Table 6.432. Parameters summary
NameTypeDirectionSummary

key

OpenstackVolumeAuthenticationKey

Out

 

6.140.2. remove DELETE
Copiar enlace

Expand
Table 6.433. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.140.3. update PUT
Copiar enlace

Expand
Table 6.434. Parameters summary
NameTypeDirectionSummary

key

OpenstackVolumeAuthenticationKey

In/Out

 

6.141. OpenstackVolumeAuthenticationKeys
Copiar enlace

Expand
Table 6.435. Methods summary
NameSummary

add

 

list

 

6.141.1. add POST
Copiar enlace

Expand
Table 6.436. Parameters summary
NameTypeDirectionSummary

key

OpenstackVolumeAuthenticationKey

In/Out

 

6.141.2. list GET
Copiar enlace

Expand
Table 6.437. Parameters summary
NameTypeDirectionSummary

keys

OpenstackVolumeAuthenticationKey[]

Out

 

max

Integer

In

Sets the maximum number of keys to return.

6.141.2.1. max
Copiar enlace

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

6.142. OpenstackVolumeProvider
Copiar enlace

Expand
Table 6.438. Methods summary
NameSummary

get

 

importcertificates

 

remove

 

testconnectivity

 

update

 

6.142.1. get GET
Copiar enlace

Expand
Table 6.439. Parameters summary
NameTypeDirectionSummary

provider

OpenStackVolumeProvider

Out

 

6.142.2. importcertificates POST
Copiar enlace

Expand
Table 6.440. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.142.3. remove DELETE
Copiar enlace

Expand
Table 6.441. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.142.4. testconnectivity POST
Copiar enlace

Expand
Table 6.442. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.142.5. update PUT
Copiar enlace

Expand
Table 6.443. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackVolumeProvider

In/Out

 

6.143. OpenstackVolumeProviders
Copiar enlace

Expand
Table 6.444. Methods summary
NameSummary

add

Adds a new volume provider.

list

Retrieves the list of volume providers.

6.143.1. add POST
Copiar enlace

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>
Expand
Table 6.445. Parameters summary
NameTypeDirectionSummary

provider

OpenStackVolumeProvider

In/Out

 

6.143.2. list GET
Copiar enlace

Retrieves the list of volume providers.

Expand
Table 6.446. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

OpenStackVolumeProvider[]

Out

 
6.143.2.1. max
Copiar enlace

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

6.144. OpenstackVolumeType
Copiar enlace

Expand
Table 6.447. Methods summary
NameSummary

get

 

6.144.1. get GET
Copiar enlace

Expand
Table 6.448. Parameters summary
NameTypeDirectionSummary

type

OpenStackVolumeType

Out

 

6.145. OpenstackVolumeTypes
Copiar enlace

Expand
Table 6.449. Methods summary
NameSummary

list

 

6.145.1. list GET
Copiar enlace

Expand
Table 6.450. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of volume types to return.

types

OpenStackVolumeType[]

Out

 
6.145.1.1. max
Copiar enlace

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

6.146. OperatingSystem
Copiar enlace

Expand
Table 6.451. Methods summary
NameSummary

get

 

6.146.1. get GET
Copiar enlace

Expand
Table 6.452. Parameters summary
NameTypeDirectionSummary

operating_system

OperatingSystemInfo

Out

 

6.147. OperatingSystems
Copiar enlace

Expand
Table 6.453. Methods summary
NameSummary

list

 

6.147.1. list GET
Copiar enlace

Expand
Table 6.454. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

operating_system

OperatingSystemInfo[]

Out

 
6.147.1.1. max
Copiar enlace

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

6.148. Permission
Copiar enlace

Expand
Table 6.455. Methods summary
NameSummary

get

 

remove

 

6.148.1. get GET
Copiar enlace

Expand
Table 6.456. Parameters summary
NameTypeDirectionSummary

permission

Permission

Out

 

6.148.2. remove DELETE
Copiar enlace

Expand
Table 6.457. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.149. Permit
Copiar enlace

A service to manage a specific permit of the role.

Expand
Table 6.458. Methods summary
NameSummary

get

Gets the information about the permit of the role.

remove

Removes the permit from the role.

6.149.1. get GET
Copiar enlace

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>
Expand
Table 6.459. Parameters summary
NameTypeDirectionSummary

permit

Permit

Out

The permit of the role.

6.149.2. remove DELETE
Copiar enlace

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
Expand
Table 6.460. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.150. Permits
Copiar enlace

Represents a permits sub-collection of the specific role.

Expand
Table 6.461. Methods summary
NameSummary

add

Adds a permit to the role.

list

List the permits of the role.

6.150.1. add POST
Copiar enlace

Adds a permit to the role. The permit name can be retrieved from the Section 6.31, “ClusterLevels” service.

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

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

With a request body like this: 

<permit>
  <name>create_vm</name>
</permit>
Expand
Table 6.462. Parameters summary
NameTypeDirectionSummary

permit

Permit

In/Out

The permit to add.

6.150.2. list GET
Copiar enlace

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>
Expand
Table 6.463. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of permits to return.

permits

Permit[]

Out

List of permits.

6.150.2.1. max
Copiar enlace

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

6.151. Qos
Copiar enlace

Expand
Table 6.464. Methods summary
NameSummary

get

 

remove

 

update

 

6.151.1. get GET
Copiar enlace

Expand
Table 6.465. Parameters summary
NameTypeDirectionSummary

qos

Qos

Out

 

6.151.2. remove DELETE
Copiar enlace

Expand
Table 6.466. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.151.3. update PUT
Copiar enlace

Expand
Table 6.467. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

qos

Qos

In/Out

 

6.152. Qoss
Copiar enlace

Expand
Table 6.468. Methods summary
NameSummary

add

 

list

 

6.152.1. add POST
Copiar enlace

Expand
Table 6.469. Parameters summary
NameTypeDirectionSummary

qos

Qos

In/Out

 

6.152.2. list GET
Copiar enlace

Expand
Table 6.470. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of QoS descriptors to return.

qoss

Qos[]

Out

 
6.152.2.1. max
Copiar enlace

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

6.153. Quota
Copiar enlace

Expand
Table 6.471. Methods summary
NameSummary

get

Retrieves a quota.

remove

Delete a quota.

update

Updates a quota.

6.153.1. get GET
Copiar enlace

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>
Expand
Table 6.472. Parameters summary
NameTypeDirectionSummary

quota

Quota

Out

 

6.153.2. remove DELETE
Copiar enlace

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
Expand
Table 6.473. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.153.3. update PUT
Copiar enlace

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>
Expand
Table 6.474. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

quota

Quota

In/Out

 

6.154. QuotaClusterLimit
Copiar enlace

Expand
Table 6.475. Methods summary
NameSummary

get

 

remove

 

6.154.1. get GET
Copiar enlace

Expand
Table 6.476. Parameters summary
NameTypeDirectionSummary

limit

QuotaClusterLimit

Out

 

6.154.2. remove DELETE
Copiar enlace

Expand
Table 6.477. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.155. QuotaClusterLimits
Copiar enlace

Expand
Table 6.478. Methods summary
NameSummary

add

 

list

 

6.155.1. add POST
Copiar enlace

Expand
Table 6.479. Parameters summary
NameTypeDirectionSummary

limit

QuotaClusterLimit

In/Out

 

6.155.2. list GET
Copiar enlace

Expand
Table 6.480. Parameters summary
NameTypeDirectionSummary

limits

QuotaClusterLimit[]

Out

 

max

Integer

In

Sets the maximum number of limits to return.

6.155.2.1. max
Copiar enlace

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

6.156. QuotaStorageLimit
Copiar enlace

Expand
Table 6.481. Methods summary
NameSummary

get

 

remove

 

6.156.1. get GET
Copiar enlace

Expand
Table 6.482. Parameters summary
NameTypeDirectionSummary

limit

QuotaStorageLimit

Out

 

6.156.2. remove DELETE
Copiar enlace

Expand
Table 6.483. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

6.157. QuotaStorageLimits
Copiar enlace

Expand
Table 6.484. Methods summary
NameSummary

add

 

list

 

6.157.1. add POST
Copiar enlace

Expand
Table 6.485. Parameters summary
NameTypeDirectionSummary

limit

QuotaStorageLimit

In/Out

 

6.157.2. list GET
Copiar enlace

Expand
Table 6.486. Parameters summary
NameTypeDirectionSummary

limits

QuotaStorageLimit[]

Out

 

max

Integer

In

Sets the maximum number of limits to return.

6.157.2.1. max
Copiar enlace

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

6.158. Quotas
Copiar enlace

Expand
Table 6.487. Methods summary
NameSummary

add

Creates a new quota.

list

Lists quotas of a data center

6.158.1. add POST
Copiar enlace

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>
Expand
Table 6.488. Parameters summary
NameTypeDirectionSummary

quota

Quota

In/Out

 

6.158.2. list GET
Copiar enlace

Lists quotas of a data center

Expand
Table 6.489. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of quota descriptors to return.

quotas

Quota[]

Out

 
6.158.2.1. max
Copiar enlace

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

6.159. Role
Copiar enlace

Expand
Table 6.490. Methods summary
NameSummary

get

Get the role.

remove

Removes the role.

update

Updates a role.

6.159.1. get GET
Copiar enlace

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>
Expand
Table 6.491. Parameters summary
NameTypeDirectionSummary

role

Role

Out

Retrieved role.

6.159.2. remove DELETE
Copiar enlace

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}
Expand
Table 6.492. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.159.3. update PUT
Copiar enlace

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>
Expand
Table 6.493. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

role

Role

In/Out

Updated role.

6.160. Roles
Copiar enlace

Provides read-only access to the global set of roles

Expand
Table 6.494. Methods summary
NameSummary

add

Create a new role.

list

List roles.

6.160.1. add POST
Copiar enlace

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>
Expand
Table 6.495. Parameters summary
NameTypeDirectionSummary

role

Role

In/Out

Role that will be added.

6.160.2. list GET
Copiar enlace

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>
Expand
Table 6.496. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out

Retrieved list of roles.

6.160.2.1. max
Copiar enlace

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

6.161. SchedulingPolicies
Copiar enlace

Expand
Table 6.497. Methods summary
NameSummary

add

 

list

 

6.161.1. add POST
Copiar enlace

Expand
Table 6.498. Parameters summary
NameTypeDirectionSummary

policy

SchedulingPolicy

In/Out

 

6.161.2. list GET
Copiar enlace

Expand
Table 6.499. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of policies to return.

policies

SchedulingPolicy[]

Out

 
6.161.2.1. max
Copiar enlace

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

6.162. SchedulingPolicy
Copiar enlace

Expand
Table 6.500. Methods summary
NameSummary

get

 

remove

 

update

 

6.162.1. get GET
Copiar enlace

Expand
Table 6.501. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

policy

SchedulingPolicy

Out

 

6.162.2. remove DELETE
Copiar enlace

Expand
Table 6.502. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.162.3. update PUT
Copiar enlace

Expand
Table 6.503. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

policy

SchedulingPolicy

In/Out

 

6.163. SchedulingPolicyUnit
Copiar enlace

Expand
Table 6.504. Methods summary
NameSummary

get

 

remove

 

6.163.1. get GET
Copiar enlace

Expand
Table 6.505. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

unit

SchedulingPolicyUnit

Out

 

6.163.2. remove DELETE
Copiar enlace

Expand
Table 6.506. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.164. SchedulingPolicyUnits
Copiar enlace

Expand
Table 6.507. Methods summary
NameSummary

list

 

6.164.1. list GET
Copiar enlace

Expand
Table 6.508. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of policy units to return.

units

SchedulingPolicyUnit[]

Out

 
6.164.1.1. max
Copiar enlace

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

6.165. Snapshot
Copiar enlace

Expand
Table 6.509. Methods summary
NameSummary

get

 

remove

 

restore

Restores a virtual machine snapshot.

6.165.1. get GET
Copiar enlace

Expand
Table 6.510. Parameters summary
NameTypeDirectionSummary

snapshot

Snapshot

Out

 

6.165.2. remove DELETE
Copiar enlace

Expand
Table 6.511. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.165.3. restore POST
Copiar enlace

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/>
Expand
Table 6.512. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the restore should be performed asynchronously.

disks

Disk[]

In

 

restore_memory

Boolean

In

 

6.166. SnapshotCdrom
Copiar enlace

Expand
Table 6.513. Methods summary
NameSummary

get

 

6.166.1. get GET
Copiar enlace

Expand
Table 6.514. Parameters summary
NameTypeDirectionSummary

cdrom

Cdrom

Out

 

6.167. SnapshotCdroms
Copiar enlace

Expand
Table 6.515. Methods summary
NameSummary

list

 

6.167.1. list GET
Copiar enlace

Expand
Table 6.516. Parameters summary
NameTypeDirectionSummary

cdroms

Cdrom[]

Out

 

max

Integer

In

Sets the maximum number of CDROMS to return.

6.167.1.1. max
Copiar enlace

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

6.168. SnapshotDisk
Copiar enlace

Expand
Table 6.517. Methods summary
NameSummary

get

 

6.168.1. get GET
Copiar enlace

Expand
Table 6.518. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.169. SnapshotDisks
Copiar enlace

Expand
Table 6.519. Methods summary
NameSummary

list

 

6.169.1. list GET
Copiar enlace

Expand
Table 6.520. Parameters summary
NameTypeDirectionSummary

disks

Disk[]

Out

 

max

Integer

In

Sets the maximum number of disks to return.

6.169.1.1. max
Copiar enlace

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

6.170. SnapshotNic
Copiar enlace

Expand
Table 6.521. Methods summary
NameSummary

get

 

6.170.1. get GET
Copiar enlace

Expand
Table 6.522. Parameters summary
NameTypeDirectionSummary

nic

Nic

Out

 

6.171. SnapshotNics
Copiar enlace

Expand
Table 6.523. Methods summary
NameSummary

list

 

6.171.1. list GET
Copiar enlace

Expand
Table 6.524. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

 
6.171.1.1. max
Copiar enlace

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

6.172. Snapshots
Copiar enlace

Expand
Table 6.525. Methods summary
NameSummary

add

Creates a virtual machine snapshot.

list

 

6.172.1. add POST
Copiar enlace

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

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>
Expand
Table 6.526. Parameters summary
NameTypeDirectionSummary

snapshot

Snapshot

In/Out

 

6.172.2. list GET
Copiar enlace

Expand
Table 6.527. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

Snapshot[]

Out

 
6.172.2.1. max
Copiar enlace

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

6.173. SshPublicKey
Copiar enlace

Expand
Table 6.528. Methods summary
NameSummary

get

 

remove

 

update

 

6.173.1. get GET
Copiar enlace

Expand
Table 6.529. Parameters summary
NameTypeDirectionSummary

key

SshPublicKey

Out

 

6.173.2. remove DELETE
Copiar enlace

Expand
Table 6.530. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.173.3. update PUT
Copiar enlace

Expand
Table 6.531. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

key

SshPublicKey

In/Out

 

6.174. SshPublicKeys
Copiar enlace

Expand
Table 6.532. Methods summary
NameSummary

add

 

list

 

6.174.1. add POST
Copiar enlace

Expand
Table 6.533. Parameters summary
NameTypeDirectionSummary

key

SshPublicKey

In/Out

 

6.174.2. list GET
Copiar enlace

Expand
Table 6.534. Parameters summary
NameTypeDirectionSummary

keys

SshPublicKey[]

Out

 

max

Integer

In

Sets the maximum number of keys to return.

6.174.2.1. max
Copiar enlace

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

6.175. Statistic
Copiar enlace

Expand
Table 6.535. Methods summary
NameSummary

get

 

6.175.1. get GET
Copiar enlace

Expand
Table 6.536. Parameters summary
NameTypeDirectionSummary

statistic

Statistic

Out

 

6.176. Statistics
Copiar enlace

Expand
Table 6.537. Methods summary
NameSummary

list

Retrieves a list of statistics.

6.176.1. list GET
Copiar enlace

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>
Expand
Table 6.538. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of statistics to return.

statistics

Statistic[]

Out

 
6.176.1.1. max
Copiar enlace

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

6.177. Step
Copiar enlace

A service to manage a step.

Expand
Table 6.539. Methods summary
NameSummary

end

Marks an external step execution as ended.

get

Retrieves a step.

6.177.1. end POST
Copiar enlace

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>
Expand
Table 6.540. Parameters summary
NameTypeDirectionSummary

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.

6.177.1.1. succeeded
Copiar enlace

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

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

6.177.2. get GET
Copiar enlace

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>
Expand
Table 6.541. Parameters summary
NameTypeDirectionSummary

step

Step

Out

Retrieves the representation of the step.

6.178. Steps
Copiar enlace

A service to manage steps.

Expand
Table 6.542. Methods summary
NameSummary

add

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

list

Retrieves the representation of the steps.

6.178.1. add POST
Copiar enlace

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>
Expand
Table 6.543. Parameters summary
NameTypeDirectionSummary

step

Step

In/Out

Step that will be added.

6.178.2. list GET
Copiar enlace

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>
Expand
Table 6.544. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of steps to return.

steps

Step[]

Out

A representation of steps.

6.178.2.1. max
Copiar enlace

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

6.179. Storage
Copiar enlace

Expand
Table 6.545. Methods summary
NameSummary

get

 

6.179.1. get GET
Copiar enlace

Expand
Table 6.546. Parameters summary
NameTypeDirectionSummary

report_status

Boolean

In

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

storage

HostStorage

Out

 
6.179.1.1. report_status
Copiar enlace

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>

6.180. StorageDomain
Copiar enlace

Expand
Table 6.547. Methods summary
NameSummary

get

 

isattached

 

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.

6.180.1. get GET
Copiar enlace

Expand
Table 6.548. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

storage_domain

StorageDomain

Out

 

6.180.2. isattached POST
Copiar enlace

Expand
Table 6.549. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

host

Host

In

 

is_attached

Boolean

Out

 

6.180.3. reduceluns POST
Copiar enlace

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>
Expand
Table 6.550. Parameters summary
NameTypeDirectionSummary

logical_units

LogicalUnit[]

In

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

6.180.4. refreshluns POST
Copiar enlace

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>
Expand
Table 6.551. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the refresh should be performed asynchronously.

logical_units

LogicalUnit[]

In

The LUNs that need to be refreshed.

6.180.5. remove DELETE
Copiar enlace

Removes the storage domain.

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

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

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

Expand
Table 6.552. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

destroy

Boolean

In

Indicates if the operation should succeed, and the storage domain removed from the database, even if the storage isn’t accessible.

format

Boolean

In

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

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

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

host

String

In

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

6.180.5.1. destroy
Copiar enlace

Indicates if the operation should succeed, and the storage domain removed from the database, even if the storage isn’t accessible. 

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

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

6.180.5.2. host
Copiar enlace

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

This parameter is mandatory, and it can contain the name or the identifier of the host. For example, to use the host named myhost to remove the storage domain with identifier 123 send a request like this: 

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

6.180.6. update PUT
Copiar enlace

Updates a storage domain.

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

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

PUT /ovirt-engine/api/storagedomains/123

With a request body as follows: 

<storage_domain>
  <name>data2</name>
  <wipe_after_delete>true</wipe_after_delete>
</storage_domain>
Expand
Table 6.553. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

storage_domain

StorageDomain

In/Out

 

6.180.7. updateovfstore POST
Copiar enlace

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

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

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

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

Expand
Table 6.554. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the OVF_STORE update should be performed asynchronously.

6.181. StorageDomainContentDisk
Copiar enlace

Expand
Table 6.555. Methods summary
NameSummary

get

 

6.181.1. get GET
Copiar enlace

Expand
Table 6.556. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

filter

Boolean

In

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

6.182. StorageDomainContentDisks
Copiar enlace

Expand
Table 6.557. Methods summary
NameSummary

list

 

6.182.1. list GET
Copiar enlace

Expand
Table 6.558. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

disks

Disk[]

Out

 

max

Integer

In

Sets the maximum number of disks to return.

search

String

In

A query string used to restrict the returned disks.

6.182.1.1. case_sensitive
Copiar enlace

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.

6.182.1.2. max
Copiar enlace

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

6.183. StorageDomainServerConnection
Copiar enlace

Expand
Table 6.559. Methods summary
NameSummary

get

 

remove

Detaches a storage connection from storage.

6.183.1. get GET
Copiar enlace

Expand
Table 6.560. Parameters summary
NameTypeDirectionSummary

connection

StorageConnection

Out

 

6.183.2. remove DELETE
Copiar enlace

Detaches a storage connection from storage.

Expand
Table 6.561. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.184. StorageDomainServerConnections
Copiar enlace

Expand
Table 6.562. Methods summary
NameSummary

add

 

list

 

6.184.1. add POST
Copiar enlace

Expand
Table 6.563. Parameters summary
NameTypeDirectionSummary

connection

StorageConnection

In/Out

 

6.184.2. list GET
Copiar enlace

Expand
Table 6.564. Parameters summary
NameTypeDirectionSummary

connections

StorageConnection[]

Out

 

max

Integer

In

Sets the maximum number of connections to return.

6.184.2.1. max
Copiar enlace

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

6.185. StorageDomainTemplate
Copiar enlace

Expand
Table 6.565. Methods summary
NameSummary

get

 

import

Action to import a template from an export storage domain.

register

 

remove

 

6.185.1. get GET
Copiar enlace

Expand
Table 6.566. Parameters summary
NameTypeDirectionSummary

template

Template

Out

 

6.185.2. import POST
Copiar enlace

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>
Expand
Table 6.567. Parameters summary
NameTypeDirectionSummary

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

 
6.185.2.1. clone
Copiar enlace

Use the optional clone parameter to generate new UUIDs for the imported template and its entities.

The user might want to import a template with the clone parameter set to false when importing a template from an export domain, with templates that was exported by a different Red Hat Virtualization environment.

6.185.3. register POST
Copiar enlace

Expand
Table 6.568. Parameters summary
NameTypeDirectionSummary

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

 

template

Template

In

 
6.185.3.1. allow_partial_import
Copiar enlace

Indicates whether a template 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 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.

6.185.4. remove DELETE
Copiar enlace

Expand
Table 6.569. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.186. StorageDomainTemplates
Copiar enlace

Expand
Table 6.570. Methods summary
NameSummary

list

 

6.186.1. list GET
Copiar enlace

Expand
Table 6.571. Parameters summary
NameTypeDirectionSummary

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.

6.186.1.1. max
Copiar enlace

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

6.186.1.2. unregistered
Copiar enlace

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.

6.187. StorageDomainVm
Copiar enlace

Expand
Table 6.572. Methods summary
NameSummary

get

 

import

Imports a virtual machine from an export storage domain.

register

 

remove

Deletes a virtual machine from an export storage domain.

6.187.1. get GET
Copiar enlace

Expand
Table 6.573. Parameters summary
NameTypeDirectionSummary

vm

Vm

Out

 

6.187.2. import POST
Copiar enlace

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>
Expand
Table 6.574. Parameters summary
NameTypeDirectionSummary

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.

storage_domain

StorageDomain

In

 

vm

Vm

In

 
6.187.2.1. clone
Copiar enlace

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.

6.187.2.2. collapse_snapshots
Copiar enlace

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.

6.187.3. register POST
Copiar enlace

Expand
Table 6.575. Parameters summary
NameTypeDirectionSummary

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.

vm

Vm

In

 

vnic_profile_mappings

VnicProfileMapping[]

In

Mapping rules for virtual NIC profiles that will be applied during the import process.

6.187.3.1. allow_partial_import
Copiar enlace

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.

6.187.3.2. reassign_bad_macs
Copiar enlace

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.

6.187.4. remove DELETE
Copiar enlace

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
Expand
Table 6.576. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.188. StorageDomainVmDiskAttachment
Copiar enlace

Returns the details of the disks attached to a virtual machine in the export domain.

Expand
Table 6.577. Methods summary
NameSummary

get

Returns the details of the attachment with all its properties and a link to the disk.

6.188.1. get GET
Copiar enlace

Returns the details of the attachment with all its properties and a link to the disk.

Expand
Table 6.578. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

Out

The disk attachment.

6.189. StorageDomainVmDiskAttachments
Copiar enlace

Returns the details of a disk attached to a virtual machine in the export domain.

Expand
Table 6.579. Methods summary
NameSummary

list

List the disks that are attached to the virtual machine.

6.189.1. list GET
Copiar enlace

List the disks that are attached to the virtual machine.

Expand
Table 6.580. Parameters summary
NameTypeDirectionSummary

attachments

DiskAttachment[]

Out

 

6.190. StorageDomainVms
Copiar enlace

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.

Expand
Table 6.581. Methods summary
NameSummary

list

 

6.190.1. list GET
Copiar enlace

Expand
Table 6.582. Parameters summary
NameTypeDirectionSummary

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

 
6.190.1.1. max
Copiar enlace

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

6.190.1.2. unregistered
Copiar enlace

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.

6.191. StorageDomains
Copiar enlace

Expand
Table 6.583. Methods summary
NameSummary

add

Adds a new storage domain.

list

 

6.191.1. add POST
Copiar enlace

Adds a new storage domain.

Creation of a new StorageDomain requires the name, type, host and storage attributes. Identify the host attribute with the id or name attributes. In oVirt 3.6 and later you can enable the wipe after delete option by default on the storage domain. To configure this, specify wipe_after_delete in the POST request. This option can be edited after the domain is created, but doing so will not change the wipe after delete property of disks that already exist.

To add a new storage domain with specified name, type, storage.type, storage.address and storage.path and by using a host with an id 123, send a request as follows: 

POST /ovirt-engine/api/storagedomains

With a request body as follows: 

<storage_domain>
  <name>mydata</name>
  <type>data</type>
  <storage>
    <type>nfs</type>
    <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>
Expand
Table 6.584. Parameters summary
NameTypeDirectionSummary

storage_domain

StorageDomain

In/Out

 

6.191.2. list GET
Copiar enlace

Expand
Table 6.585. Parameters summary
NameTypeDirectionSummary

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.

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

 
6.191.2.1. case_sensitive
Copiar enlace

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.

6.191.2.2. max
Copiar enlace

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

6.192. StorageServerConnection
Copiar enlace

Expand
Table 6.586. Methods summary
NameSummary

get

 

remove

Removes a storage connection.

update

Updates the storage connection.

6.192.1. get GET
Copiar enlace

Expand
Table 6.587. Parameters summary
NameTypeDirectionSummary

conection

StorageConnection

Out

 

6.192.2. remove DELETE
Copiar enlace

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.

Expand
Table 6.588. Parameters summary
NameTypeDirectionSummary

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

6.192.2.1. host
Copiar enlace

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

6.192.3. update PUT
Copiar enlace

Updates the storage connection.

For example, to change the address of the storage server send a request like this: 

PUT /ovirt-engine/api/storageconnections/123

With a request body like this: 

<storage_connection>
  <address>mynewnfs.example.com</address>
  <host>
    <name>myhost</name>
  </host>
</storage_connection>
Expand
Table 6.589. Parameters summary
NameTypeDirectionSummary

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.

6.192.3.1. force
Copiar enlace

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.

6.193. StorageServerConnectionExtension
Copiar enlace

Expand
Table 6.590. Methods summary
NameSummary

get

 

remove

 

update

Update a storage server connection extension for the given host.

6.193.1. get GET
Copiar enlace

Expand
Table 6.591. Parameters summary
NameTypeDirectionSummary

extension

StorageConnectionExtension

Out

 

6.193.2. remove DELETE
Copiar enlace

Expand
Table 6.592. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.193.3. update PUT
Copiar enlace

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>
Expand
Table 6.593. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

extension

StorageConnectionExtension

In/Out

 

6.194. StorageServerConnectionExtensions
Copiar enlace

Expand
Table 6.594. Methods summary
NameSummary

add

Creates a new storage server connection extension for the given host.

list

 

6.194.1. add POST
Copiar enlace

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>
Expand
Table 6.595. Parameters summary
NameTypeDirectionSummary

extension

StorageConnectionExtension

In/Out

 

6.194.2. list GET
Copiar enlace

Expand
Table 6.596. Parameters summary
NameTypeDirectionSummary

extensions

StorageConnectionExtension[]

Out

 

max

Integer

In

Sets the maximum number of extensions to return.

6.194.2.1. max
Copiar enlace

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

6.195. StorageServerConnections
Copiar enlace

Expand
Table 6.597. Methods summary
NameSummary

add

Creates a new storage connection.

list

 

6.195.1. add POST
Copiar enlace

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>
Expand
Table 6.598. Parameters summary
NameTypeDirectionSummary

connection

StorageConnection

In/Out

 

6.195.2. list GET
Copiar enlace

Expand
Table 6.599. Parameters summary
NameTypeDirectionSummary

connections

StorageConnection[]

Out

 

max

Integer

In

Sets the maximum number of connections to return.

6.195.2.1. max
Copiar enlace

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

6.196. System
Copiar enlace

Expand
Table 6.600. Methods summary
NameSummary

get

Returns basic information describing the API, like the product name, the version number and a summary of the number of relevant objects.

reloadconfigurations

 

6.196.1. get GET
Copiar enlace

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.

Expand
Table 6.601. Parameters summary
NameTypeDirectionSummary

api

Api

Out

 

6.196.2. reloadconfigurations POST
Copiar enlace

Expand
Table 6.602. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reload should be performed asynchronously.

6.197. SystemPermissions
Copiar enlace

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.

Expand
Table 6.603. Methods summary
NameSummary

add

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

list

List all the permissions of the specific entity.

6.197.1. add POST
Copiar enlace

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>
Expand
Table 6.604. Parameters summary
NameTypeDirectionSummary

permission

Permission

In/Out

The permission.

6.197.2. list GET
Copiar enlace

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>
Expand
Table 6.605. Parameters summary
NameTypeDirectionSummary

permissions

Permission[]

Out

The list of permissions.

6.198. Tag
Copiar enlace

A service to manage a specific tag in the system.

Expand
Table 6.606. Methods summary
NameSummary

get

Gets the information about the tag.

remove

Removes the tag from the system.

update

Updates the tag entity.

6.198.1. get GET
Copiar enlace

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>
Expand
Table 6.607. Parameters summary
NameTypeDirectionSummary

tag

Tag

Out

The tag.

6.198.2. remove DELETE
Copiar enlace

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
Expand
Table 6.608. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.198.3. update PUT
Copiar enlace

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>
Expand
Table 6.609. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

tag

Tag

In/Out

The updated tag.

6.199. Tags
Copiar enlace

Represents a service to manage collection of the tags in the system.

Expand
Table 6.610. Methods summary
NameSummary

add

Add a new tag to the system.

list

List the tags in the system.

6.199.1. add POST
Copiar enlace

Add a new tag to the system.

For example, to add new tag with name mytag to the system send a request like this: 

POST /ovirt-engine/api/tags

With a request body like this: 

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

The root tag is a special pseudo-tag assumed as the default parent tag if no parent tag is specified. The root tag cannot be deleted nor assigned a parent tag.

To create new tag with specific parent tag send a request body like this: 

<tag>
  <name>mytag</name>
  <parent>
    <name>myparenttag</name>
  </parent>
</tag>
Expand
Table 6.611. Parameters summary
NameTypeDirectionSummary

tag

Tag

In/Out

The added tag.

6.199.2. list GET
Copiar enlace

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)
Expand
Table 6.612. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

List of all tags in the system.

6.199.2.1. max
Copiar enlace

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

6.200. Template
Copiar enlace

Manages the virtual machine template and template versions.

Expand
Table 6.613. Methods summary
NameSummary

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.

6.200.1. export POST
Copiar enlace

Exports a template to the data center export domain.

For example, the operation can be facilitated using the following request: 

POST /ovirt-engine/api/templates/123/export

With a request body like this: 

<action>
  <storage_domain id="456"/>
  <exclusive>true<exclusive/>
</action>
Expand
Table 6.614. Parameters summary
NameTypeDirectionSummary

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.

6.200.1.1. exclusive
Copiar enlace

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.

6.200.2. get GET
Copiar enlace

Returns the information about this template or template version.

Expand
Table 6.615. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

template

Template

Out

The information about the template or template version.

6.200.3. remove DELETE
Copiar enlace

Removes a virtual machine template. 

DELETE /ovirt-engine/api/templates/123
Expand
Table 6.616. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.200.4. update PUT
Copiar enlace

Updates the template.

The name, description, type, memory, cpu, topology, os, high_availability, display, stateless, usb and timezone elements can be updated after a template has been created.

For example, to update a template to so that it has 1 GiB of memory send a request like this: 

PUT /ovirt-engine/api/templates/123

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>
Expand
Table 6.617. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

template

Template

In/Out

 

6.201. TemplateCdrom
Copiar enlace

A service managing a CD-ROM device on templates.

Expand
Table 6.618. Methods summary
NameSummary

get

Returns the information about this CD-ROM device.

6.201.1. get GET
Copiar enlace

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/
Expand
Table 6.619. Parameters summary
NameTypeDirectionSummary

cdrom

Cdrom

Out

The information about the CD-ROM device.

6.201.1.1. cdrom
Copiar enlace

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>

6.202. TemplateCdroms
Copiar enlace

Lists the CD-ROM devices of a template.

Expand
Table 6.620. Methods summary
NameSummary

list

 

6.202.1. list GET
Copiar enlace

Expand
Table 6.621. Parameters summary
NameTypeDirectionSummary

cdroms

Cdrom[]

Out

The list of CD-ROM devices of the template.

max

Integer

In

Sets the maximum number of CD-ROMs to return.

6.202.1.1. max
Copiar enlace

Sets the maximum number of CD-ROMs to return. If not specified all the CD-ROMs are returned.

6.203. TemplateDisk
Copiar enlace

Expand
Table 6.622. Methods summary
NameSummary

copy

 

export

 

get

 

remove

 

6.203.1. copy POST
Copiar enlace

Expand
Table 6.623. Parameters summary
NameTypeDirectionSummary

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.

6.203.2. export POST
Copiar enlace

Expand
Table 6.624. Parameters summary
NameTypeDirectionSummary

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.

6.203.3. get GET
Copiar enlace

Expand
Table 6.625. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.203.4. remove DELETE
Copiar enlace

Expand
Table 6.626. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.204. TemplateDiskAttachment
Copiar enlace

This service manages the attachment of a disk to a template.

Expand
Table 6.627. Methods summary
NameSummary

get

Returns the details of the attachment.

remove

Removes the disk from the template.

6.204.1. get GET
Copiar enlace

Returns the details of the attachment.

Expand
Table 6.628. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

Out

 

6.204.2. remove DELETE
Copiar enlace

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
Expand
Table 6.629. Parameters summary
NameTypeDirectionSummary

force

Boolean

In

 

storage_domain

String

In

Specifies the identifier of the storage domain the image to be removed resides on.

6.205. TemplateDiskAttachments
Copiar enlace

This service manages the set of disks attached to a template. Each attached disk is represented by a DiskAttachment.

Expand
Table 6.630. Methods summary
NameSummary

list

List the disks that are attached to the template.

6.205.1. list GET
Copiar enlace

List the disks that are attached to the template.

Expand
Table 6.631. Parameters summary
NameTypeDirectionSummary

attachments

DiskAttachment[]

Out

 

6.206. TemplateDisks
Copiar enlace

Expand
Table 6.632. Methods summary
NameSummary

list

 

6.206.1. list GET
Copiar enlace

Expand
Table 6.633. Parameters summary
NameTypeDirectionSummary

disks

Disk[]

Out

 

max

Integer

In

Sets the maximum number of disks to return.

6.206.1.1. max
Copiar enlace

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

6.207. TemplateGraphicsConsole
Copiar enlace

Expand
Table 6.634. Methods summary
NameSummary

get

Gets graphics console configuration of the template.

remove

Remove the graphics console from the template.

6.207.1. get GET
Copiar enlace

Gets graphics console configuration of the template.

Expand
Table 6.635. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

Out

The information about the graphics console of the template.

6.207.2. remove DELETE
Copiar enlace

Remove the graphics console from the template.

Expand
Table 6.636. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.208. TemplateGraphicsConsoles
Copiar enlace

Expand
Table 6.637. Methods summary
NameSummary

add

Add new graphics console to the template.

list

Lists all the configured graphics consoles of the template.

6.208.1. add POST
Copiar enlace

Add new graphics console to the template.

Expand
Table 6.638. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

In/Out

 

6.208.2. list GET
Copiar enlace

Lists all the configured graphics consoles of the template.

Expand
Table 6.639. Parameters summary
NameTypeDirectionSummary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the template.

max

Integer

In

Sets the maximum number of consoles to return.

6.208.2.1. max
Copiar enlace

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

6.209. TemplateNic
Copiar enlace

Expand
Table 6.640. Methods summary
NameSummary

get

 

remove

 

update

 

6.209.1. get GET
Copiar enlace

Expand
Table 6.641. Parameters summary
NameTypeDirectionSummary

nic

Nic

Out

 

6.209.2. remove DELETE
Copiar enlace

Expand
Table 6.642. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.209.3. update PUT
Copiar enlace

Expand
Table 6.643. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

 

6.210. TemplateNics
Copiar enlace

Expand
Table 6.644. Methods summary
NameSummary

add

 

list

 

6.210.1. add POST
Copiar enlace

Expand
Table 6.645. Parameters summary
NameTypeDirectionSummary

nic

Nic

In/Out

 

6.210.2. list GET
Copiar enlace

Expand
Table 6.646. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

 
6.210.2.1. max
Copiar enlace

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

6.211. TemplateWatchdog
Copiar enlace

Expand
Table 6.647. Methods summary
NameSummary

get

 

remove

 

update

 

6.211.1. get GET
Copiar enlace

Expand
Table 6.648. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

Out

 

6.211.2. remove DELETE
Copiar enlace

Expand
Table 6.649. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.211.3. update PUT
Copiar enlace

Expand
Table 6.650. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

 

6.212. TemplateWatchdogs
Copiar enlace

Expand
Table 6.651. Methods summary
NameSummary

add

 

list

 

6.212.1. add POST
Copiar enlace

Expand
Table 6.652. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

In/Out

 

6.212.2. list GET
Copiar enlace

Expand
Table 6.653. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of watchdogs to return.

watchdogs

Watchdog[]

Out

 
6.212.2.1. max
Copiar enlace

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

6.213. Templates
Copiar enlace

This service manages the virtual machine templates available in the system.

Expand
Table 6.654. Methods summary
NameSummary

add

Creates a new template.

list

Returns the list of virtual machine templates.

6.213.1. add POST
Copiar enlace

Creates a new template.

This requires the name and vm elements. Identify the virtual machine with the id name attributes. 

POST /ovirt-engine/api/templates

With a request body like this: 

<template>
  <name>mytemplate</name>
  <vm id="123"/>
</template>

The template can be created as a sub version of an existing template.This requires the name and vm attributes for the new template, and the base_template and version_name attributes for the new template version. The base_template and version_name attributes must be specified within a version section enclosed in the template section. Identify the virtual machine with the id or name attributes. 

<template>
  <name>mytemplate</name>
  <vm id="123"/>
  <version>
    <base_template id="456"/>
    <version_name>mytemplate_001</version_name>
  </version>
</template>
Expand
Table 6.655. Parameters summary
NameTypeDirectionSummary

clone_permissions

Boolean

In

Specifies if the permissions of the virtual machine should be copied to the template.

seal

Boolean

In

Seal the template.

template

Template

In/Out

The information about the template or template version.

6.213.1.1. clone_permissions
Copiar enlace

Specifies if the permissions of the virtual machine should be copied to the template.

If this optional parameter is provided, and its values is true then the permissions of the virtual machine (only the direct ones, not the inherited ones) will be copied to the created template. For example, to create a template from the myvm virtual machine copying its permissions, send a request like this: 

POST /ovirt-engine/api/templates?clone_permissions=true

With a request body like this: 

<template>
  <name>mytemplate<name>
  <vm>
    <name>myvm<name>
  </vm>
</template>
6.213.1.2. seal
Copiar enlace

Seal 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 etc., thus making easy to use the template to create multiple virtual machines without manual intervention.

Currently sealing is supported only for Linux OS.

6.213.2. list GET
Copiar enlace

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.

Expand
Table 6.656. Parameters summary
NameTypeDirectionSummary

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.

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.

6.213.2.1. case_sensitive
Copiar enlace

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.

6.213.2.2. max
Copiar enlace

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

6.214. UnmanagedNetwork
Copiar enlace

Expand
Table 6.657. Methods summary
NameSummary

get

 

remove

 

6.214.1. get GET
Copiar enlace

Expand
Table 6.658. Parameters summary
NameTypeDirectionSummary

network

UnmanagedNetwork

Out

 

6.214.2. remove DELETE
Copiar enlace

Expand
Table 6.659. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.215. UnmanagedNetworks
Copiar enlace

Expand
Table 6.660. Methods summary
NameSummary

list

 

6.215.1. list GET
Copiar enlace

Expand
Table 6.661. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

UnmanagedNetwork[]

Out

 
6.215.1.1. max
Copiar enlace

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

6.216. User
Copiar enlace

A service to manage a user in the system. Use this service to either get users details or remove users. In order to add new users please use Section 6.217, “Users”.

Expand
Table 6.662. Methods summary
NameSummary

get

Gets the system user information.

remove

Removes the system user.

6.216.1. get GET
Copiar enlace

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>
Expand
Table 6.663. Parameters summary
NameTypeDirectionSummary

user

User

Out

The system user.

6.216.2. remove DELETE
Copiar enlace

Removes the system user.

Usage: 

DELETE /ovirt-engine/api/users/1234
Expand
Table 6.664. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.217. Users
Copiar enlace

A service to manage the users in the system.

Expand
Table 6.665. Methods summary
NameSummary

add

Add user from a directory service.

list

List all the users in the system.

6.217.1. add POST
Copiar enlace

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>
Expand
Table 6.666. Parameters summary
NameTypeDirectionSummary

user

User

In/Out

 

6.217.2. list GET
Copiar enlace

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>
Expand
Table 6.667. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

max

Integer

In

Sets the maximum number of users to return.

search

String

In

A query string used to restrict the returned users.

users

User[]

Out

The list of users.

6.217.2.1. case_sensitive
Copiar enlace

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.

6.217.2.2. max
Copiar enlace

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

6.218. VirtualFunctionAllowedNetwork
Copiar enlace

Expand
Table 6.668. Methods summary
NameSummary

get

 

remove

 

6.218.1. get GET
Copiar enlace

Expand
Table 6.669. Parameters summary
NameTypeDirectionSummary

network

Network

Out

 

6.218.2. remove DELETE
Copiar enlace

Expand
Table 6.670. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.219. VirtualFunctionAllowedNetworks
Copiar enlace

Expand
Table 6.671. Methods summary
NameSummary

add

 

list

 

6.219.1. add POST
Copiar enlace

Expand
Table 6.672. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

 

6.219.2. list GET
Copiar enlace

Expand
Table 6.673. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

 
6.219.2.1. max
Copiar enlace

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

6.220. Vm
Copiar enlace

Expand
Table 6.674. Methods summary
NameSummary

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 a virtual machine to an export domain.

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

 

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

 

6.220.1. cancelmigration POST
Copiar enlace

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/>
Expand
Table 6.675. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the migration should cancelled asynchronously.

6.220.2. clone POST
Copiar enlace

Expand
Table 6.676. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the clone should be performed asynchronously.

vm

Vm

In

 

6.220.3. commitsnapshot POST
Copiar enlace

Permanently restores the virtual machine to the state of the previewed snapshot.

See the preview_snapshot operation for details.

Expand
Table 6.677. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the snapshots should be committed asynchronously.

6.220.4. detach POST
Copiar enlace

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/>
Expand
Table 6.678. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the detach action should be performed asynchronously.

6.220.5. export POST
Copiar enlace

Exports a virtual machine 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>
Expand
Table 6.679. Parameters summary
NameTypeDirectionSummary

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

 

6.220.6. freezefilesystems POST
Copiar enlace

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/>
Expand
Table 6.680. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the freeze should be performed asynchronously.

6.220.7. get GET
Copiar enlace

Retrieves the description of the virtual machine.

Expand
Table 6.681. Parameters summary
NameTypeDirectionSummary

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.

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.

vm

Vm

Out

Description of the virtual machine.

6.220.7.1. all_content
Copiar enlace

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
Note

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.

6.220.7.2. next_run
Copiar enlace

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

6.220.8. logon POST
Copiar enlace

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/>
Expand
Table 6.682. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the logon should be performed asynchronously.

6.220.9. maintenance POST
Copiar enlace

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>
Expand
Table 6.683. Parameters summary
NameTypeDirectionSummary

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.

6.220.10. migrate POST
Copiar enlace

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>
Expand
Table 6.684. Parameters summary
NameTypeDirectionSummary

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.

6.220.10.1. cluster
Copiar enlace

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.

6.220.10.2. force
Copiar enlace

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.

6.220.10.3. host
Copiar enlace

Specifies a specific host that the virtual machine should migrate to. This is an optional parameter. By default, the Red Hat Virtualization Manager 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.

6.220.11. previewsnapshot POST
Copiar enlace

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.

Expand
Table 6.685. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the preview should be performed asynchronously.

disks

Disk[]

In

 

restore_memory

Boolean

In

 

snapshot

Snapshot

In

 

vm

Vm

In

 

6.220.12. reboot POST
Copiar enlace

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/>
Expand
Table 6.686. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reboot should be performed asynchronously.

6.220.13. remove DELETE
Copiar enlace

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
Expand
Table 6.687. Parameters summary
NameTypeDirectionSummary

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.

6.220.13.1. force
Copiar enlace

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.

6.220.14. reordermacaddresses POST
Copiar enlace

Expand
Table 6.688. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.220.15. shutdown POST
Copiar enlace

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/>
Expand
Table 6.689. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the shutdown should be performed asynchronously.

6.220.16. start POST
Copiar enlace

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/>
Expand
Table 6.690. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the start action should be performed asynchronously.

filter

Boolean

In

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

pause

Boolean

In

If set to true, start the virtual machine in paused mode.

use_cloud_init

Boolean

In

If set to true, the initialization type is set to cloud-init.

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.

6.220.16.1. pause
Copiar enlace

If set to true, start the virtual machine in paused mode. The default is false.

6.220.16.2. use_cloud_init
Copiar enlace

If set to true, the initialization type is set to cloud-init. The default value is false. See this for details.

6.220.16.3. use_sysprep
Copiar enlace

If set to true, the initialization type is set to Sysprep. The default value is false. See this for details.

6.220.16.4. vm
Copiar enlace

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.

6.220.17. stop POST
Copiar enlace

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/>
Expand
Table 6.691. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the stop action should be performed asynchronously.

6.220.18. suspend POST
Copiar enlace

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/>
Expand
Table 6.692. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the suspend action should be performed asynchronously.

6.220.19. thawfilesystems POST
Copiar enlace

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/>
Expand
Table 6.693. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the thaw file systems action should be performed asynchronously.

6.220.20. ticket POST
Copiar enlace

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

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
Expand
Table 6.694. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the generation of the ticket should be performed asynchronously.

ticket

Ticket

In/Out

 

6.220.21. undosnapshot POST
Copiar enlace

Restores the virtual machine to the state it had before previewing the snapshot.

See the preview_snapshot operation for details.

Expand
Table 6.695. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the undo snapshot action should be performed asynchronously.

6.220.22. update PUT
Copiar enlace

Expand
Table 6.696. Parameters summary
NameTypeDirectionSummary

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

 
6.220.22.1. next_run
Copiar enlace

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.

6.221. VmApplication
Copiar enlace

A service that provides information about an application installed in a virtual machine.

Expand
Table 6.697. Methods summary
NameSummary

get

Returns the information about the application.

6.221.1. get GET
Copiar enlace

Returns the information about the application.

Expand
Table 6.698. Parameters summary
NameTypeDirectionSummary

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.

6.221.1.1. application
Copiar enlace

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>

6.222. VmApplications
Copiar enlace

A service that provides information about applications installed in a virtual machine.

Expand
Table 6.699. Methods summary
NameSummary

list

Returns a list of applications installed in the virtual machine.

6.222.1. list GET
Copiar enlace

Returns a list of applications installed in the virtual machine.

Expand
Table 6.700. Parameters summary
NameTypeDirectionSummary

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.

max

Integer

In

Sets the maximum number of applications to return.

6.222.1.1. applications
Copiar enlace

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>
6.222.1.2. max
Copiar enlace

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

6.223. VmCdrom
Copiar enlace

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.

Expand
Table 6.701. Methods summary
NameSummary

get

Returns the information about this CDROM device.

update

Updates the information about this CDROM device.

6.223.1. get GET
Copiar enlace

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>
Expand
Table 6.702. Parameters summary
NameTypeDirectionSummary

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.

6.223.1.1. current
Copiar enlace

Indicates if the operation should return the information for the currently running virtual machine. This parameter is optional, and the default value is false.

6.223.2. update PUT
Copiar enlace

Updates the information about this CDROM device.

It allows to change or eject the disk by changing the value of the file attribute. For example, to insert or change the disk send a request like this: 

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000

The body should contain the new value for the file attribute: 

<cdrom>
  <file id="mycd.iso"/>
</cdrom>

The value of the id attribute, mycd.iso in this example, should correspond to a file available in an attached ISO storage domain.

To eject the disk use a file with an empty id: 

<cdrom>
  <file id=""/>
</cdrom>

By default the above operations change permanently the disk that will be visible to the virtual machine after the next boot, but they don’t have any effect on the currently running virtual machine. If you want to change the disk that is visible to the current running virtual machine, add the current=true parameter. For example, to eject the current disk send a request like this: 

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000?current=true

With a request body like this: 

<cdrom>
  <file id=""/>
</cdrom>
Important

The changes made with the current=true parameter are never persisted, so they won’t have any effect after the virtual machine is rebooted.

Expand
Table 6.703. Parameters summary
NameTypeDirectionSummary

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.

6.223.2.1. current
Copiar enlace

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.

6.224. VmCdroms
Copiar enlace

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.

Expand
Table 6.704. Methods summary
NameSummary

list

Returns the list of CDROM devices of the virtual machine.

6.224.1. list GET
Copiar enlace

Returns the list of CDROM devices of the virtual machine.

Expand
Table 6.705. Parameters summary
NameTypeDirectionSummary

cdroms

Cdrom[]

Out

The list of CDROM devices of the virtual machine.

max

Integer

In

Sets the maximum number of CDROMs to return.

6.224.1.1. max
Copiar enlace

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

6.225. VmDisk
Copiar enlace

Expand
Table 6.706. Methods summary
NameSummary

activate

 

deactivate

 

export

 

get

 

move

 

remove

Detach the disk from the virtual machine.

update

 

6.225.1. activate POST
Copiar enlace

Expand
Table 6.707. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.225.2. deactivate POST
Copiar enlace

Expand
Table 6.708. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

6.225.3. export POST
Copiar enlace

Expand
Table 6.709. Parameters summary
NameTypeDirectionSummary

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.

6.225.4. get GET
Copiar enlace

Expand
Table 6.710. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.225.5. move POST
Copiar enlace

Expand
Table 6.711. Parameters summary
NameTypeDirectionSummary

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.

6.225.6. remove DELETE
Copiar enlace

Detach the disk from the virtual machine.

Note

In version 3 of the API this used to also remove the disk completely from the system, but starting with version 4 it doesn’t. If you need to remove it completely use the remove method of the top level disk service.

Expand
Table 6.712. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.225.7. update PUT
Copiar enlace

Expand
Table 6.713. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

disk

Disk

In/Out

 

6.226. VmDisks
Copiar enlace

Expand
Table 6.714. Methods summary
NameSummary

add

 

list

 

6.226.1. add POST
Copiar enlace

Expand
Table 6.715. Parameters summary
NameTypeDirectionSummary

disk

Disk

In/Out

 

6.226.2. list GET
Copiar enlace

Expand
Table 6.716. Parameters summary
NameTypeDirectionSummary

disks

Disk[]

Out

 

max

Integer

In

Sets the maximum number of disks to return.

6.226.2.1. max
Copiar enlace

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

6.227. VmGraphicsConsole
Copiar enlace

Expand
Table 6.717. Methods summary
NameSummary

get

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

6.227.1. get GET
Copiar enlace

Gets graphics console configuration of the virtual machine.

Expand
Table 6.718. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

Out

The information about the graphics console of the virtual machine.

current

Boolean

In

Use the following query to obtain the current run-time configuration of the graphics console.

6.227.1.1. current
Copiar enlace

Use the following query to obtain the current run-time configuration of the graphics console. 

GET /ovit-engine/api/vms/123/graphicsconsoles/456?current=true

The default value is false.

6.227.2. proxyticket POST
Copiar enlace

Expand
Table 6.719. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the generation of the ticket should be performed asynchronously.

proxy_ticket

ProxyTicket

Out

 

6.227.3. remoteviewerconnectionfile POST
Copiar enlace

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
Expand
Table 6.720. Parameters summary
NameTypeDirectionSummary

remote_viewer_connection_file

String

Out

Contains the file which is compatible with remote-viewer client.

6.227.3.1. remote_viewer_connection_file
Copiar enlace

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.

6.227.4. remove DELETE
Copiar enlace

Remove the graphics console from the virtual machine.

Expand
Table 6.721. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.227.5. ticket POST
Copiar enlace

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>
Expand
Table 6.722. Parameters summary
NameTypeDirectionSummary

ticket

Ticket

In/Out

The generated ticket that can be used to access this console.

6.228. VmGraphicsConsoles
Copiar enlace

Expand
Table 6.723. Methods summary
NameSummary

add

Add new graphics console to the virtual machine.

list

Lists all the configured graphics consoles of the virtual machine.

6.228.1. add POST
Copiar enlace

Add new graphics console to the virtual machine.

Expand
Table 6.724. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

In/Out

 

6.228.2. list GET
Copiar enlace

Lists all the configured graphics consoles of the virtual machine.

Expand
Table 6.725. Parameters summary
NameTypeDirectionSummary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the virtual machine.

current

Boolean

In

Use the following query to obtain the current run-time configuration of the graphics consoles.

max

Integer

In

Sets the maximum number of consoles to return.

6.228.2.1. current
Copiar enlace

Use the following query to obtain the current run-time configuration of the graphics consoles. 

GET /ovirt-engine/api/vms/123/graphicsconsoles?current=true

The default value is false.

6.228.2.2. max
Copiar enlace

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

6.229. VmHostDevice
Copiar enlace

A service to manage individual host device attached to a virtual machine.

Expand
Table 6.726. Methods summary
NameSummary

get

Retrieve information about particular host device attached to given virtual machine.

remove

Remove the attachment of this host device from given virtual machine.

6.229.1. get GET
Copiar enlace

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>
Expand
Table 6.727. Parameters summary
NameTypeDirectionSummary

device

HostDevice

Out

Retrieved information about the host device attached to given virtual machine.

6.229.2. remove DELETE
Copiar enlace

Remove the attachment of this host device from given virtual machine.

Note

In case this device serves as an IOMMU placeholder, it cannot be removed (remove will result only in setting its placeholder flag to true). Note that all IOMMU placeholder devices will be removed automatically as soon as there will be no more non-placeholder devices (all devices from given IOMMU group are detached). 

DELETE /ovirt-engine/api/vms/123/hostdevices/456
Expand
Table 6.728. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.230. VmHostDevices
Copiar enlace

A service to manage host devices attached to a virtual machine.

Expand
Table 6.729. Methods summary
NameSummary

add

Attach target device to given virtual machine.

list

List the host devices assigned to given virtual machine.

6.230.1. add POST
Copiar enlace

Attach target device to given virtual machine.

Example: 

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

With request body of type HostDevice, for example 

<host_device id="123" />
Note

A necessary precondition for a successful host device attachment is that the virtual machine must be pinned to exactly one host. The device ID is then taken relative to this host.

Note

Attachment of a PCI device that is part of a bigger IOMMU group will result in attachment of the remaining devices from that IOMMU group as "placeholders". These devices are then identified using the placeholder attribute of the HostDevice type set to true.

In case you want attach a device that already serves as an IOMMU placeholder, simply issue an explicit Add operation for it, and its placeholder flag will be cleared, and the device will be accessible to the virtual machine.

Expand
Table 6.730. Parameters summary
NameTypeDirectionSummary

device

HostDevice

In/Out

The host device to be attached to given virtual machine.

6.230.2. list GET
Copiar enlace

List the host devices assigned to given virtual machine.

Expand
Table 6.731. Parameters summary
NameTypeDirectionSummary

device

HostDevice[]

Out

Retrieved list of host devices attached to given virtual machine.

max

Integer

In

Sets the maximum number of devices to return.

6.230.2.1. max
Copiar enlace

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

6.231. VmNic
Copiar enlace

Expand
Table 6.732. Methods summary
NameSummary

activate

 

deactivate

 

get

 

remove

Removes the NIC.

update

Updates the NIC.

6.231.1. activate POST
Copiar enlace

Expand
Table 6.733. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.231.2. deactivate POST
Copiar enlace

Expand
Table 6.734. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

6.231.3. get GET
Copiar enlace

Expand
Table 6.735. Parameters summary
NameTypeDirectionSummary

nic

Nic

Out

 

6.231.4. remove DELETE
Copiar enlace

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
Important

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Windows Server 2008 and
  • Windows Server 2003
Expand
Table 6.736. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.231.5. update PUT
Copiar enlace

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

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Windows Server 2008 and
  • Windows Server 2003
Expand
Table 6.737. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

 

6.232. VmNics
Copiar enlace

Expand
Table 6.738. Methods summary
NameSummary

add

Adds a NIC to the virtual machine.

list

 

6.232.1. add POST
Copiar enlace

Adds a NIC to the virtual machine.

The following example adds a network interface named mynic using virtio and the ovirtmgmt network to the virtual machine. 

POST /ovirt-engine/api/vms/123/nics
 
<nic>
  <interface>virtio</interface>
  <name>mynic</name>
  <network>
    <name>ovirtmgmt</name>
  </network>
</nic>

The following example sends that request using curl: 

curl \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \
--cacert /etc/pki/ovirt-engine/ca.pem \
--data '
<nic>
  <name>mynic</name>
  <network>
    <name>ovirtmgmt</name>
  </network>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/123/nics
Important

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Windows Server 2008 and
  • Windows Server 2003
Expand
Table 6.739. Parameters summary
NameTypeDirectionSummary

nic

Nic

In/Out

 

6.232.2. list GET
Copiar enlace

Expand
Table 6.740. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

 
6.232.2.1. max
Copiar enlace

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

6.233. VmNumaNode
Copiar enlace

Expand
Table 6.741. Methods summary
NameSummary

get

 

remove

Removes a virtual NUMA node.

update

Updates a virtual NUMA node.

6.233.1. get GET
Copiar enlace

Expand
Table 6.742. Parameters summary
NameTypeDirectionSummary

node

VirtualNumaNode

Out

 

6.233.2. remove DELETE
Copiar enlace

Removes a virtual NUMA node.

An example of removing a virtual NUMA node: 

DELETE /ovirt-engine/api/vms/123/numanodes/456
Expand
Table 6.743. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.233.3. update PUT
Copiar enlace

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>
Expand
Table 6.744. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

node

VirtualNumaNode

In/Out

 

6.234. VmNumaNodes
Copiar enlace

Expand
Table 6.745. Methods summary
NameSummary

add

Creates a new virtual NUMA node for the virtual machine.

list

Lists virtual NUMA nodes of a virtual machine.

6.234.1. add POST
Copiar enlace

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>
</vm_numa_node>
Expand
Table 6.746. Parameters summary
NameTypeDirectionSummary

node

VirtualNumaNode

In/Out

 

6.234.2. list GET
Copiar enlace

Lists virtual NUMA nodes of a virtual machine.

Expand
Table 6.747. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of nodes to return.

nodes

VirtualNumaNode[]

Out

 
6.234.2.1. max
Copiar enlace

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

6.235. VmPool
Copiar enlace

A service to manage a virtual machines pool.

Expand
Table 6.748. Methods summary
NameSummary

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.

6.235.1. allocatevm POST
Copiar enlace

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/>
Expand
Table 6.749. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the allocation should be performed asynchronously.

6.235.2. get GET
Copiar enlace

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>
Expand
Table 6.750. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

pool

VmPool

Out

Retrieved virtual machines pool.

6.235.3. remove DELETE
Copiar enlace

Removes a virtual machine pool. 

DELETE /ovirt-engine/api/vmpools/123
Expand
Table 6.751. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.235.4. update PUT
Copiar enlace

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>
Expand
Table 6.752. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

pool

VmPool

In/Out

The virtual machine pool that is being updated.

6.236. VmPools
Copiar enlace

Provides read-write access to virtual machines pools.

Expand
Table 6.753. Methods summary
NameSummary

add

Creates a new virtual machine pool.

list

Get a list of available virtual machines pools.

6.236.1. add POST
Copiar enlace

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>
Expand
Table 6.754. Parameters summary
NameTypeDirectionSummary

pool

VmPool

In/Out

Pool to add.

6.236.2. list GET
Copiar enlace

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>
Expand
Table 6.755. Parameters summary
NameTypeDirectionSummary

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.

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.

6.236.2.1. case_sensitive
Copiar enlace

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.

6.236.2.2. max
Copiar enlace

Sets the maximum number of pools to return. If this value is not specified, all of the pools are returned.

6.237. VmReportedDevice
Copiar enlace

Expand
Table 6.756. Methods summary
NameSummary

get

 

6.237.1. get GET
Copiar enlace

Expand
Table 6.757. Parameters summary
NameTypeDirectionSummary

reported_device

ReportedDevice

Out

 

6.238. VmReportedDevices
Copiar enlace

Expand
Table 6.758. Methods summary
NameSummary

list

 

6.238.1. list GET
Copiar enlace

Expand
Table 6.759. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of devices to return.

reported_device

ReportedDevice[]

Out

 
6.238.1.1. max
Copiar enlace

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

6.239. VmSession
Copiar enlace

Expand
Table 6.760. Methods summary
NameSummary

get

 

6.239.1. get GET
Copiar enlace

Expand
Table 6.761. Parameters summary
NameTypeDirectionSummary

session

Session

Out

 

6.240. VmSessions
Copiar enlace

Provides information about virtual machine user sessions.

Expand
Table 6.762. Methods summary
NameSummary

list

Lists all user sessions for this virtual machine.

6.240.1. list GET
Copiar enlace

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>
Expand
Table 6.763. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of sessions to return.

sessions

Session[]

Out

 
6.240.1.1. max
Copiar enlace

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

6.241. VmWatchdog
Copiar enlace

A service managing a watchdog on virtual machines.

Expand
Table 6.764. Methods summary
NameSummary

get

Returns the information about the watchdog.

remove

Removes the watchdog from the virtual machine.

update

Updates the information about the watchdog.

6.241.1. get GET
Copiar enlace

Returns the information about the watchdog.

Expand
Table 6.765. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

Out

The information about the watchdog.

6.241.1.1. watchdog
Copiar enlace

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>

6.241.2. remove DELETE
Copiar enlace

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
Expand
Table 6.766. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.241.3. update PUT
Copiar enlace

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>
Expand
Table 6.767. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

The information about the watchdog.

6.241.3.1. watchdog
Copiar enlace

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.

6.242. VmWatchdogs
Copiar enlace

Lists the watchdogs of a virtual machine.

Expand
Table 6.768. Methods summary
NameSummary

add

Adds new watchdog to the virtual machine.

list

The list of watchdogs of the virtual machine.

6.242.1. add POST
Copiar enlace

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>
Expand
Table 6.769. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

In/Out

The information about the watchdog.

6.242.1.1. watchdog
Copiar enlace

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.

6.242.2. list GET
Copiar enlace

The list of watchdogs of the virtual machine.

Expand
Table 6.770. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of watchdogs to return.

watchdogs

Watchdog[]

Out

The information about the watchdog.

6.242.2.1. max
Copiar enlace

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

6.242.2.2. watchdogs
Copiar enlace

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>

6.243. Vms
Copiar enlace

Expand
Table 6.771. Methods summary
NameSummary

add

Creates a new virtual machine.

list

 

6.243.1. add POST
Copiar enlace

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.

Expand
Table 6.772. Parameters summary
NameTypeDirectionSummary

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.

vm

Vm

In/Out

 
6.243.1.1. clone
Copiar enlace

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

When this parameter is true the permissions of the template will also be copied, as when using clone_permissions=true.

6.243.1.2. clone_permissions
Copiar enlace

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>

6.243.2. list GET
Copiar enlace

Expand
Table 6.773. Parameters summary
NameTypeDirectionSummary

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.

max

Integer

In

The maximum number of results to return.

search

String

In

A query string used to restrict the returned virtual machines.

vms

Vm[]

Out

 
6.243.2.1. all_content
Copiar enlace

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

By default the following attributes are excluded:

  • console
  • initialization.configuration.data - The OVF document describing the virtual machine.
  • rng_source
  • soundcard
  • virtio_scsi

For example, to retrieve the complete representation of the virtual machines send a request like this: 

GET /ovirt-engine/api/vms?all_content=true
Note

The reason for not including these attributes is performance: they are seldom used and they require additional queries to the database. So try to use the this parameter only when it is really needed.

6.243.2.2. case_sensitive
Copiar enlace

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.

6.244. VnicProfile
Copiar enlace

This service manages a vNIC profile.

Expand
Table 6.774. Methods summary
NameSummary

get

Retrieves details about a vNIC profile.

remove

Removes the vNIC profile.

update

Updates details of a vNIC profile.

6.244.1. get GET
Copiar enlace

Retrieves details about a vNIC profile.

Expand
Table 6.775. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

Out

 

6.244.2. remove DELETE
Copiar enlace

Removes the vNIC profile.

Expand
Table 6.776. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.244.3. update PUT
Copiar enlace

Updates details of a vNIC profile.

Expand
Table 6.777. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

VnicProfile

In/Out

The vNIC profile that is being updated.

6.245. VnicProfiles
Copiar enlace

This service manages the collection of all vNIC profiles.

Expand
Table 6.778. Methods summary
NameSummary

add

Add a vNIC profile.

list

List all vNIC profiles.

6.245.1. add POST
Copiar enlace

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 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>
Expand
Table 6.779. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

In/Out

The vNIC profile that is being added.

6.245.2. list GET
Copiar enlace

List all vNIC profiles.

Expand
Table 6.780. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

Out

The list of all vNIC profiles.

6.245.2.1. max
Copiar enlace

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

6.246. Weight
Copiar enlace

Expand
Table 6.781. Methods summary
NameSummary

get

 

remove

 

6.246.1. get GET
Copiar enlace

Expand
Table 6.782. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

weight

Weight

Out

 

6.246.2. remove DELETE
Copiar enlace

Expand
Table 6.783. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.247. Weights
Copiar enlace

Expand
Table 6.784. Methods summary
NameSummary

add

 

list

 

6.247.1. add POST
Copiar enlace

Expand
Table 6.785. Parameters summary
NameTypeDirectionSummary

weight

Weight

In/Out

 

6.247.2. list GET
Copiar enlace

Expand
Table 6.786. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of weights to return.

weights

Weight[]

Out

 
6.247.2.1. max
Copiar enlace

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

Chapter 7. Types
Copiar enlace

This section enumerates all the data types that are available in the API.

7.1. AccessProtocol enum
Copiar enlace

Expand
Table 7.1. Values summary
NameSummary

cifs

 

gluster

 

nfs

 

7.2. Action struct
Copiar enlace

Expand
Table 7.2. Attributes summary
NameTypeSummary

allow_partial_import

Boolean

 

async

Boolean

 

bricks

GlusterBrick[]

 

certificates

Certificate[]

 

check_connectivity

Boolean

 

clone

Boolean

 

cluster

Cluster

 

collapse_snapshots

Boolean

 

comment

String

Free text containing comments about this object.

connectivity_timeout

Integer

 

data_center

DataCenter

 

deploy_hosted_engine

Boolean

 

description

String

A human-readable description in plain text.

details

GlusterVolumeProfileDetails

 

discard_snapshots

Boolean

 

disk

Disk

 

disks

Disk[]

 

exclusive

Boolean

 

fault

Fault

 

fence_type

String

 

filter

Boolean

 

fix_layout

Boolean

 

force

Boolean

 

grace_period

GracePeriod

 

host

Host

 

id

String

A unique identifier.

image

String

 

import_as_template

Boolean

 

is_attached

Boolean

 

iscsi

IscsiDetails

 

iscsi_targets

String[]

 

job

Job

 

logical_units

LogicalUnit[]

 

maintenance_enabled

Boolean

 

modified_bonds

HostNic[]

 

modified_labels

NetworkLabel[]

 

modified_network_attachments

NetworkAttachment[]

 

name

String

A human-readable name in plain text.

option

Option

 

pause

Boolean

 

power_management

PowerManagement

 

proxy_ticket

ProxyTicket

 

reason

String

 

reassign_bad_macs

Boolean

 

remote_viewer_connection_file

String

 

removed_bonds

HostNic[]

 

removed_labels

NetworkLabel[]

 

removed_network_attachments

NetworkAttachment[]

 

resolution_type

String

 

restore_memory

Boolean

 

root_password

String

 

snapshot

Snapshot

 

ssh

Ssh

 

status

String

 

stop_gluster_service

Boolean

 

storage_domain

StorageDomain

 

storage_domains

StorageDomain[]

 

succeeded

Boolean

 

synchronized_network_attachments

NetworkAttachment[]

 

template

Template

 

ticket

Ticket

 

undeploy_hosted_engine

Boolean

 

use_cloud_init

Boolean

 

use_sysprep

Boolean

 

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

 

vm

Vm

 

vnic_profile_mappings

VnicProfileMapping[]

 

7.3. AffinityGroup struct
Copiar enlace

An affinity group represents a group of virtual machines with a defined relationship.

Expand
Table 7.3. Attributes summary
NameTypeSummary

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.

vms_rule

AffinityRule

Specifies the affinity rule applied to virtual machines that are members of this affinity group.

7.3.1. enforcing
Copiar enlace

Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines that are members of that affinity group.

Warning

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.

7.3.2. positive
Copiar enlace

Specifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are members of that affinity group.

Warning

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.

Expand
Table 7.4. Links summary
NameTypeSummary

cluster

Cluster

A reference to the cluster to which the affinity group applies.

hosts

Host[]

A list of all hosts assigned to this affinity group.

vms

Vm[]

A list of all virtual machines assigned to this affinity group.

7.4. AffinityLabel struct
Copiar enlace

The affinity label can influence virtual machine scheduling. It is most frequently used to create a sub-cluster from the available hosts.

Expand
Table 7.5. Attributes summary
NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

read_only

Boolean

The read_only property marks a label that can not be modified.

7.4.1. read_only
Copiar enlace

The read_only property marks a label that can not be modified. This is usually the case when listing internally-generated labels.

Expand
Table 7.6. Links summary
NameTypeSummary

hosts

Host[]

A list of hosts that were labeled using this scheduling label.

vms

Vm[]

A list of virtual machines that were labeled using this scheduling label.

7.5. AffinityRule struct
Copiar enlace

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.

Expand
Table 7.7. Attributes summary
NameTypeSummary

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.

7.5.1. enabled
Copiar enlace

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.

7.5.2. enforcing
Copiar enlace

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.

7.5.3. positive
Copiar enlace

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.

7.6. Agent struct
Copiar enlace

Type representing a fence agent.

Expand
Table 7.8. Attributes summary
NameTypeSummary

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.

Expand
Table 7.9. Links summary
NameTypeSummary

host

Host

Reference to the host service.

7.7. AgentConfiguration struct
Copiar enlace

Expand
Table 7.10. Attributes summary
NameTypeSummary

address

String

 

broker_type

MessageBrokerType

 

network_mappings

String

 

password

String

 

port

Integer

 

username

String

 

7.8. Api struct
Copiar enlace

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>
Expand
Table 7.11. Attributes summary
NameTypeSummary

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.

7.9. ApiSummary struct
Copiar enlace

A summary containing the total number of relevant objects, such as virtual machines, hosts, and storage domains.

Expand
Table 7.12. Attributes summary
NameTypeSummary

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.

7.10. ApiSummaryItem struct
Copiar enlace

This type contains an item of the API summary. Each item contains the total and active number of some kind of object.

Expand
Table 7.13. Attributes summary
NameTypeSummary

active

Integer

The total number of active objects.

total

Integer

The total number of objects.

7.11. Application struct
Copiar enlace

Expand
Table 7.14. Attributes summary
NameTypeSummary

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.

Expand
Table 7.15. Links summary
NameTypeSummary

vm

Vm

 

7.12. Architecture enum
Copiar enlace

Expand
Table 7.16. Values summary
NameSummary

ppc64

 

undefined

 

x86_64

 

7.13. AuthorizedKey struct
Copiar enlace

Expand
Table 7.17. Attributes summary
NameTypeSummary

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.

Expand
Table 7.18. Links summary
NameTypeSummary

user

User

 

7.14. AutoNumaStatus enum
Copiar enlace

Expand
Table 7.19. Values summary
NameSummary

disable

 

enable

 

unknown

 

7.15. Balance struct
Copiar enlace

Expand
Table 7.20. Attributes summary
NameTypeSummary

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.

Expand
Table 7.21. Links summary
NameTypeSummary

scheduling_policy

SchedulingPolicy

 

scheduling_policy_unit

SchedulingPolicyUnit

 

7.16. Bios struct
Copiar enlace

Expand
Table 7.22. Attributes summary
NameTypeSummary

boot_menu

BootMenu

 

7.17. BlockStatistic struct
Copiar enlace

Expand
Table 7.23. Attributes summary
NameTypeSummary

statistics

Statistic[]

 

7.18. Bonding struct
Copiar enlace

Represents a network interfaces bond.

Expand
Table 7.24. Attributes summary
NameTypeSummary

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.

7.18.1. ad_partner_mac
Copiar enlace

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.

7.18.2. options
Copiar enlace

A list of option elements for a bonded interface. Each option contains property name and value attributes. Only required when adding bonded interfaces.

7.18.3. slaves
Copiar enlace

A list of slave NICs for a bonded interface. Only required when adding bonded interfaces.

Expand
Table 7.25. Links summary
NameTypeSummary

active_slave

HostNic

The active_slave property of the bond in modes that support it (active-backup, balance-alb and balance-tlb).

7.19. Bookmark struct
Copiar enlace

Expand
Table 7.26. Attributes summary
NameTypeSummary

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

 

7.20. Boot struct
Copiar enlace

Expand
Table 7.27. Attributes summary
NameTypeSummary

devices

BootDevice[]

 

7.21. BootDevice enum
Copiar enlace

Expand
Table 7.28. Values summary
NameSummary

cdrom

 

hd

 

network

 

7.22. BootMenu struct
Copiar enlace

Expand
Table 7.29. Attributes summary
NameTypeSummary

enabled

Boolean

 

7.23. BootProtocol enum
Copiar enlace

Defines the options of the IP address assignment method to a NIC.

Expand
Table 7.30. Values summary
NameSummary

autoconf

Stateless address auto-configuration.

dhcp

Dynamic host configuration protocol.

none

No address configuration.

static

Statically-defined address, mask and gateway.

7.23.1. autoconf
Copiar enlace

Stateless address auto-configuration.

The mechanism is defined by RFC 4862. Please refer to this wikipedia article for more information.

Note

The value is valid for IPv6 addresses only.

7.23.2. dhcp
Copiar enlace

Dynamic host configuration protocol.

Please refer to this wikipedia article for more information.

7.24. BrickProfileDetail struct
Copiar enlace

Expand
Table 7.31. Attributes summary
NameTypeSummary

profile_details

ProfileDetail[]

 
Expand
Table 7.32. Links summary
NameTypeSummary

brick

GlusterBrick

 

7.25. Cdrom struct
Copiar enlace

Expand
Table 7.33. Attributes summary
NameTypeSummary

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.

Expand
Table 7.34. Links summary
NameTypeSummary

instance_type

InstanceType

Optionally references to an instance type the device is used by.

template

Template

Optionally references to a template the device is used by.

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

7.26. Certificate struct
Copiar enlace

Expand
Table 7.35. Attributes summary
NameTypeSummary

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

 

7.27. CloudInit struct
Copiar enlace

Expand
Table 7.36. Attributes summary
NameTypeSummary

authorized_keys

AuthorizedKey[]

 

files

File[]

 

host

Host

 

network_configuration

NetworkConfiguration

 

regenerate_ssh_keys

Boolean

 

timezone

String

 

users

User[]

 

7.28. Cluster struct
Copiar enlace

Type representation of a cluster.

A JSON representation of a cluster 

{
  "cluster" : [ {
    "ballooning_enabled" : "false",
    "cpu" : {
      "architecture" : "x86_64",
      "type" : "Intel SandyBridge Family"
    },
    "custom_scheduling_policy_properties" : {
      "property" : [ {
        "name" : "HighUtilization",
        "value" : "80"
      }, {
        "name" : "CpuOverCommitDurationMinutes",
        "value" : "2"
      } ]
    },
    "error_handling" : {
      "on_error" : "migrate"
    },
    "fencing_policy" : {
      "enabled" : "true",
      "skip_if_connectivity_broken" : {
        "enabled" : "false",
        "threshold" : "50"
      },
      "skip_if_gluster_bricks_up" : "false",
      "skip_if_gluster_quorum_not_met" : "false",
      "skip_if_sd_active" : {
        "enabled" : "false"
      }
    },
    "gluster_service" : "false",
    "ha_reservation" : "false",
    "ksm" : {
      "enabled" : "true",
      "merge_across_nodes" : "true"
    },
    "maintenance_reason_required" : "false",
    "memory_policy" : {
      "over_commit" : {
        "percent" : "100"
      },
      "transparent_hugepages" : {
        "enabled" : "true"
      }
    },
    "migration" : {
      "auto_converge" : "inherit",
      "bandwidth" : {
        "assignment_method" : "auto"
      },
      "compressed" : "inherit",
      "policy" : {
        "id" : "00000000-0000-0000-0000-000000000000"
      }
    },
    "optional_reason" : "false",
    "required_rng_sources" : {
      "required_rng_source" : [ "random" ]
    },
    "switch_type" : "legacy",
    "threads_as_cores" : "false",
    "trusted_service" : "false",
    "tunnel_migration" : "false",
    "version" : {
      "major" : "4",
      "minor" : "1"
    },
    "virt_service" : "true",
    "data_center" : {
      "href" : "/ovirt-engine/api/datacenters/123",
      "id" : "123"
    },
    "mac_pool" : {
      "href" : "/ovirt-engine/api/macpools/456",
      "id" : "456"
    },
    "scheduling_policy" : {
      "href" : "/ovirt-engine/api/schedulingpolicies/789",
      "id" : "789"
    },
    "actions" : {
      "link" : [ {
        "href" : "/ovirt-engine/api/clusters/234/resetemulatedmachine",
        "rel" : "resetemulatedmachine"
      } ]
    },
    "name" : "Default",
    "description" : "The default server cluster",
    "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"
    } ]
  } ]
}
Expand
Table 7.37. Attributes summary
NameTypeSummary

ballooning_enabled

Boolean

 

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

Custom fencing policy can be defined for a cluster.

gluster_service

Boolean

 

gluster_tuned_profile

String

The name of the https://fedorahosted.

ha_reservation

Boolean

 

id

String

A unique identifier.

ksm

Ksm

 

maintenance_reason_required

Boolean

 

memory_policy

MemoryPolicy

 

migration

MigrationOptions

 

name

String

A human-readable name in plain text.

optional_reason

Boolean

 

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

Type of switch to be used by all networks in given cluster.

threads_as_cores

Boolean

 

trusted_service

Boolean

 

tunnel_migration

Boolean

 

version

Version

The compatibility version of the cluster.

virt_service

Boolean

 

7.28.1. custom_scheduling_policy_properties
Copiar enlace

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.

7.28.2. fencing_policy
Copiar enlace

Custom fencing policy can be defined for a cluster.

Here is an example: 

PUT /ovirt-engine/api/cluster/123

With request body: 

<cluster>
  <fencing_policy>
    <enabled>true</enabled>
    <skip_if_sd_active>
      <enabled>false</enabled>
    </skip_if_sd_active>
    <skip_if_connectivity_broken>
      <enabled>false</enabled>
      <threshold>50</threshold>
    </skip_if_connectivity_broken>
  </fencing_policy>
</cluster>

7.28.3. gluster_tuned_profile
Copiar enlace

The name of the tuned profile to set on all the hosts in the cluster. This is not mandatory and relevant only for clusters with gluster service.

7.28.4. required_rng_sources
Copiar enlace

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.

Important

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.

Important

Engine version 4.1 introduces a new RNG source urandom that replaces random RNG source in clusters with compatibility version 4.1 or higher.

7.28.5. version
Copiar enlace

The compatibility version of the cluster.

All hosts in this cluster must support at least this compatibility version.

For example: 

GET /ovirt-engine/api/clusters/123

Will respond: 

<cluster>
  ...
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  ...
</cluster>

To update the compatibility version, use: 

PUT /ovirt-engine/api/clusters/123

With a request body: 

<cluster>
  <version>
    <major>4</major>
    <minor>1</minor>
  </version>
</cluster>

In order to update the cluster compatibility version, all hosts in the cluster must support the new compatibility version.

Expand
Table 7.38. Links summary
NameTypeSummary

affinity_groups

AffinityGroup[]

 

cpu_profiles

CpuProfile[]

 

data_center

DataCenter

 

gluster_hooks

GlusterHook[]

 

gluster_volumes

GlusterVolume[]

 

mac_pool

MacPool

A reference to the MAC pool used by this cluster.

management_network

Network

 

network_filters

NetworkFilter[]

 

networks

Network[]

 

permissions

Permission[]

 

scheduling_policy

SchedulingPolicy

Reference to the default scheduling policy used by this cluster.

7.29. ClusterLevel struct
Copiar enlace

Describes the capabilities supported by a specific cluster level.

Expand
Table 7.39. Attributes summary
NameTypeSummary

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.

7.30. Configuration struct
Copiar enlace

Expand
Table 7.40. Attributes summary
NameTypeSummary

data

String

The document describing the virtual machine.

type

ConfigurationType

 

7.30.1. data
Copiar enlace

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>

7.31. ConfigurationType enum
Copiar enlace

Expand
Table 7.41. Values summary
NameSummary

ovf

 

7.32. Console struct
Copiar enlace

Expand
Table 7.42. Attributes summary
NameTypeSummary

enabled

Boolean

 

7.33. Core struct
Copiar enlace

Expand
Table 7.43. Attributes summary
NameTypeSummary

index

Integer

 

socket

Integer

 

7.34. Cpu struct
Copiar enlace

Expand
Table 7.44. Attributes summary
NameTypeSummary

architecture

Architecture

 

cores

Core[]

 

cpu_tune

CpuTune

 

level

Integer

 

mode

CpuMode

 

name

String

 

speed

Decimal

 

topology

CpuTopology

 

type

String

 

7.35. CpuMode enum
Copiar enlace

Expand
Table 7.45. Values summary
NameSummary

custom

 

host_model

 

host_passthrough

 

7.36. CpuProfile struct
Copiar enlace

Expand
Table 7.46. Attributes summary
NameTypeSummary

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.

Expand
Table 7.47. Links summary
NameTypeSummary

cluster

Cluster

 

permissions

Permission[]

 

qos

Qos

 

7.37. CpuTopology struct
Copiar enlace

Expand
Table 7.48. Attributes summary
NameTypeSummary

cores

Integer

 

sockets

Integer

 

threads

Integer

 

7.38. CpuTune struct
Copiar enlace

Expand
Table 7.49. Attributes summary
NameTypeSummary

vcpu_pins

VcpuPin[]

 

7.39. CpuType struct
Copiar enlace

Describes a supported CPU type.

Expand
Table 7.50. Attributes summary
NameTypeSummary

architecture

Architecture

The architecture of the CPU.

level

Integer

The level of the CPU type.

name

String

The name of the CPU type, for example Intel Conroe Family.

7.40. CreationStatus enum
Copiar enlace

Expand
Table 7.51. Values summary
NameSummary

complete

 

failed

 

in_progress

 

pending

 

7.41. CustomProperty struct
Copiar enlace

Expand
Table 7.52. Attributes summary
NameTypeSummary

name

String

 

regexp

String

 

value

String

 

7.42. DataCenter struct
Copiar enlace

Expand
Table 7.53. Attributes summary
NameTypeSummary

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.

7.42.1. version
Copiar enlace

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>
Expand
Table 7.54. Links summary
NameTypeSummary

clusters

Cluster[]

Reference to clusters inside this data center.

iscsi_bonds

IscsiBond[]

Reference to ISCSI bonds used by this data center.

mac_pool

MacPool

Reference to the MAC pool used by this data center.

networks

Network[]

Reference to networks attached to this data center.

permissions

Permission[]

Reference to permissions assigned to this data center.

qoss

Qos[]

Reference to quality of service used by this data center.

quotas

Quota[]

Reference to quotas assigned to this data center.

storage_domains

StorageDomain[]

Reference to storage domains attached to this data center.

7.43. DataCenterStatus enum
Copiar enlace

Expand
Table 7.55. Values summary
NameSummary

contend

 

maintenance

 

not_operational

 

problematic

 

uninitialized

 

up

 

7.44. Device struct
Copiar enlace

A device wraps links to potential parents of a device.

Expand
Table 7.56. Attributes summary
NameTypeSummary

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.

Expand
Table 7.57. Links summary
NameTypeSummary

instance_type

InstanceType

Optionally references to an instance type the device is used by.

template

Template

Optionally references to a template the device is used by.

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

7.45. Disk struct
Copiar enlace

Represents a virtual disk device.

Expand
Table 7.58. Attributes summary
NameTypeSummary

active

Boolean

Indicates if the disk is visible to the virtual machine.

actual_size

Integer

The actual size of the disk, in bytes.

alias

String

 

bootable

Boolean

Indicates if the disk is marked as bootable.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

format

DiskFormat

The underlying storage format.

id

String

A unique identifier.

image_id

String

 

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 not cause virtual machine to be paused and, instead, disk errors should be propagated to the the guest operating system.

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

 

shareable

Boolean

Indicates if the disk can be attached to multiple virtual machines.

sparse

Boolean

Indicates if the physical storage for the disk should not be preallocated.

status

DiskStatus

The status of the disk device.

storage_type

DiskStorageType

 

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

7.45.1. active
Copiar enlace

Indicates if the disk is visible to the virtual machine.

Important

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

7.45.2. actual_size
Copiar enlace

The actual size of the disk, in bytes.

The actual size is the number of bytes actually used by the disk, and it will be smaller than the provisioned size for disks that use the cow format.

7.45.3. bootable
Copiar enlace

Indicates if the disk is marked as bootable.

Important

This attribute only makes sense for disks that are actually connected to virtual machines, and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

7.45.4. initial_size
Copiar enlace

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.

7.45.5. interface
Copiar enlace

The type of interface driver used to connect the disk device to the virtual machine.

Important

This attribute only makes sense for disks that are actually connected to virtual machines, and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

7.45.6. provisioned_size
Copiar enlace

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

7.45.7. qcow_version
Copiar enlace

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 storage domain’s version which the disk is created on. Storage domains with version lower than V4 support QCOW2 volumes, while V4 storage domains also support QCOW2v3. For more information about features of the different QCOW versions, see here.

7.45.8. shareable
Copiar enlace

Indicates if the disk can be attached to multiple virtual machines.

Important

When a disk is attached to multiple virtual machines it is the responsibility of the guest operating systems of those virtual machines to coordinate access to it, to avoid corruption of the data, for example using a shared file system like GlusterFS or GFS.

7.45.9. wipe_after_delete
Copiar enlace

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.
Expand
Table 7.59. Links summary
NameTypeSummary

disk_profile

DiskProfile

 

instance_type

InstanceType

Optionally references to an instance type the device is used by.

openstack_volume_type

OpenStackVolumeType

 

permissions

Permission[]

 

quota

Quota

 

snapshot

Snapshot

 

statistics

Statistic[]

Statistics exposed by the disk.

storage_domain

StorageDomain

 

storage_domains

StorageDomain[]

The storage domains associated with this disk.

template

Template

Optionally references to a template the device is used by.

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

7.46. DiskAttachment struct
Copiar enlace

Describes how a disk is attached to a virtual machine.

Expand
Table 7.60. Attributes summary
NameTypeSummary

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.

7.46.1. active
Copiar enlace

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.

7.46.2. logical_name
Copiar enlace

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.

7.46.3. read_only
Copiar enlace

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>

7.46.4. uses_scsi_reservation
Copiar enlace

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.

Expand
Table 7.61. Links summary
NameTypeSummary

disk

Disk

The reference to the disk.

template

Template

The reference to the template.

vm

Vm

The reference to the virtual machine.

7.47. DiskFormat enum
Copiar enlace

The underlying storage format of disks.

Expand
Table 7.62. Values summary
NameSummary

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.

7.48. DiskInterface enum
Copiar enlace

Expand
Table 7.63. Values summary
NameSummary

ide

 

spapr_vscsi

 

virtio

 

virtio_scsi

 

7.49. DiskProfile struct
Copiar enlace

Expand
Table 7.64. Attributes summary
NameTypeSummary

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.

Expand
Table 7.65. Links summary
NameTypeSummary

permissions

Permission[]

 

qos

Qos

 

storage_domain

StorageDomain

 

7.50. DiskSnapshot struct
Copiar enlace

Expand
Table 7.66. Attributes summary
NameTypeSummary

active

Boolean

Indicates if the disk is visible to the virtual machine.

actual_size

Integer

The actual size of the disk, in bytes.

alias

String

 

bootable

Boolean

Indicates if the disk is marked as bootable.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

format

DiskFormat

The underlying storage format.

id

String

A unique identifier.

image_id

String

 

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 not cause virtual machine to be paused and, instead, disk errors should be propagated to the the guest operating system.

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

 

shareable

Boolean

Indicates if the disk can be attached to multiple virtual machines.

sparse

Boolean

Indicates if the physical storage for the disk should not be preallocated.

status

DiskStatus

The status of the disk device.

storage_type

DiskStorageType

 

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

7.50.1. active
Copiar enlace

Indicates if the disk is visible to the virtual machine.

Important

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

7.50.2. actual_size
Copiar enlace

The actual size of the disk, in bytes.

The actual size is the number of bytes actually used by the disk, and it will be smaller than the provisioned size for disks that use the cow format.

7.50.3. bootable
Copiar enlace

Indicates if the disk is marked as bootable.

Important

This attribute only makes sense for disks that are actually connected to virtual machines, and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

7.50.4. initial_size
Copiar enlace

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.

7.50.5. interface
Copiar enlace

The type of interface driver used to connect the disk device to the virtual machine.

Important

This attribute only makes sense for disks that are actually connected to virtual machines, and in version 4 of the API it has been moved to the DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

7.50.6. provisioned_size
Copiar enlace

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

7.50.7. qcow_version
Copiar enlace

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 storage domain’s version which the disk is created on. Storage domains with version lower than V4 support QCOW2 volumes, while V4 storage domains also support QCOW2v3. For more information about features of the different QCOW versions, see here.

7.50.8. shareable
Copiar enlace

Indicates if the disk can be attached to multiple virtual machines.

Important

When a disk is attached to multiple virtual machines it is the responsibility of the guest operating systems of those virtual machines to coordinate access to it, to avoid corruption of the data, for example using a shared file system like GlusterFS or GFS.

7.50.9. wipe_after_delete
Copiar enlace

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.
Expand
Table 7.67. Links summary
NameTypeSummary

disk

Disk

 

disk_profile

DiskProfile

 

instance_type

InstanceType

Optionally references to an instance type the device is used by.

openstack_volume_type

OpenStackVolumeType

 

permissions

Permission[]

 

quota

Quota

 

snapshot

Snapshot

 

statistics

Statistic[]

Statistics exposed by the disk.

storage_domain

StorageDomain

 

storage_domains

StorageDomain[]

The storage domains associated with this disk.

template

Template

Optionally references to a template the device is used by.

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

7.51. DiskStatus enum
Copiar enlace

Expand
Table 7.68. Values summary
NameSummary

illegal

 

locked

 

ok

 

7.52. DiskStorageType enum
Copiar enlace

Expand
Table 7.69. Values summary
NameSummary

cinder

 

image

 

lun

 

7.53. DiskType enum
Copiar enlace

Expand
Table 7.70. Values summary
NameSummary

data

 

system

 

7.54. Display struct
Copiar enlace

Expand
Table 7.71. Attributes summary
NameTypeSummary

address

String

 

allow_override

Boolean

 

certificate

Certificate

 

copy_paste_enabled

Boolean

 

disconnect_action

String

 

file_transfer_enabled

Boolean

 

keyboard_layout

String

 

monitors

Integer

 

port

Integer

 

proxy

String

 

secure_port

Integer

 

single_qxl_pci

Boolean

 

smartcard_enabled

Boolean

 

type

DisplayType

 

7.55. DisplayType enum
Copiar enlace

Expand
Table 7.72. Values summary
NameSummary

spice

 

vnc

 

7.56. Dns struct
Copiar enlace

Represents the DNS resolver configuration.

Expand
Table 7.73. Attributes summary
NameTypeSummary

search_domains

Host[]

Array of hosts serving as search domains.

servers

Host[]

Array of hosts serving as DNS servers.

7.57. DnsResolverConfiguration struct
Copiar enlace

Represents the DNS resolver configuration.

Expand
Table 7.74. Attributes summary
NameTypeSummary

name_servers

String[]

Array of addresses of name servers.

7.57.1. name_servers
Copiar enlace

Array of addresses of name servers. Either IPv4 or IPv6 addresses may be specified.

7.58. Domain struct
Copiar enlace

This type represents a directory service domain.

Expand
Table 7.75. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.76. Links summary
NameTypeSummary

groups

Group[]

A reference to all groups in the directory service.

users

User[]

A reference to a list of all users in the directory service.

7.59. EntityExternalStatus enum
Copiar enlace

Type representing an external entity status.

Expand
Table 7.77. Values summary
NameSummary

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.

7.59.1. error
Copiar enlace

The external entity status is erroneous. This might require a moderate attention.

7.59.2. failure
Copiar enlace

The external entity has an issue that causes failures. This might require immediate attention.

7.60. EntityProfileDetail struct
Copiar enlace

Expand
Table 7.78. Attributes summary
NameTypeSummary

profile_details

ProfileDetail[]

 

7.61. ErrorHandling struct
Copiar enlace

Expand
Table 7.79. Attributes summary
NameTypeSummary

on_error

MigrateOnError

 

7.62. Event struct
Copiar enlace

Type representing an event.

Expand
Table 7.80. Attributes summary
NameTypeSummary

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.

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.

7.62.1. correlation_id
Copiar enlace

The event correlation identifier. Used in order to correlate several events together.

7.62.2. flood_rate
Copiar enlace

Defines the flood rate. This prevents flooding in case an event appeared more than once in the defined rate. Defaults is 30 seconds.

Expand
Table 7.81. Links summary
NameTypeSummary

cluster

Cluster

Reference to the cluster service.

data_center

DataCenter

Reference to the data center service.

host

Host

Reference to the host service.

storage_domain

StorageDomain

Reference to the storage domain service.

template

Template

Reference to the template service.

user

User

Reference to the user service.

vm

Vm

Reference to the virtual machine service.

7.63. ExternalComputeResource struct
Copiar enlace

Expand
Table 7.82. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.83. Links summary
NameTypeSummary

external_host_provider

ExternalHostProvider

 

7.64. ExternalDiscoveredHost struct
Copiar enlace

Expand
Table 7.84. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.85. Links summary
NameTypeSummary

external_host_provider

ExternalHostProvider

 

7.65. ExternalHost struct
Copiar enlace

Expand
Table 7.86. Attributes summary
NameTypeSummary

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.

Expand
Table 7.87. Links summary
NameTypeSummary

external_host_provider

ExternalHostProvider

 

7.66. ExternalHostGroup struct
Copiar enlace

Expand
Table 7.88. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.89. Links summary
NameTypeSummary

external_host_provider

ExternalHostProvider

 

7.67. ExternalHostProvider struct
Copiar enlace

Expand
Table 7.90. Attributes summary
NameTypeSummary

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.

7.67.1. requires_authentication
Copiar enlace

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

Expand
Table 7.91. Links summary
NameTypeSummary

certificates

Certificate[]

 

compute_resources

ExternalComputeResource[]

 

discovered_hosts

ExternalDiscoveredHost[]

 

host_groups

ExternalHostGroup[]

 

hosts

Host[]

 

7.68. ExternalProvider struct
Copiar enlace

Represents an external provider.

Expand
Table 7.92. Attributes summary
NameTypeSummary

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.

7.68.1. requires_authentication
Copiar enlace

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

7.69. ExternalStatus enum
Copiar enlace

Expand
Table 7.93. Values summary
NameSummary

error

 

failure

 

info

 

ok

 

warning

 

7.70. ExternalSystemType enum
Copiar enlace

Represents the type of the external system that is associated with the step.

Expand
Table 7.94. Values summary
NameSummary

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.

7.71. ExternalVmImport struct
Copiar enlace

Describes the parameters for the virtual machine import operation from an external system.

Expand
Table 7.95. Attributes summary
NameTypeSummary

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

Specifies the disk allocation policy of the resulting virtual machine: true for sparse, false for preallocated.

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.

7.71.1. url
Copiar enlace

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.

Expand
Table 7.96. Links summary
NameTypeSummary

cluster

Cluster

Specifies the target cluster for the resulting virtual machine.

cpu_profile

CpuProfile

Optional.

drivers_iso

File

Optional.

host

Host

Optional.

quota

Quota

Optional.

storage_domain

StorageDomain

Specifies the target storage domain for converted disks.

vm

Vm

The virtual machine entity used to specify a name for the newly created virtual machine.

7.72. ExternalVmProviderType enum
Copiar enlace

Describes the type of external hypervisor system.

Expand
Table 7.97. Values summary
NameSummary

kvm

 

vmware

 

xen

 

7.73. Fault struct
Copiar enlace

Expand
Table 7.98. Attributes summary
NameTypeSummary

detail

String

 

reason

String

 

7.74. FenceType enum
Copiar enlace

Type representing the type of the fence operation.

Expand
Table 7.99. Values summary
NameSummary

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.

7.75. FencingPolicy struct
Copiar enlace

Type representing a cluster fencing policy.

Expand
Table 7.100. Attributes summary
NameTypeSummary

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.

7.75.1. skip_if_connectivity_broken
Copiar enlace

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.

7.75.2. skip_if_gluster_bricks_up
Copiar enlace

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.

7.75.3. skip_if_gluster_quorum_not_met
Copiar enlace

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.

7.75.4. skip_if_sd_active
Copiar enlace

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.

7.76. File struct
Copiar enlace

Expand
Table 7.101. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.102. Links summary
NameTypeSummary

storage_domain

StorageDomain

 

7.77. Filter struct
Copiar enlace

Expand
Table 7.103. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.104. Links summary
NameTypeSummary

scheduling_policy_unit

SchedulingPolicyUnit

 

7.78. Floppy struct
Copiar enlace

Expand
Table 7.105. Attributes summary
NameTypeSummary

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.

Expand
Table 7.106. Links summary
NameTypeSummary

instance_type

InstanceType

Optionally references to an instance type the device is used by.

template

Template

Optionally references to a template the device is used by.

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

7.79. FopStatistic struct
Copiar enlace

Expand
Table 7.107. Attributes summary
NameTypeSummary

name

String

 

statistics

Statistic[]

 

7.80. GlusterBrick struct
Copiar enlace

Expand
Table 7.108. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.109. Links summary
NameTypeSummary

gluster_volume

GlusterVolume

 

instance_type

InstanceType

Optionally references to an instance type the device is used by.

statistics

Statistic[]

 

template

Template

Optionally references to a template the device is used by.

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

7.81. GlusterBrickAdvancedDetails struct
Copiar enlace

Expand
Table 7.110. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.111. Links summary
NameTypeSummary

instance_type

InstanceType

Optionally references to an instance type the device is used by.

template

Template

Optionally references to a template the device is used by.

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

7.82. GlusterBrickMemoryInfo struct
Copiar enlace

Expand
Table 7.112. Attributes summary
NameTypeSummary

memory_pools

GlusterMemoryPool[]

 

7.83. GlusterBrickStatus enum
Copiar enlace

Expand
Table 7.113. Values summary
NameSummary

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.

7.84. GlusterClient struct
Copiar enlace

Expand
Table 7.114. Attributes summary
NameTypeSummary

bytes_read

Integer

 

bytes_written

Integer

 

client_port

Integer

 

host_name

String

 

7.85. GlusterHook struct
Copiar enlace

Expand
Table 7.115. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.116. Links summary
NameTypeSummary

cluster

Cluster

 

server_hooks

GlusterServerHook[]

 

7.86. GlusterHookStatus enum
Copiar enlace

Expand
Table 7.117. Values summary
NameSummary

disabled

Hook is disabled in the cluster.

enabled

Hook is enabled in the cluster.

missing

Unknown/missing hook status.

7.87. GlusterMemoryPool struct
Copiar enlace

Expand
Table 7.118. Attributes summary
NameTypeSummary

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

 

7.88. GlusterServerHook struct
Copiar enlace

Expand
Table 7.119. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.120. Links summary
NameTypeSummary

host

Host

 

7.89. GlusterState enum
Copiar enlace

Expand
Table 7.121. Values summary
NameSummary

down

 

unknown

 

up

 

7.90. GlusterVolume struct
Copiar enlace

Expand
Table 7.122. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.123. Links summary
NameTypeSummary

bricks

GlusterBrick[]

 

cluster

Cluster

 

statistics

Statistic[]

 

7.91. GlusterVolumeProfileDetails struct
Copiar enlace

Expand
Table 7.124. Attributes summary
NameTypeSummary

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[]

 

7.92. GlusterVolumeStatus enum
Copiar enlace

Expand
Table 7.125. Values summary
NameSummary

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.

7.93. GlusterVolumeType enum
Copiar enlace

Type representing the type of Gluster Volume.

Expand
Table 7.126. Values summary
NameSummary

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.

7.93.1. disperse
Copiar enlace

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.

7.93.2. distribute
Copiar enlace

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.

7.93.3. distributed_disperse
Copiar enlace

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.

7.93.4. distributed_replicate
Copiar enlace

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.

7.93.5. distributed_stripe
Copiar enlace

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.

7.93.6. distributed_striped_replicate
Copiar enlace

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.

7.93.7. replicate
Copiar enlace

Replicated volumes replicates files across bricks in the volume.

Replicated volumes can be used in environments where high-availability and high-reliability are critical.

7.93.8. stripe
Copiar enlace

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.

7.93.9. striped_replicate
Copiar enlace

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.

7.94. GracePeriod struct
Copiar enlace

Expand
Table 7.127. Attributes summary
NameTypeSummary

expiry

Integer

 

7.95. GraphicsConsole struct
Copiar enlace

Expand
Table 7.128. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.129. Links summary
NameTypeSummary

instance_type

InstanceType

 

template

Template

 

vm

Vm

 

7.96. GraphicsType enum
Copiar enlace

Expand
Table 7.130. Values summary
NameSummary

spice

 

vnc

 

7.97. Group struct
Copiar enlace

This type represents all groups in the directory service.

Expand
Table 7.131. Attributes summary
NameTypeSummary

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.

Expand
Table 7.132. Links summary
NameTypeSummary

domain

Domain

A link to the domain containing this group.

permissions

Permission[]

A link to the permissions sub-collection for permissions attached to this group.

roles

Role[]

A link to the roles sub-collection for roles attached to this group.

tags

Tag[]

A link to the tags sub-collection for tags attached to this group.

7.98. GuestOperatingSystem struct
Copiar enlace

Expand
Table 7.133. Attributes summary
NameTypeSummary

architecture

String

 

codename

String

 

distribution

String

 

family

String

 

kernel

Kernel

 

version

Version

 

7.99. HardwareInformation struct
Copiar enlace

Expand
Table 7.134. Attributes summary
NameTypeSummary

family

String

 

manufacturer

String

 

product_name

String

 

serial_number

String

 

supported_rng_sources

RngSource[]

 

uuid

String

 

version

String

 

7.100. HighAvailability struct
Copiar enlace

Expand
Table 7.135. Attributes summary
NameTypeSummary

enabled

Boolean

 

priority

Integer

Indicates the priority of the virtual machine inside the run and migration queues.

7.100.1. priority
Copiar enlace

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:

Expand
API ValueGUI 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:

Expand
GUI LabelAPI Value

Low

1

Medium

50

High

100

7.101. Hook struct
Copiar enlace

Represents a hook.

Expand
Table 7.136. Attributes summary
NameTypeSummary

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.

Expand
Table 7.137. Links summary
NameTypeSummary

host

Host

Reference to the host the hook belongs to.

7.102. HookContentType enum
Copiar enlace

Represents content type of hook script.

Expand
Table 7.138. Values summary
NameSummary

binary

Binary content type of the hook.

text

Text content type of the hook.

7.103. HookStage enum
Copiar enlace

Expand
Table 7.139. Values summary
NameSummary

post

 

pre

 

7.104. HookStatus enum
Copiar enlace

Type represents the status of a hook.

Expand
Table 7.140. Values summary
NameSummary

disabled

Hook is disabled.

enabled

Hook is enabled.

missing

Hook is missing.

7.105. Host struct
Copiar enlace

Type representing a host.

Expand
Table 7.141. Attributes summary
NameTypeSummary

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 hosted engine status on 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.

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.

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.

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.

7.105.1. external_status
Copiar enlace

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.

7.105.2. kdump_status
Copiar enlace

The host KDUMP status. KDUMP happens when the host kernel has crashed and it is now going through memory dumping.

7.105.3. ksm
Copiar enlace

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>

7.105.4. libvirt_version
Copiar enlace

The host libvirt version. For more information on libvirt please go to libvirt.

7.105.5. override_iptables
Copiar enlace

Specifies whether we should override firewall definitions. This applies only when the host is installed or re-installed.

7.105.6. protocol
Copiar enlace

The protocol that the engine uses to communicate with the host.

Warning

Since version 4.1 of the engine the protocol is always set to stomp since xml was removed.

7.105.7. se_linux
Copiar enlace

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.

7.105.8. spm
Copiar enlace

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.

7.105.9. status_detail
Copiar enlace

The host status details. Relevant for Gluster hosts.

7.105.10. transparent_huge_pages
Copiar enlace

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>

7.105.11. version
Copiar enlace

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>
Expand
Table 7.142. Links summary
NameTypeSummary

affinity_labels

AffinityLabel[]

 

agents

Agent[]

 

cluster

Cluster

 

devices

Device[]

 

external_host_provider

ExternalHostProvider

 

hooks

Hook[]

 

katello_errata

KatelloErratum[]

Lists all the Katello errata assigned to the host.

network_attachments

NetworkAttachment[]

 

nics

HostNic[]

 

numa_nodes

NumaNode[]

 

permissions

Permission[]

 

statistics

Statistic[]

Each host resource exposes a statistics sub-collection for host-specific statistics.

storage_connection_extensions

StorageConnectionExtension[]

 

storages

HostStorage[]

 

tags

Tag[]

 

unmanaged_networks

UnmanagedNetwork[]

 

7.106. HostDevice struct
Copiar enlace

Expand
Table 7.143. Attributes summary
NameTypeSummary

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

 

name

String

A human-readable name in plain text.

physical_function

HostDevice

 

placeholder

Boolean

 

product

Product

 

vendor

Vendor

 

virtual_functions

Integer

 

7.106.1. driver
Copiar enlace

The name of the driver this device is bound to.

For example: pcieport or uhci_hcd.

Expand
Table 7.144. Links summary
NameTypeSummary

host

Host

 

parent_device

HostDevice

 

vm

Vm

 

7.107. HostDevicePassthrough struct
Copiar enlace

Expand
Table 7.145. Attributes summary
NameTypeSummary

enabled

Boolean

 

7.108. HostNic struct
Copiar enlace

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>
Expand
Table 7.146. Attributes summary
NameTypeSummary

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.

network_labels

NetworkLabel[]

The labels that are applied to this NIC.

override_configuration

Boolean

 

properties

Property[]

 

speed

Integer

 

statistics

Statistic[]

A link to the statistics of the NIC.

status

NicStatus

 

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

Describes the virtual functions configuration of a physical function NIC.

vlan

Vlan

 

7.108.1. ad_aggregator_id
Copiar enlace

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.

7.108.2. bridged
Copiar enlace

Defines the bridged network status. Set to true for a bridged network and false for a bridgeless network.

7.108.3. statistics
Copiar enlace

A link to the statistics of the NIC.

The data types for HostNic statistical values:

  • data.current.rx - The rate in bytes per second of data received.
  • data.current.tx - The rate in bytes per second of data transmitted.
  • data.total.rx - Total received data.
  • data.total.tx - Total transmitted data.
  • errors.total.rx - Total errors from receiving data.
  • errors.total.tx - Total errors from transmitting data.
Expand
Table 7.147. Links summary
NameTypeSummary

host

Host

 

network

Network

A reference to the network to which the interface should be connected.

physical_function

HostNic

A reference to the physical function NIC of a SR-IOV virtual function NIC.

qos

Qos

A link to the quality-of-service configuration of the interface.

7.109. HostNicVirtualFunctionsConfiguration struct
Copiar enlace

Describes the virtual functions configuration of an SR-IOV-enabled physical function NIC.

Expand
Table 7.148. Attributes summary
NameTypeSummary

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.

7.109.1. max_number_of_virtual_functions
Copiar enlace

The maximum number of virtual functions the NIC supports. This property is read-only.

7.109.2. number_of_virtual_functions
Copiar enlace

The number of virtual functions currently defined. A user-defined value between 0 and max_number_of_virtual_functions.

7.110. HostProtocol enum
Copiar enlace

The protocol used by the engine to communicate with a host.

Warning

Since version 4.1 of the engine the protocol is always set to stomp since xml was removed.

Expand
Table 7.149. Values summary
NameSummary

stomp

JSON-RPC protocol on top of STOMP.

xml

XML-RPC protocol.

7.111. HostStatus enum
Copiar enlace

Type representing a host status.

Expand
Table 7.150. Values summary
NameSummary

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.

7.111.1. error
Copiar enlace

The host is in error status. This will happen if we will try to run a virtual machine several times and it will fail.

7.111.2. initializing
Copiar enlace

The host is initializing. This is an intermediate step before moving the host to 'up' status.

7.111.3. install_failed
Copiar enlace

The host installation failed. In such cases look at the event log to understand what failed the installation, and issue a re-install.

7.111.4. installing_os
Copiar enlace

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

7.111.5. maintenance
Copiar enlace

The host is in maintenance status. When a host is in maintenance it cannot run virtual machines.

7.111.6. non_operational
Copiar enlace

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.

7.111.7. non_responsive
Copiar enlace

The host is not responsive. This means that the engine is not able to communicate with the host.

7.111.8. pending_approval
Copiar enlace

The host is pending administrator approval. This is relevant only for vintage ovirt-node / RHV-H.

7.111.9. preparing_for_maintenance
Copiar enlace

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.

7.112. HostStorage struct
Copiar enlace

Expand
Table 7.151. Attributes summary
NameTypeSummary

address

String

 

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

logical_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

 

7.112.1. nfs_retrans
Copiar enlace

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.

7.112.2. nfs_timeo
Copiar enlace

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.

Expand
Table 7.152. Links summary
NameTypeSummary

host

Host

 

7.113. HostType enum
Copiar enlace

This enumerated type is used to determine which type of operating system is used by the host.

Expand
Table 7.153. Values summary
NameSummary

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.

7.113.1. ovirt_node
Copiar enlace

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.

7.114. HostedEngine struct
Copiar enlace

Expand
Table 7.154. Attributes summary
NameTypeSummary

active

Boolean

 

configured

Boolean

 

global_maintenance

Boolean

 

local_maintenance

Boolean

 

score

Integer

 

7.115. Icon struct
Copiar enlace

Icon of virtual machine or template.

Expand
Table 7.155. Attributes summary
NameTypeSummary

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.

7.115.1. media_type
Copiar enlace

Format of icon file.

One of:

  • image/jpeg
  • image/png
  • image/gif

7.116. Identified struct
Copiar enlace

This interface is the base model for all types that represent objects with an identifier.

Expand
Table 7.156. Attributes summary
NameTypeSummary

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.

7.117. Image struct
Copiar enlace

Expand
Table 7.157. Attributes summary
NameTypeSummary

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.

Expand
Table 7.158. Links summary
NameTypeSummary

storage_domain

StorageDomain

 

7.118. ImageTransfer struct
Copiar enlace

This type contains information regarding an image transfer being performed.

Expand
Table 7.159. Attributes summary
NameTypeSummary

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

id

String

A unique identifier.

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.

signed_ticket

String

The signed ticket that should be attached as an Authentication header in the HTTPS request for the proxy server to input or output to (See the proxy_url attribute).

7.118.1. direction
Copiar enlace

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.

7.118.2. phase
Copiar enlace

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.

7.118.3. proxy_url
Copiar enlace

The URL of the proxy server that the user inputs or outputs to. This attribute is available only if the image transfer entity is in the transferring phase. See phase for details.

Expand
Table 7.160. Links summary
NameTypeSummary

host

Host

The host which will be used to write to the image which is targeted for input or output.

image

Image

The image which is targeted for input or output.

7.119. ImageTransferDirection enum
Copiar enlace

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.

Expand
Table 7.161. Values summary
NameSummary

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.

7.120. ImageTransferPhase enum
Copiar enlace

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.

Expand
Table 7.162. Values summary
NameSummary

cancelled

This phase will be set as a result of the user cancelling the transfer.

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_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-daemon is not running in the selected host.

paused_user

This phase is a result of a pause call by the user, using pause.

resuming

The phase where the transfer has been resumed by the client calling resume.

transferring

The phase where the transfer session is open, and the client can input or output the desired image using the preferred tools.

unknown

An unknown phase.

7.120.1. cancelled
Copiar enlace

This phase will be set as a result of the user cancelling the transfer. The cancellation can only be performed in the Administration Portal.

7.120.2. finalizing_success
Copiar enlace

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.

7.120.3. finished_failure
Copiar enlace

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.

7.120.4. finished_success
Copiar enlace

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.

7.120.5. initializing
Copiar enlace

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

7.120.6. paused_system
Copiar enlace

This phase means the session timed out, or some other error occurred with this transfer; for example ovirt-imageio-daemon is not running in the selected host. To resume the session, the client should call resume. After resuming, the phase will change to resuming.

7.120.7. resuming
Copiar enlace

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.

7.120.8. unknown
Copiar enlace

An unknown phase. This will only be set in cases of unpredictable errors.

7.121. InheritableBoolean enum
Copiar enlace

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.

Expand
Table 7.163. Values summary
NameSummary

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.

7.122. Initialization struct
Copiar enlace

Expand
Table 7.164. Attributes summary
NameTypeSummary

active_directory_ou

String

 

authorized_ssh_keys

String

 

cloud_init

CloudInit

 

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

 

7.123. InstanceType struct
Copiar enlace

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

Note

An instance type inherits it’s attributes from the template entity although most template attributes are not used in instance types.

Expand
Table 7.165. Attributes summary
NameTypeSummary

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_shares

Integer

 

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

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

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

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

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 a base version or a sub version of another template.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

vm

Vm

The virtual machine configuration associated with this template.

7.123.1. cpu
Copiar enlace

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>

7.123.2. custom_compatibility_version
Copiar enlace

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.

7.123.3. high_availability
Copiar enlace

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.123.4. large_icon
Copiar enlace

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.123.5. lease
Copiar enlace

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.

7.123.6. memory
Copiar enlace

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request: 

PUT /ovirt-engine/api/vms/123

With the following request body: 

<vm>
  <memory>1073741824</memory>
</vm>
Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is running.

7.123.7. migration_downtime
Copiar enlace

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]

7.123.8. origin
Copiar enlace

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.123.9. small_icon
Copiar enlace

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.123.10. sso
Copiar enlace

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.

Expand
Table 7.166. Links summary
NameTypeSummary

cdroms

Cdrom[]

References to the CD-ROM devices attached to the template.

cluster

Cluster

Reference to cluster the virtual machine belongs to.

cpu_profile

CpuProfile

Reference to CPU profile used by this virtual machine.

disk_attachments

DiskAttachment[]

References to the disks attached to the template.

graphics_consoles

GraphicsConsole[]

References to the graphic consoles attached to the template.

nics

Nic[]

References to the network interfaces attached to the template.

permissions

Permission[]

References to the user permissions attached to the template.

quota

Quota

Reference to quota configuration set for this virtual machine.

storage_domain

StorageDomain

Reference to storage domain the virtual machine belongs to.

tags

Tag[]

References to the tags attached to the template.

watchdogs

Watchdog[]

References to the watchdog devices attached to the template.

7.124. Io struct
Copiar enlace

Expand
Table 7.167. Attributes summary
NameTypeSummary

threads

Integer

 

7.125. Ip struct
Copiar enlace

Represents the IP configuration of a network interface.

Expand
Table 7.168. Attributes summary
NameTypeSummary

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.

7.125.1. address
Copiar enlace

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>

7.125.2. netmask
Copiar enlace

The network mask.

For IPv6 addresses the value is an integer in the range of 0-128, which represents the subnet prefix.

7.125.3. version
Copiar enlace

The version of the IP protocol.

Note

From version 4.1 of the Manager this attribute will be optional, and when a value is not provided, it will be inferred from the value of the address attribute.

7.126. IpAddressAssignment struct
Copiar enlace

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.

Expand
Table 7.169. Attributes summary
NameTypeSummary

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.

7.127. IpVersion enum
Copiar enlace

Defines the values for the IP protocol version.

Expand
Table 7.170. Values summary
NameSummary

v4

IPv4.

v6

IPv6.

7.128. IscsiBond struct
Copiar enlace

Expand
Table 7.171. Attributes summary
NameTypeSummary

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.

Expand
Table 7.172. Links summary
NameTypeSummary

data_center

DataCenter

 

networks

Network[]

 

storage_connections

StorageConnection[]

 

7.129. IscsiDetails struct
Copiar enlace

Expand
Table 7.173. Attributes summary
NameTypeSummary

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

 

7.130. Job struct
Copiar enlace

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.

Expand
Table 7.174. Attributes summary
NameTypeSummary

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.

7.130.1. external
Copiar enlace

Indicates if the job is originated by an external system. External jobs are managed externally, by the creator of the job.

Expand
Table 7.175. Links summary
NameTypeSummary

owner

User

The user who is the owner of the job.

steps

Step[]

The steps of the job.

7.131. JobStatus enum
Copiar enlace

Represents the status of the job.

Expand
Table 7.176. Values summary
NameSummary

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.

7.131.1. aborted
Copiar enlace

The aborted job status. This status is applicable for an external job that was forcibly aborted.

7.131.2. finished
Copiar enlace

The finished job status. This status describes a completed job execution.

7.131.3. started
Copiar enlace

The started job status. This status represents a job which is currently being executed.

7.131.4. unknown
Copiar enlace

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.

7.132. KatelloErratum struct
Copiar enlace

Type representing a Katello erratum.

Expand
Table 7.177. Attributes summary
NameTypeSummary

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.

7.132.1. severity
Copiar enlace

The severity of the Katello erratum.

The supported severities are moderate, important or critical.

7.132.2. type
Copiar enlace

The type of the Katello erratum.

The supported types are bugfix, enhancement or security.

Expand
Table 7.178. Links summary
NameTypeSummary

host

Host

Reference to the host that the Katello erratum is assigned to.

vm

Vm

Reference to the virtual machine that the Katello erratum is assigned to.

7.133. KdumpStatus enum
Copiar enlace

Expand
Table 7.179. Values summary
NameSummary

disabled

 

enabled

 

unknown

 

7.134. Kernel struct
Copiar enlace

Expand
Table 7.180. Attributes summary
NameTypeSummary

version

Version

 

7.135. Ksm struct
Copiar enlace

Expand
Table 7.181. Attributes summary
NameTypeSummary

enabled

Boolean

 

merge_across_nodes

Boolean

 

7.136. LogSeverity enum
Copiar enlace

Enum representing a severity of an event.

Expand
Table 7.182. Values summary
NameSummary

alert

Alert severity.

error

Error severity.

normal

Normal severity.

warning

Warning severity.

7.136.1. alert
Copiar enlace

Alert severity. Used to specify a condition that requires an immediate attention.

7.136.2. error
Copiar enlace

Error severity. Used to specify that there is an error that needs to be examined.

7.136.3. normal
Copiar enlace

Normal severity. Used for information events.

7.136.4. warning
Copiar enlace

Warning severity. Used to warn something might be wrong.

7.137. LogicalUnit struct
Copiar enlace

Expand
Table 7.183. Attributes summary
NameTypeSummary

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

 

7.137.1. discard_max_size
Copiar enlace

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.

Note

This is the software limit, and not the hardware limit, as noted in the documentation of queue-sysfs for discard_max_bytes.

7.137.2. discard_zeroes_data
Copiar enlace

True, if previously discarded blocks in the logical unit’s underlying storage are read back as zeros. For more information please see the documentation of queue-sysfs for discard_zeroes_data.

7.138. LunStatus enum
Copiar enlace

Expand
Table 7.184. Values summary
NameSummary

free

 

unusable

 

used

 

7.139. Mac struct
Copiar enlace

Expand
Table 7.185. Attributes summary
NameTypeSummary

address

String

 

7.140. MacPool struct
Copiar enlace

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>
Expand
Table 7.186. Attributes summary
NameTypeSummary

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.

7.140.1. allow_duplicates
Copiar enlace

Defines whether duplicate MAC addresses are permitted in the pool. If not specified, defaults to false.

7.140.2. default_pool
Copiar enlace

Defines whether this is the default pool. If not specified, defaults to false.

7.140.3. ranges
Copiar enlace

Defines the range of MAC addresses for the pool. Multiple ranges can be defined.

7.141. MemoryOverCommit struct
Copiar enlace

Expand
Table 7.187. Attributes summary
NameTypeSummary

percent

Integer

 

7.142. MemoryPolicy struct
Copiar enlace

Logical grouping of memory related properties of virtual machine-like entities.

Expand
Table 7.188. Attributes summary
NameTypeSummary

ballooning

Boolean

 

guaranteed

Integer

 

max

Integer

Maximum virtual machine’s memory, in bytes.

over_commit

MemoryOverCommit

 

transparent_huge_pages

TransparentHugePages

 

7.142.1. max
Copiar enlace

Maximum virtual machine’s memory, in bytes.

The user provides the value in bytes, and the engine 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 Red Hat Virtualization Manager will truncate that value to the nearest lower MiB boundary: in this case 1073741824 (1 GiB).

7.143. MessageBrokerType enum
Copiar enlace

Expand
Table 7.189. Values summary
NameSummary

qpid

 

rabbit_mq

 

7.144. Method struct
Copiar enlace

Expand
Table 7.190. Attributes summary
NameTypeSummary

id

SsoMethod

 

7.145. MigrateOnError enum
Copiar enlace

Expand
Table 7.191. Values summary
NameSummary

do_not_migrate

 

migrate

 

migrate_highly_available

 

7.146. MigrationBandwidth struct
Copiar enlace

Defines the bandwidth used by migration.

Expand
Table 7.192. Attributes summary
NameTypeSummary

assignment_method

MigrationBandwidthAssignmentMethod

The method used to assign the bandwidth.

custom_value

Integer

Custom bandwidth in Mbps.

7.146.1. custom_value
Copiar enlace

Custom bandwidth in Mbps. Will be applied only if the assignmentMethod attribute is custom.

7.147. MigrationBandwidthAssignmentMethod enum
Copiar enlace

Defines how the migration bandwidth is assigned.

Expand
Table 7.193. Values summary
NameSummary

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.

7.147.1. auto
Copiar enlace

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.

7.148. MigrationOptions struct
Copiar enlace

The type for migration options.

Expand
Table 7.194. Attributes summary
NameTypeSummary

auto_converge

InheritableBoolean

 

bandwidth

MigrationBandwidth

The bandwidth that is allowed to be used by the migration.

compressed

InheritableBoolean

 
Expand
Table 7.195. Links summary
NameTypeSummary

policy

MigrationPolicy

A reference to the migration policy, as defined using engine-config.

7.149. MigrationPolicy struct
Copiar enlace

A policy describing how the migration is treated, such as convergence or how many parallel migrations are allowed.

Expand
Table 7.196. Attributes summary
NameTypeSummary

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.

7.150. Network struct
Copiar enlace

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>
Expand
Table 7.197. Attributes summary
NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

display

Boolean

 

dns_resolver_configuration

DnsResolverConfiguration

 

id

String

A unique identifier.

ip

Ip

 

mtu

Integer

Specifies the maximum transmission unit for the network.

name

String

A human-readable name in plain text.

profile_required

Boolean

 

required

Boolean

 

status

NetworkStatus

 

stp

Boolean

Specifies whether the spanning tree protocol is enabled for the network.

usages

NetworkUsage[]

Defines a set of usage elements for the network.

vlan

Vlan

 

7.150.1. usages
Copiar enlace

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.

Expand
Table 7.198. Links summary
NameTypeSummary

cluster

Cluster

 

data_center

DataCenter

A reference to the data center that the network is a member of.

network_labels

NetworkLabel[]

A reference to the labels assigned to the network.

permissions

Permission[]

A reference to the permissions of the network.

qos

Qos

 

vnic_profiles

VnicProfile[]

A reference to the profiles of the network.

7.151. NetworkAttachment struct
Copiar enlace

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
Important

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>
Expand
Table 7.199. Attributes summary
NameTypeSummary

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.

7.151.1. dns_resolver_configuration
Copiar enlace

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.

7.151.2. properties
Copiar enlace

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:

Expand
NameDefault 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

Expand
Table 7.200. Links summary
NameTypeSummary

host

Host

 

host_nic

HostNic

A reference to the host network interface.

network

Network

A reference to the network that the interface is attached to.

qos

Qos

 

7.152. NetworkConfiguration struct
Copiar enlace

Expand
Table 7.201. Attributes summary
NameTypeSummary

dns

Dns

 

nics

Nic[]

 

7.153. NetworkFilter struct
Copiar enlace

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.

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.

Expand
Table 7.202. Attributes summary
NameTypeSummary

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.

7.153.1. version
Copiar enlace

The minimum supported version of a specific NetworkFilter. This is the version that the NetworkFilter was first introduced in.

7.154. NetworkLabel struct
Copiar enlace

Represents a label which can be added to a host network interface.

Expand
Table 7.203. Attributes summary
NameTypeSummary

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.

Expand
Table 7.204. Links summary
NameTypeSummary

host_nic

HostNic

 

network

Network

 

7.155. NetworkPluginType enum
Copiar enlace

Expand
Table 7.205. Values summary
NameSummary

open_vswitch

 

7.156. NetworkStatus enum
Copiar enlace

Expand
Table 7.206. Values summary
NameSummary

non_operational

 

operational

 

7.157. NetworkUsage enum
Copiar enlace

This type indicates the purpose that the network is used for in the cluster.

Expand
Table 7.207. Values summary
NameSummary

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 Red Hat Virtualization Manager and the nodes.

migration

The network will be used for virtual machine migration.

vm

 

7.157.1. management
Copiar enlace

The network will be used for communication between the Red Hat Virtualization Manager and the nodes. This is the network where the ovirtmgmt bridge will be created.

7.158. NfsProfileDetail struct
Copiar enlace

Expand
Table 7.208. Attributes summary
NameTypeSummary

nfs_server_ip

String

 

profile_details

ProfileDetail[]

 

7.159. NfsVersion enum
Copiar enlace

Expand
Table 7.209. Values summary
NameSummary

auto

 

v3

 

v4

 

v4_1

 

v4_2

NFS 4.

7.159.1. v4_2
Copiar enlace

NFS 4.2.

7.160. Nic struct
Copiar enlace

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>
Expand
Table 7.210. Attributes summary
NameTypeSummary

boot_protocol

BootProtocol

 

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

interface

NicInterface

The type of driver used for the NIC.

linked

Boolean

Defines if the NIC is linked to the virtual machine.

mac

Mac

The MAC address of the interface.

name

String

A human-readable name in plain text.

on_boot

Boolean

 

plugged

Boolean

Defines if the NIC is plugged in to the virtual machine.

Expand
Table 7.211. Links summary
NameTypeSummary

instance_type

InstanceType

Optionally references to an instance type the device is used by.

network

Network

A reference to the network that the interface should be connected to.

network_attachments

NetworkAttachment[]

 

network_labels

NetworkLabel[]

 

reported_devices

ReportedDevice[]

 

statistics

Statistic[]

A link to the statistics for the NIC.

template

Template

Optionally references to a template the device is used by.

virtual_function_allowed_labels

NetworkLabel[]

 

virtual_function_allowed_networks

Network[]

 

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

vnic_profile

VnicProfile

 

7.161. NicConfiguration struct
Copiar enlace

Expand
Table 7.212. Attributes summary
NameTypeSummary

boot_protocol

BootProtocol

 

ip

Ip

 

name

String

 

on_boot

Boolean

 

7.162. NicInterface enum
Copiar enlace

Expand
Table 7.213. Values summary
NameSummary

e1000

 

pci_passthrough

 

rtl8139

 

rtl8139_virtio

 

spapr_vlan

 

virtio

 

7.163. NicStatus enum
Copiar enlace

Expand
Table 7.214. Values summary
NameSummary

down

 

up

 

7.164. NumaNode struct
Copiar enlace

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>
Expand
Table 7.215. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.216. Links summary
NameTypeSummary

host

Host

 

statistics

Statistic[]

Each host NUMA node resource exposes a statistics sub-collection for host NUMA node specific statistics.

7.165. NumaNodePin struct
Copiar enlace

Represents the pinning of a virtual NUMA node to a physical NUMA node.

Expand
Table 7.217. Attributes summary
NameTypeSummary

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.

7.165.1. host_numa_node
Copiar enlace

Deprecated. Has no function.

7.165.2. pinned
Copiar enlace

Deprecated. Should always be true.

7.166. NumaTuneMode enum
Copiar enlace

Expand
Table 7.218. Values summary
NameSummary

interleave

 

preferred

 

strict

 

7.167. OpenStackImage struct
Copiar enlace

Expand
Table 7.219. Attributes summary
NameTypeSummary

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.

Expand
Table 7.220. Links summary
NameTypeSummary

openstack_image_provider

OpenStackImageProvider

 

7.168. OpenStackImageProvider struct
Copiar enlace

Expand
Table 7.221. Attributes summary
NameTypeSummary

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

 

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

7.168.1. requires_authentication
Copiar enlace

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

Expand
Table 7.222. Links summary
NameTypeSummary

certificates

Certificate[]

 

images

OpenStackImage[]

 

7.169. OpenStackNetwork struct
Copiar enlace

Expand
Table 7.223. Attributes summary
NameTypeSummary

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.

Expand
Table 7.224. Links summary
NameTypeSummary

openstack_network_provider

OpenStackNetworkProvider

 

7.170. OpenStackNetworkProvider struct
Copiar enlace

Expand
Table 7.225. Attributes summary
NameTypeSummary

agent_configuration

AgentConfiguration

Agent configuration settings.

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.

plugin_type

NetworkPluginType

Network plugin type.

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

 

type

OpenStackNetworkProviderType

The type of provider.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

7.170.1. read_only
Copiar enlace

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.

7.170.2. requires_authentication
Copiar enlace

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

Expand
Table 7.226. Links summary
NameTypeSummary

certificates

Certificate[]

Reference to the certificates list.

networks

OpenStackNetwork[]

Reference to OpenStack networks list.

subnets

OpenStackSubnet[]

Reference to OpenStack networks subnets list.

7.171. OpenStackNetworkProviderType enum
Copiar enlace

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.

Expand
Table 7.227. Values summary
NameSummary

external

Indicates that the provider is an external one, implementing the OpenStack Neutron API.

neutron

Indicates that the provider is OpenStack Neutron.

7.171.1. external
Copiar enlace

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.

7.171.2. neutron
Copiar enlace

Indicates that the provider is OpenStack Neutron. The standard OpenStack Neutron agent is used as the virtual interface driver.

7.172. OpenStackProvider struct
Copiar enlace

Expand
Table 7.228. Attributes summary
NameTypeSummary

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

 

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

7.172.1. requires_authentication
Copiar enlace

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

7.173. OpenStackSubnet struct
Copiar enlace

Expand
Table 7.229. Attributes summary
NameTypeSummary

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.

7.173.1. ip_version
Copiar enlace

Defines IP version.

Values can be v4' for IPv4 or `v6 for IPv6.

Expand
Table 7.230. Links summary
NameTypeSummary

openstack_network

OpenStackNetwork

Reference to the service managing the OpenStack network.

7.174. OpenStackVolumeProvider struct
Copiar enlace

Expand
Table 7.231. Attributes summary
NameTypeSummary

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

 

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

7.174.1. requires_authentication
Copiar enlace

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

Expand
Table 7.232. Links summary
NameTypeSummary

authentication_keys

OpenstackVolumeAuthenticationKey[]

 

certificates

Certificate[]

 

data_center

DataCenter

 

volume_types

OpenStackVolumeType[]

 

7.175. OpenStackVolumeType struct
Copiar enlace

Expand
Table 7.233. Attributes summary
NameTypeSummary

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[]

 
Expand
Table 7.234. Links summary
NameTypeSummary

openstack_volume_provider

OpenStackVolumeProvider

 

7.176. OpenstackVolumeAuthenticationKey struct
Copiar enlace

Expand
Table 7.235. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.236. Links summary
NameTypeSummary

openstack_volume_provider

OpenStackVolumeProvider

 

7.177. OpenstackVolumeAuthenticationKeyUsageType enum
Copiar enlace

Expand
Table 7.237. Values summary
NameSummary

ceph

 

7.178. OperatingSystem struct
Copiar enlace

Information describing the operating system. This is used for both virtual machines and hosts.

Expand
Table 7.238. Attributes summary
NameTypeSummary

boot

Boot

 

cmdline

String

 

custom_kernel_cmdline

String

A custom part of the host kernel command line.

initrd

String

 

kernel

String

 

reported_kernel_cmdline

String

The host kernel command line as reported by a running host.

type

String

 

version

Version

 

7.178.1. custom_kernel_cmdline
Copiar enlace

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.

Note

This attribute is currently only used for hosts.

7.178.2. reported_kernel_cmdline
Copiar enlace

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.

Note

This attribute is currently only used for hosts.

7.179. OperatingSystemInfo struct
Copiar enlace

Expand
Table 7.239. Attributes summary
NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

large_icon

Icon

 

name

String

A human-readable name in plain text.

small_icon

Icon

 

7.180. Option struct
Copiar enlace

Expand
Table 7.240. Attributes summary
NameTypeSummary

name

String

 

type

String

 

value

String

 

7.181. OsType enum
Copiar enlace

Expand
Table 7.241. Values summary
NameSummary

other

 

other_linux

 

rhel_3

 

rhel_3x64

 

rhel_4

 

rhel_4x64

 

rhel_5

 

rhel_5x64

 

rhel_6

 

rhel_6x64

 

unassigned

 

windows_2003

 

windows_2003x64

 

windows_2008

 

windows_2008r2x64

 

windows_2008x64

 

windows_2012x64

 

windows_7

 

windows_7x64

 

windows_8

 

windows_8x64

 

windows_xp

 

7.182. Package struct
Copiar enlace

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>
Expand
Table 7.242. Attributes summary
NameTypeSummary

name

String

The name of the package.

7.183. Payload struct
Copiar enlace

Expand
Table 7.243. Attributes summary
NameTypeSummary

files

File[]

 

type

VmDeviceType

 

volume_id

String

 

7.184. PayloadEncoding enum
Copiar enlace

Expand
Table 7.244. Values summary
NameSummary

base64

 

plaintext

 

7.185. Permission struct
Copiar enlace

Expand
Table 7.245. Attributes summary
NameTypeSummary

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.

Expand
Table 7.246. Links summary
NameTypeSummary

cluster

Cluster

 

data_center

DataCenter

 

disk

Disk

 

group

Group

 

host

Host

 

role

Role

 

storage_domain

StorageDomain

 

template

Template

 

user

User

 

vm

Vm

 

vm_pool

VmPool

 

7.186. Permit struct
Copiar enlace

Type represents a permit.

Expand
Table 7.247. Attributes summary
NameTypeSummary

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.

Expand
Table 7.248. Links summary
NameTypeSummary

role

Role

Reference to the role the permit belongs to.

7.187. PmProxy struct
Copiar enlace

Expand
Table 7.249. Attributes summary
NameTypeSummary

type

PmProxyType

 

7.188. PmProxyType enum
Copiar enlace

Expand
Table 7.250. Values summary
NameSummary

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.

7.189. PolicyUnitType enum
Copiar enlace

Holds the types of all internal policy unit types.

Expand
Table 7.251. Values summary
NameSummary

filter

 

load_balancing

 

weight

 

7.190. PortMirroring struct
Copiar enlace

7.191. PowerManagement struct
Copiar enlace

Expand
Table 7.252. Attributes summary
NameTypeSummary

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.

7.191.1. agents
Copiar enlace

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.

7.191.2. automatic_pm_enabled
Copiar enlace

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.

7.191.3. kdump_detection
Copiar enlace

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.

7.191.4. type
Copiar enlace

Fencing device code.

A list of valid fencing device codes are available in the capabilities collection.

7.192. PowerManagementStatus enum
Copiar enlace

Expand
Table 7.253. Values summary
NameSummary

off

Host is OFF.

on

Host is ON.

unknown

Unknown status.

7.193. Product struct
Copiar enlace

Expand
Table 7.254. Attributes summary
NameTypeSummary

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.

7.194. ProductInfo struct
Copiar enlace

Product information.

The entry point contains a product_info element to help an API user determine the legitimacy of the Red Hat Virtualization environment. This includes the name of the product, the vendor and the version.

Verify a genuine Red Hat Virtualization environment

The follow elements identify a genuine Red Hat Virtualization environment: 

<api>
...
<product_info>
  <name>oVirt Engine</name>
  <vendor>ovirt.org</vendor>
  <version>
    <build>0</build>
    <full_version>4.1.0_master</full_version>
    <major>4</major>
    <minor>1</minor>
    <revision>0</revision>
  </version>
</product_info>
...
</api>
Expand
Table 7.255. Attributes summary
NameTypeSummary

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.

7.194.1. vendor
Copiar enlace

The name of the vendor, for example ovirt.org.

7.195. ProfileDetail struct
Copiar enlace

Expand
Table 7.256. Attributes summary
NameTypeSummary

block_statistics

BlockStatistic[]

 

duration

Integer

 

fop_statistics

FopStatistic[]

 

profile_type

String

 

statistics

Statistic[]

 

7.196. Property struct
Copiar enlace

Expand
Table 7.257. Attributes summary
NameTypeSummary

name

String

 

value

String

 

7.197. ProxyTicket struct
Copiar enlace

Expand
Table 7.258. Attributes summary
NameTypeSummary

value

String

 

7.198. QcowVersion enum
Copiar enlace

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.

Expand
Table 7.259. Values summary
NameSummary

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.

7.198.1. qcow2_v3
Copiar enlace

The Copy On Write compatibility version which was introduced in QEMU 1.1 It means that the new format is in use.

7.199. Qos struct
Copiar enlace

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.

Expand
Table 7.260. Attributes summary
NameTypeSummary

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.

inbound_burst

Integer

The amount of data that can be delivered in a single burst in MiB.

inbound_peak

Integer

The maximum inbound rate in Mbps.

max_iops

Integer

Maximum permitted number of input and output operations per second.

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

outbound_average_linkshare

Integer

Weighted share.

outbound_average_realtime

Integer

The committed rate in Mbps.

outbound_average_upperlimit

Integer

The maximum bandwidth to be used by a network in Mbps.

outbound_burst

Integer

The amount of data that can be sent in a single burst in MiB.

outbound_peak

Integer

The maximum outbound rate in Mbps.

type

QosType

The kind of resources this entry can be assigned.

7.199.1. cpu_limit
Copiar enlace

The maximum processing capability in %.

Used to configure computing resources.

7.199.2. inbound_average
Copiar enlace

The desired average inbound bit rate in Mbps.

Used to configure virtual machines networks. If defined, inbound_peak and inbound_burst also has to be set.

See Libvirt-QOS for further details.

7.199.3. inbound_burst
Copiar enlace

The amount of data that can be delivered in a single burst in MiB.

Used to configure virtual machines networks. If defined, inbound_average and inbound_peak also has to be set.

See Libvirt-QOS for further details.

7.199.4. inbound_peak
Copiar enlace

The maximum inbound rate in Mbps.

Used to configure virtual machines networks. If defined, inbound_average and inbound_burst also has to be set.

See Libvirt-QOS for further details.

7.199.5. max_iops
Copiar enlace

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.

7.199.6. max_read_iops
Copiar enlace

Maximum permitted number of input operations per second.

Used to configure storage. Must not be set if max_iops is set.

7.199.7. max_read_throughput
Copiar enlace

Maximum permitted throughput for read operations.

Used to configure storage. Must not be set if max_throughput is set.

7.199.8. max_throughput
Copiar enlace

Maximum permitted total throughput.

Used to configure storage. Must not be set if max_read_throughput or max_write_throughput is set.

7.199.9. max_write_iops
Copiar enlace

Maximum permitted number of output operations per second.

Used to configure storage. Must not be set if max_iops is set.

7.199.10. max_write_throughput
Copiar enlace

Maximum permitted throughput for write operations.

Used to configure storage. Must not be set if max_throughput is set.

7.199.11. outbound_average
Copiar enlace

The desired average outbound bit rate in Mbps.

Used to configure virtual machines networks. If defined, outbound_peak and outbound_burst also has to be set.

See Libvirt-QOS for further details.

7.199.12. outbound_average_linkshare
Copiar enlace

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.

7.199.13. outbound_average_realtime
Copiar enlace

The committed rate in Mbps.

Used to configure host networks. The minimum bandwidth required by a network. The committed rate requested is not guaranteed and will vary depending on the network infrastructure and the committed rate requested by other networks on the same logical link.

7.199.14. outbound_average_upperlimit
Copiar enlace

The maximum bandwidth to be used by a network in Mbps.

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.

7.199.15. outbound_burst
Copiar enlace

The amount of data that can be sent in a single burst in MiB.

Used to configure virtual machines networks. If defined, outbound_average and outbound_peak also has to be set.

See Libvirt-QOS for further details.

7.199.16. outbound_peak
Copiar enlace

The maximum outbound rate in Mbps.

Used to configure virtual machines networks. If defined, outbound_average and outbound_burst also has to be set.

See Libvirt-QOS for further details.

Expand
Table 7.261. Links summary
NameTypeSummary

data_center

DataCenter

The data center the QoS is assiciated to.

7.200. QosType enum
Copiar enlace

This type represents the kind of resource the Quality of service (QoS) can be assigned to.

Expand
Table 7.262. Values summary
NameSummary

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.

7.201. Quota struct
Copiar enlace

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>
Expand
Table 7.263. Attributes summary
NameTypeSummary

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[]

 
Expand
Table 7.264. Links summary
NameTypeSummary

permissions

Permission[]

 

quota_cluster_limits

QuotaClusterLimit[]

 

quota_storage_limits

QuotaStorageLimit[]

 

7.202. QuotaClusterLimit struct
Copiar enlace

Expand
Table 7.265. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.266. Links summary
NameTypeSummary

cluster

Cluster

 

quota

Quota

 

7.203. QuotaModeType enum
Copiar enlace

Expand
Table 7.267. Values summary
NameSummary

audit

 

disabled

 

enabled

 

7.204. QuotaStorageLimit struct
Copiar enlace

Expand
Table 7.268. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.269. Links summary
NameTypeSummary

quota

Quota

 

storage_domain

StorageDomain

 

7.205. Range struct
Copiar enlace

Expand
Table 7.270. Attributes summary
NameTypeSummary

from

String

 

to

String

 

7.206. Rate struct
Copiar enlace

Determines maximum speed of consumption of bytes from random number generator device.

Expand
Table 7.271. Attributes summary
NameTypeSummary

bytes

Integer

Number of bytes allowed to consume per period.

period

Integer

Duration of one period in milliseconds.

7.207. ReportedConfiguration struct
Copiar enlace

Expand
Table 7.272. Attributes summary
NameTypeSummary

actual_value

String

 

expected_value

String

 

in_sync

Boolean

false when the network attachment contains uncommitted network configuration.

name

String

 

7.208. ReportedDevice struct
Copiar enlace

Expand
Table 7.273. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.274. Links summary
NameTypeSummary

vm

Vm

 

7.209. ReportedDeviceType enum
Copiar enlace

Expand
Table 7.275. Values summary
NameSummary

network

 

7.210. ResolutionType enum
Copiar enlace

Expand
Table 7.276. Values summary
NameSummary

add

 

copy

 

7.211. RngDevice struct
Copiar enlace

Random number generator (RNG) device model.

Expand
Table 7.277. Attributes summary
NameTypeSummary

rate

Rate

Determines maximum speed of consumption of bytes from random number generator device.

source

RngSource

Backend of the random number generator device.

7.212. RngSource enum
Copiar enlace

Representing the random generator backend types.

Expand
Table 7.278. Values summary
NameSummary

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.

7.212.1. urandom
Copiar enlace

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.

7.213. Role struct
Copiar enlace

Represents a system role.

Expand
Table 7.279. Attributes summary
NameTypeSummary

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.

7.213.1. mutable
Copiar enlace

Defines the ability to update or delete the role.

Roles with mutable set to false are predefined roles.

Expand
Table 7.280. Links summary
NameTypeSummary

permits

Permit[]

A link to the permits sub-collection for role permits.

user

User

 

7.214. RoleType enum
Copiar enlace

Type representing whether a role is administrative or not. A user which was granted at least one administrative role is considered an administrator.

Expand
Table 7.281. Values summary
NameSummary

admin

Administrative role.

user

User role.

7.215. SchedulingPolicy struct
Copiar enlace

Expand
Table 7.282. Attributes summary
NameTypeSummary

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[]

 
Expand
Table 7.283. Links summary
NameTypeSummary

balances

Balance[]

 

filters

Filter[]

 

weight

Weight[]

 

7.216. SchedulingPolicyUnit struct
Copiar enlace

Expand
Table 7.284. Attributes summary
NameTypeSummary

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

 

7.217. ScsiGenericIO enum
Copiar enlace

Expand
Table 7.285. Values summary
NameSummary

filtered

 

unfiltered

 

7.218. SeLinux struct
Copiar enlace

Expand
Table 7.286. Attributes summary
NameTypeSummary

mode

SeLinuxMode

 

7.219. SeLinuxMode enum
Copiar enlace

Expand
Table 7.287. Values summary
NameSummary

disabled

 

enforcing

 

permissive

 

7.220. SerialNumber struct
Copiar enlace

Expand
Table 7.288. Attributes summary
NameTypeSummary

policy

SerialNumberPolicy

 

value

String

 

7.221. SerialNumberPolicy enum
Copiar enlace

Expand
Table 7.289. Values summary
NameSummary

custom

 

host

 

vm

 

7.222. Session struct
Copiar enlace

Describes a user session to a virtual machine.

Expand
Table 7.290. Attributes summary
NameTypeSummary

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.

7.222.1. console_user
Copiar enlace

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

7.222.2. ip
Copiar enlace

The IP address the user is connected from.

Currently only available for console users.

7.222.3. protocol
Copiar enlace

The protocol used by the session.

Currently not used. Intended for info about how the user is connected: through SPICE, VNC, SSH, or RDP.

Expand
Table 7.291. Links summary
NameTypeSummary

user

User

The user related to this session.

vm

Vm

A link to the virtual machine related to this session.

7.223. SkipIfConnectivityBroken struct
Copiar enlace

Expand
Table 7.292. Attributes summary
NameTypeSummary

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.

7.223.1. enabled
Copiar enlace

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.

7.223.2. threshold
Copiar enlace

Threshold for connectivity testing. If at least the threshold percentage of hosts in the cluster lost connectivity then fencing will not take place.

7.224. SkipIfSdActive struct
Copiar enlace

This type represents the storage related configuration in the fencing policy.

Expand
Table 7.293. Attributes summary
NameTypeSummary

enabled

Boolean

If enabled, we will skip fencing in case the host maintains its lease in the storage.

7.224.1. enabled
Copiar enlace

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.

7.225. Snapshot struct
Copiar enlace

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>
Expand
Table 7.294. Attributes summary
NameTypeSummary

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_shares

Integer

 

creation_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

 

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

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

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

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

 

snapshot_type

SnapshotType

 

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.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

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.

7.225.1. cpu
Copiar enlace

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>

7.225.2. custom_compatibility_version
Copiar enlace

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.

7.225.3. high_availability
Copiar enlace

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.225.4. large_icon
Copiar enlace

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.225.5. lease
Copiar enlace

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.

7.225.6. memory
Copiar enlace

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request: 

PUT /ovirt-engine/api/vms/123

With the following request body: 

<vm>
  <memory>1073741824</memory>
</vm>
Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is running.

7.225.7. migration_downtime
Copiar enlace

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]

7.225.8. next_run_configuration_exists
Copiar enlace

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.

7.225.9. origin
Copiar enlace

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.225.10. persist_memorystate
Copiar enlace

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.

7.225.11. placement_policy
Copiar enlace

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request: 

PUT /api/vms/123

With a request body like this: 

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

7.225.12. small_icon
Copiar enlace

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.225.13. sso
Copiar enlace

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.

7.225.14. stop_reason
Copiar enlace

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual machine.

Expand
Table 7.295. Links summary
NameTypeSummary

affinity_labels

AffinityLabel[]

Optional.

applications

Application[]

List of applications installed on the virtual machine.

cdroms

Cdrom[]

Reference to the ISO mounted to the CDROM.

cluster

Cluster

Reference to cluster the virtual machine belongs to.

cpu_profile

CpuProfile

Reference to CPU profile used by this virtual machine.

disk_attachments

DiskAttachment[]

References the disks attached to the virtual machine.

external_host_provider

ExternalHostProvider

 

floppies

Floppy[]

Reference to the ISO mounted to the floppy.

graphics_consoles

GraphicsConsole[]

List of graphics consoles configured for this virtual machine.

host

Host

Reference to the host the virtual machine is running on.

host_devices

HostDevice[]

References devices associated to this virtual machine.

instance_type

InstanceType

The virtual machine configuration can be optionally predefined via one of the instance types.

katello_errata

KatelloErratum[]

Lists all the Katello errata assigned to the virtual machine.

nics

Nic[]

References the list of network interface devices on the virtual machine.

numa_nodes

NumaNode[]

Refers to the NUMA Nodes configuration used by this virtual machine.

original_template

Template

References the original template used to create the virtual machine.

permissions

Permission[]

Permissions set for this virtual machine.

quota

Quota

Reference to quota configuration set for this virtual machine.

reported_devices

ReportedDevice[]

 

sessions

Session[]

List of user sessions opened for this virtual machine.

snapshots

Snapshot[]

Refers to all snapshots taken from the virtual machine.

statistics

Statistic[]

Statistics data collected from this virtual machine.

storage_domain

StorageDomain

Reference to storage domain the virtual machine belongs to.

tags

Tag[]

 

template

Template

Reference to the template the virtual machine is based on.

vm

Vm

 

vm_pool

VmPool

Reference to the pool the virtual machine is optionally member of.

watchdogs

Watchdog[]

Refers to the Watchdog configuration.

7.226. SnapshotStatus enum
Copiar enlace

Expand
Table 7.296. Values summary
NameSummary

in_preview

 

locked

 

ok

 

7.227. SnapshotType enum
Copiar enlace

Expand
Table 7.297. Values summary
NameSummary

active

 

preview

 

regular

 

stateless

 

7.228. SpecialObjects struct
Copiar enlace

This type contains references to special objects, such as blank templates and the root of a hierarchy of tags.

Expand
Table 7.298. Links summary
NameTypeSummary

blank_template

Template

A reference to a blank template.

root_tag

Tag

A reference to the root of a hierarchy of tags.

7.229. Spm struct
Copiar enlace

Expand
Table 7.299. Attributes summary
NameTypeSummary

priority

Integer

 

status

SpmStatus

 

7.230. SpmStatus enum
Copiar enlace

Expand
Table 7.300. Values summary
NameSummary

contending

 

none

 

spm

 

7.231. Ssh struct
Copiar enlace

Expand
Table 7.301. Attributes summary
NameTypeSummary

authentication_method

SshAuthenticationMethod

 

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

fingerprint

String

 

id

String

A unique identifier.

name

String

A human-readable name in plain text.

port

Integer

 

user

User

 

7.232. SshAuthenticationMethod enum
Copiar enlace

Expand
Table 7.302. Values summary
NameSummary

password

 

publickey

 

7.233. SshPublicKey struct
Copiar enlace

Expand
Table 7.303. Attributes summary
NameTypeSummary

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.

Expand
Table 7.304. Links summary
NameTypeSummary

user

User

 

7.234. Sso struct
Copiar enlace

Expand
Table 7.305. Attributes summary
NameTypeSummary

methods

Method[]

 

7.235. SsoMethod enum
Copiar enlace

Expand
Table 7.306. Values summary
NameSummary

guest_agent

 

7.236. Statistic struct
Copiar enlace

A generic type used for all kinds of statistics.

Statistic contains the statistics values for various entities. The following object contain statistics:

  • Disk
  • Host
  • HostNic
  • NumaNode
  • Nic
  • Vm
  • GlusterBrick
  • Step
  • GlusterVolume

An example of a XML representation: 

<statistics>
  <statistic id="1234" href="/ovirt-engine/api/hosts/1234/nics/1234/statistics/1234">
    <name>data.current.rx</name>
    <description>Receive data rate</description>
    <values type="DECIMAL">
      <value>
        <datum>0</datum>
      </value>
    </values>
    <type>GAUGE</type>
    <unit>BYTES_PER_SECOND</unit>
    <host_nic id="1234" href="/ovirt-engine/api/hosts/1234/nics/1234"/>
  </statistic>
  ...
</statistics>
Note

This statistics sub-collection is read-only.

Expand
Table 7.307. Attributes summary
NameTypeSummary

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.

Expand
Table 7.308. Links summary
NameTypeSummary

brick

GlusterBrick

 

disk

Disk

A relationship to the containing disk resource.

gluster_volume

GlusterVolume

 

host

Host

 

host_nic

HostNic

A reference to the host NIC.

host_numa_node

NumaNode

 

nic

Nic

 

step

Step

 

vm

Vm

 

7.237. StatisticKind enum
Copiar enlace

Expand
Table 7.309. Values summary
NameSummary

counter

 

gauge

 

7.238. StatisticUnit enum
Copiar enlace

Expand
Table 7.310. Values summary
NameSummary

bits_per_second

 

bytes

 

bytes_per_second

 

count_per_second

 

none

 

percent

 

seconds

 

7.239. Step struct
Copiar enlace

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.

Expand
Table 7.311. Attributes summary
NameTypeSummary

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.

7.239.1. external
Copiar enlace

Indicates if the step is originated by an external system. External steps are managed externally, by the creator of the step.

Expand
Table 7.312. Links summary
NameTypeSummary

execution_host

Host

The host used for the step execution (optional).

job

Job

References the job which is the top of the current step hierarchy.

parent_step

Step

References the parent step of the current step in the hierarchy.

statistics

Statistic[]

 

7.240. StepEnum enum
Copiar enlace

Type representing a step type.

Expand
Table 7.313. Values summary
NameSummary

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.

7.240.1. executing
Copiar enlace

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.

7.240.2. finalizing
Copiar enlace

The finalizing step type. Describes the post-execution steps requires to complete the job.

7.240.3. rebalancing_volume
Copiar enlace

The rebalancing volume step type. Describes a step type which is part of Gluster flow.

7.240.4. removing_bricks
Copiar enlace

The removing bricks step type. Describes a step type which is part of Gluster flow.

7.240.5. unknown
Copiar enlace

The unknown step type. Describes a step type which its origin is unknown.

7.240.6. validating
Copiar enlace

The validation step type. Used to verify the correctness of parameters and the validity of the parameters prior to the execution.

7.241. StepStatus enum
Copiar enlace

Represents the status of the step.

Expand
Table 7.314. Values summary
NameSummary

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.

7.241.1. aborted
Copiar enlace

The aborted step status. This status is applicable for an external step that was forcibly aborted.

7.241.2. finished
Copiar enlace

The finished step status. This status describes a completed step execution.

7.241.3. started
Copiar enlace

The started step status. This status represents a step which is currently being executed.

7.241.4. unknown
Copiar enlace

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.

7.242. StorageConnection struct
Copiar enlace

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>
Expand
Table 7.315. Attributes summary
NameTypeSummary

address

String

 

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

mount_options

String

 

name

String

A human-readable name in plain text.

nfs_retrans

Integer

 

nfs_timeo

Integer

 

nfs_version

NfsVersion

 

password

String

 

path

String

 

port

Integer

 

portal

String

 

target

String

 

type

StorageType

 

username

String

 

vfs_type

String

 
Expand
Table 7.316. Links summary
NameTypeSummary

host

Host

 

7.243. StorageConnectionExtension struct
Copiar enlace

Expand
Table 7.317. Attributes summary
NameTypeSummary

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

 
Expand
Table 7.318. Links summary
NameTypeSummary

host

Host

 

7.244. StorageDomain struct
Copiar enlace

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>
Expand
Table 7.319. Attributes summary
NameTypeSummary

available

Integer

 

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.

7.244.1. discard_after_delete
Copiar enlace

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.

7.244.2. supports_discard
Copiar enlace

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. Since the engine cannot check if the underlying block device supports discard for file storage domains, this attribute will not be reported for them at all.

7.244.3. supports_discard_zeroes_data
Copiar enlace

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. This is one of the conditions necessary for a virtual disk in this storage domain to have both wipe_after_delete and pass_discard attributes enabled. Since the engine cannot check if the underlying block device supports the property that discard zeroes the data for file storage domains, this attribute will not be reported for them at all.

7.244.4. wipe_after_delete
Copiar enlace

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.

Expand
Table 7.320. Links summary
NameTypeSummary

data_center

DataCenter

A link to the data center that the storage domain is attached to.

data_centers

DataCenter[]

A set of links to the data centers that the storage domain is attached to.

disk_profiles

DiskProfile[]

 

disk_snapshots

DiskSnapshot[]

 

disks

Disk[]

 

files

File[]

 

host

Host

Host is only relevant at creation time.

images

Image[]

 

permissions

Permission[]

 

storage_connections

StorageConnection[]

 

templates

Template[]

 

vms

Vm[]

 

7.245. StorageDomainLease struct
Copiar enlace

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.

Expand
Table 7.321. Links summary
NameTypeSummary

storage_domain

StorageDomain

Reference to the storage domain on which the lock resides on.

7.246. StorageDomainStatus enum
Copiar enlace

Expand
Table 7.322. Values summary
NameSummary

activating

 

active

 

detaching

 

inactive

 

locked

 

maintenance

 

mixed

 

preparing_for_maintenance

 

unattached

 

unknown

 

7.247. StorageDomainType enum
Copiar enlace

Expand
Table 7.323. Values summary
NameSummary

data

 

export

 

image

 

iso

 

volume

 

7.248. StorageFormat enum
Copiar enlace

Expand
Table 7.324. Values summary
NameSummary

v1

 

v2

 

v3

 

v4

Version 4 of the storage domain format.

7.249. StorageType enum
Copiar enlace

Type representing a storage domain type.

Expand
Table 7.325. Values summary
NameSummary

cinder

Cinder storage domain.

fcp

Fibre-Channel storage domain.

glance

Glance storage domain.

glusterfs

Gluster-FS storage domain.

iscsi

iSCSI storage domain.

localfs

Storage domain on Local storage.

nfs

NFS storage domain.

posixfs

POSIX-FS storage domain.

7.249.1. cinder
Copiar enlace

Cinder storage domain. For more details on Cinder please go to Cinder.

7.249.2. glance
Copiar enlace

Glance storage domain. For more details on Glance please go to Glance.

7.249.3. glusterfs
Copiar enlace

Gluster-FS storage domain. For more details on Gluster please go to Gluster.

7.250. SwitchType enum
Copiar enlace

Describes all switch types supported by the Manager.

Expand
Table 7.326. Values summary
NameSummary

legacy

The native switch type.

ovs

The Open vSwitch type.

7.251. Tag struct
Copiar enlace

Represents a tag in the system.

Expand
Table 7.327. Attributes summary
NameTypeSummary

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.

Expand
Table 7.328. Links summary
NameTypeSummary

group

Group

Reference to the group which has this tag assigned.

host

Host

Reference to the host which has this tag assigned.

parent

Tag

Reference to the parent tag of this tag.

template

Template

Reference to the template which has this tag assigned.

user

User

Reference to the user who has this tag assigned.

vm

Vm

Reference to the virtual machine which has this tag assigned.

7.252. Template struct
Copiar enlace

Type representing a virtual machine template. This allows a rapid instanstiation of virtual machines with common configuration and disk states.

Expand
Table 7.329. Attributes summary
NameTypeSummary

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_shares

Integer

 

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

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

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

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

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 a base version or a sub version of another template.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

vm

Vm

The virtual machine configuration associated with this template.

7.252.1. cpu
Copiar enlace

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>

7.252.2. custom_compatibility_version
Copiar enlace

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.

7.252.3. high_availability
Copiar enlace

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.252.4. large_icon
Copiar enlace

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.252.5. lease
Copiar enlace

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.

7.252.6. memory
Copiar enlace

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request: 

PUT /ovirt-engine/api/vms/123

With the following request body: 

<vm>
  <memory>1073741824</memory>
</vm>
Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is running.

7.252.7. migration_downtime
Copiar enlace

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]

7.252.8. origin
Copiar enlace

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.252.9. small_icon
Copiar enlace

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.252.10. sso
Copiar enlace

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.

Expand
Table 7.330. Links summary
NameTypeSummary

cdroms

Cdrom[]

References to the CD-ROM devices attached to the template.

cluster

Cluster

Reference to cluster the virtual machine belongs to.

cpu_profile

CpuProfile

Reference to CPU profile used by this virtual machine.

disk_attachments

DiskAttachment[]

References to the disks attached to the template.

graphics_consoles

GraphicsConsole[]

References to the graphic consoles attached to the template.

nics

Nic[]

References to the network interfaces attached to the template.

permissions

Permission[]

References to the user permissions attached to the template.

quota

Quota

Reference to quota configuration set for this virtual machine.

storage_domain

StorageDomain

Reference to storage domain the virtual machine belongs to.

tags

Tag[]

References to the tags attached to the template.

watchdogs

Watchdog[]

References to the watchdog devices attached to the template.

7.253. TemplateStatus enum
Copiar enlace

Type representing a status of a virtual machine template.

Expand
Table 7.331. Values summary
NameSummary

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.

7.254. TemplateVersion struct
Copiar enlace

Type representing a version of a virtual machine template.

Expand
Table 7.332. Attributes summary
NameTypeSummary

version_name

String

The name of this version.

version_number

Integer

The index of this version in the versions hierarchy of the template.

7.254.1. version_number
Copiar enlace

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.

Expand
Table 7.333. Links summary
NameTypeSummary

base_template

Template

References the template that this version is associated with.

7.255. Ticket struct
Copiar enlace

Type representing a ticket that allows virtual machine access.

Expand
Table 7.334. Attributes summary
NameTypeSummary

expiry

Integer

Time to live for the ticket in seconds.

value

String

The virtual machine access ticket.

7.256. TimeZone struct
Copiar enlace

Time zone representation.

Expand
Table 7.335. Attributes summary
NameTypeSummary

name

String

Name of the time zone.

utc_offset

String

Offset from https://en.

7.256.1. utc_offset
Copiar enlace

Offset from UTC.

7.257. TransparentHugePages struct
Copiar enlace

Type representing a transparent huge pages (THP) support.

Expand
Table 7.336. Attributes summary
NameTypeSummary

enabled

Boolean

Enable THP support.

7.258. TransportType enum
Copiar enlace

Protocol used to access a Gluster volume.

Expand
Table 7.337. Values summary
NameSummary

rdma

Remote direct memory access.

tcp

TCP.

7.259. UnmanagedNetwork struct
Copiar enlace

Expand
Table 7.338. Attributes summary
NameTypeSummary

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.

Expand
Table 7.339. Links summary
NameTypeSummary

host

Host

 

host_nic

HostNic

 

7.260. Usb struct
Copiar enlace

Expand
Table 7.340. Attributes summary
NameTypeSummary

enabled

Boolean

 

type

UsbType

 

7.261. UsbType enum
Copiar enlace

Expand
Table 7.341. Values summary
NameSummary

legacy

A legacy USB type.

native

 

7.261.1. legacy
Copiar enlace

A legacy USB type.

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.

7.262. User struct
Copiar enlace

Represents a user in the system.

Expand
Table 7.342. Attributes summary
NameTypeSummary

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.

7.262.1. namespace
Copiar enlace

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 https://github.com/oVirt/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 https://github.com/oVirt/ovirt-engine-extension-aaa-jdbc for more information.

7.262.2. principal
Copiar enlace

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

7.262.3. user_name
Copiar enlace

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.

Expand
Table 7.343. Links summary
NameTypeSummary

domain

Domain

 

groups

Group[]

 

permissions

Permission[]

 

roles

Role[]

A link to the roles sub-collection for user resources.

ssh_public_keys

SshPublicKey[]

 

tags

Tag[]

A link to the tags sub-collection for user resources.

7.263. Value struct
Copiar enlace

Expand
Table 7.344. Attributes summary
NameTypeSummary

datum

Decimal

 

detail

String

 

7.264. ValueType enum
Copiar enlace

Expand
Table 7.345. Values summary
NameSummary

decimal

 

integer

 

string

 

7.265. VcpuPin struct
Copiar enlace

Expand
Table 7.346. Attributes summary
NameTypeSummary

cpu_set

String

 

vcpu

Integer

 

7.266. Vendor struct
Copiar enlace

Expand
Table 7.347. Attributes summary
NameTypeSummary

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.

7.267. Version struct
Copiar enlace

Expand
Table 7.348. Attributes summary
NameTypeSummary

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

 

7.268. VirtioScsi struct
Copiar enlace

Type representing the support of virtio-SCSI. If it supported we use virtio driver for SCSI guest device.

Expand
Table 7.349. Attributes summary
NameTypeSummary

enabled

Boolean

Enable Virtio SCSI support.

7.269. VirtualNumaNode struct
Copiar enlace

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>
Expand
Table 7.350. Attributes summary
NameTypeSummary

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[]

 
Expand
Table 7.351. Links summary
NameTypeSummary

host

Host

 

statistics

Statistic[]

Each host NUMA node resource exposes a statistics sub-collection for host NUMA node specific statistics.

vm

Vm

 

7.270. Vlan struct
Copiar enlace

Type representing a Virtual LAN (VLAN) type.

Expand
Table 7.352. Attributes summary
NameTypeSummary

id

Integer

Virtual LAN ID.

7.271. Vm struct
Copiar enlace

Represents a virtual machine.

Expand
Table 7.353. Attributes summary
NameTypeSummary

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_shares

Integer

 

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

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

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

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.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

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.

7.271.1. cpu
Copiar enlace

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>

7.271.2. custom_compatibility_version
Copiar enlace

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.

7.271.3. high_availability
Copiar enlace

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.271.4. large_icon
Copiar enlace

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.271.5. lease
Copiar enlace

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.

7.271.6. memory
Copiar enlace

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request: 

PUT /ovirt-engine/api/vms/123

With the following request body: 

<vm>
  <memory>1073741824</memory>
</vm>
Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is running.

7.271.7. migration_downtime
Copiar enlace

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]

7.271.8. next_run_configuration_exists
Copiar enlace

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.

7.271.9. origin
Copiar enlace

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.271.10. placement_policy
Copiar enlace

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request: 

PUT /api/vms/123

With a request body like this: 

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

7.271.11. small_icon
Copiar enlace

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.271.12. sso
Copiar enlace

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.

7.271.13. stop_reason
Copiar enlace

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual machine.

Expand
Table 7.354. Links summary
NameTypeSummary

affinity_labels

AffinityLabel[]

Optional.

applications

Application[]

List of applications installed on the virtual machine.

cdroms

Cdrom[]

Reference to the ISO mounted to the CDROM.

cluster

Cluster

Reference to cluster the virtual machine belongs to.

cpu_profile

CpuProfile

Reference to CPU profile used by this virtual machine.

disk_attachments

DiskAttachment[]

References the disks attached to the virtual machine.

external_host_provider

ExternalHostProvider

 

floppies

Floppy[]

Reference to the ISO mounted to the floppy.

graphics_consoles

GraphicsConsole[]

List of graphics consoles configured for this virtual machine.

host

Host

Reference to the host the virtual machine is running on.

host_devices

HostDevice[]

References devices associated to this virtual machine.

instance_type

InstanceType

The virtual machine configuration can be optionally predefined via one of the instance types.

katello_errata

KatelloErratum[]

Lists all the Katello errata assigned to the virtual machine.

nics

Nic[]

References the list of network interface devices on the virtual machine.

numa_nodes

NumaNode[]

Refers to the NUMA Nodes configuration used by this virtual machine.

original_template

Template

References the original template used to create the virtual machine.

permissions

Permission[]

Permissions set for this virtual machine.

quota

Quota

Reference to quota configuration set for this virtual machine.

reported_devices

ReportedDevice[]

 

sessions

Session[]

List of user sessions opened for this virtual machine.

snapshots

Snapshot[]

Refers to all snapshots taken from the virtual machine.

statistics

Statistic[]

Statistics data collected from this virtual machine.

storage_domain

StorageDomain

Reference to storage domain the virtual machine belongs to.

tags

Tag[]

 

template

Template

Reference to the template the virtual machine is based on.

vm_pool

VmPool

Reference to the pool the virtual machine is optionally member of.

watchdogs

Watchdog[]

Refers to the Watchdog configuration.

7.272. VmAffinity enum
Copiar enlace

Expand
Table 7.355. Values summary
NameSummary

migratable

 

pinned

 

user_migratable

 

7.273. VmBase struct
Copiar enlace

Represents basic virtual machine configuration. This is used by virtual machines, templates and instance types.

Expand
Table 7.356. Attributes summary
NameTypeSummary

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_shares

Integer

 

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

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

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

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

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.

7.273.1. cpu
Copiar enlace

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>

7.273.2. custom_compatibility_version
Copiar enlace

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.

7.273.3. high_availability
Copiar enlace

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.273.4. large_icon
Copiar enlace

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.273.5. lease
Copiar enlace

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.

7.273.6. memory
Copiar enlace

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request: 

PUT /ovirt-engine/api/vms/123

With the following request body: 

<vm>
  <memory>1073741824</memory>
</vm>
Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is running.

7.273.7. migration_downtime
Copiar enlace

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]

7.273.8. origin
Copiar enlace

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.273.9. small_icon
Copiar enlace

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.273.10. sso
Copiar enlace

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.

Expand
Table 7.357. Links summary
NameTypeSummary

cluster

Cluster

Reference to cluster the virtual machine belongs to.

cpu_profile

CpuProfile

Reference to CPU profile used by this virtual machine.

quota

Quota

Reference to quota configuration set for this virtual machine.

storage_domain

StorageDomain

Reference to storage domain the virtual machine belongs to.

7.274. VmDeviceType enum
Copiar enlace

Expand
Table 7.358. Values summary
NameSummary

cdrom

 

floppy

 

7.275. VmPlacementPolicy struct
Copiar enlace

Expand
Table 7.359. Attributes summary
NameTypeSummary

affinity

VmAffinity

 
Expand
Table 7.360. Links summary
NameTypeSummary

hosts

Host[]

 

7.276. VmPool struct
Copiar enlace

Expand
Table 7.361. Attributes summary
NameTypeSummary

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

 

id

String

A unique identifier.

max_user_vms

Integer

 

name

String

A human-readable name in plain text.

prestarted_vms

Integer

 

rng_device

RngDevice

 

size

Integer

 

soundcard_enabled

Boolean

 

stateful

Boolean

Virtual machine pool’s stateful flag.

type

VmPoolType

 

use_latest_template_version

Boolean

 

7.276.1. auto_storage_select
Copiar enlace

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.

7.276.2. stateful
Copiar enlace

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.

Expand
Table 7.362. Links summary
NameTypeSummary

cluster

Cluster

 

instance_type

InstanceType

Reference to the instance type on which this pool is based.

permissions

Permission[]

 

template

Template

 

vm

Vm

 

7.277. VmPoolType enum
Copiar enlace

Expand
Table 7.363. Values summary
NameSummary

automatic

 

manual

 

7.278. VmStatus enum
Copiar enlace

Type represeting a status of a virtual machine.

Expand
Table 7.364. Values summary
NameSummary

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.

7.278.1. paused
Copiar enlace

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.

7.278.2. powering_up
Copiar enlace

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.

7.278.3. restoring_state
Copiar enlace

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.

7.278.4. saving_state
Copiar enlace

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.

7.278.5. suspended
Copiar enlace

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.

7.278.6. unknown
Copiar enlace

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.

7.278.7. up
Copiar enlace

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.

7.278.8. wait_for_launch
Copiar enlace

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.

7.279. VmSummary struct
Copiar enlace

Expand
Table 7.365. Attributes summary
NameTypeSummary

active

Integer

 

migrating

Integer

 

total

Integer

 

7.280. VmType enum
Copiar enlace

Type representing what the virtual machine is optimized for.

Expand
Table 7.366. Values summary
NameSummary

desktop

The virtual machine is intended to be used as a desktop.

server

The virtual machine is intended to be used as a server.

7.280.1. desktop
Copiar enlace

The virtual machine is intended to be used as a desktop. Currently, its implication is that a sound device will be automatically added to the virtual machine.

7.280.2. server
Copiar enlace

The virtual machine is intended to be used as a server. Currently, its implication is that a sound device will not be automatically added to the virtual machine.

7.281. VnicPassThrough struct
Copiar enlace

Expand
Table 7.367. Attributes summary
NameTypeSummary

mode

VnicPassThroughMode

Defines whether the vNIC will be implemented as a virtual device, or as a pass-through to a host device.

7.282. VnicPassThroughMode enum
Copiar enlace

Describes whether the vNIC is to be implemented as a pass-through device or a virtual one.

Expand
Table 7.368. Values summary
NameSummary

disabled

To be implemented as a virtual device.

enabled

To be implemented as a pass-through device.

7.283. VnicProfile struct
Copiar enlace

A vNIC profile is a collection of settings that can be applied to individual NIC.

Expand
Table 7.369. Attributes summary
NameTypeSummary

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 the passthrough to a SR-IOV-enabled host NIC.

port_mirroring

Boolean

Enables port mirroring.

7.283.1. migratable
Copiar enlace

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 request, by default, this will be set to true.

When migrating virtual machine, this virtual machine will be migrated only if all pass_through NICs are flagged as migratable.

7.283.2. pass_through
Copiar enlace

Enables the passthrough to a 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.

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

7.283.3. port_mirroring
Copiar enlace

Enables port mirroring.

Port mirroring copies layer 3 network traffic on a given logical networkand 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 machine on the same host and logical network. The only traffic copied is internal to one logical network on one host. There is no increase on 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 plugging 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.

Important

Enabling port mirroring reduces the privacy of other network users.

Expand
Table 7.370. Links summary
NameTypeSummary

network

Network

Reference to the network that the vNIC profile is applied to.

network_filter

NetworkFilter

Reference to the top-level network filter that apply to the NICs that use this profile.

permissions

Permission[]

Permissions to allow usage of the vNIC profile.

qos

Qos

Reference to the quality of service attributes to apply to the vNIC profile.

7.284. VnicProfileMapping struct
Copiar enlace

Maps an external virtual NIC profile to one that exists in the Red Hat Virtualization Manager.

If, for example, the desired virtual NIC profile’s mapping includes the following two lines:

Expand
Source network nameSource network profile nameTarget virtual NIC profile ID

red

gold

738dd914-8ec8-4a8b-8628-34672a5d449b

blue

silver

892a12ec-2028-4451-80aa-ff3bf55d6bac

It should be expressed in the following form: 

<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>
Expand
Table 7.371. Attributes summary
NameTypeSummary

source_network_name

String

Specifies the name of the external network.

source_network_profile_name

String

Specifies the name of the external network profile.

Expand
Table 7.372. Links summary
NameTypeSummary

target_vnic_profile

VnicProfile

Points to an existing virtual NIC profile.

7.285. VolumeGroup struct
Copiar enlace

Expand
Table 7.373. Attributes summary
NameTypeSummary

id

String

 

logical_units

LogicalUnit[]

 

name

String

 

7.286. Watchdog struct
Copiar enlace

This type represents a watchdog configuration.

Expand
Table 7.374. Attributes summary
NameTypeSummary

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.

7.286.1. model
Copiar enlace

Model of watchdog device. Currently supported only I6300ESB.

Expand
Table 7.375. Links summary
NameTypeSummary

instance_type

InstanceType

Optionally references to an instance type the device is used by.

template

Template

Optionally references to a template the device is used by.

vm

Vm

Don’t use this element, use vms instead.

vms

Vm[]

References to the virtual machines that are using this device.

7.287. WatchdogAction enum
Copiar enlace

This type describes available watchdog actions.

Expand
Table 7.376. Values summary
NameSummary

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.

7.287.1. none
Copiar enlace

No action will be performed when watchdog action is triggered. However log message will still be generated.

7.288. WatchdogModel enum
Copiar enlace

This type represents the watchdog model.

Expand
Table 7.377. Values summary
NameSummary

i6300esb

Currently only model supported is model I6300ESB.

7.289. Weight struct
Copiar enlace

Expand
Table 7.378. Attributes summary
NameTypeSummary

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.

Expand
Table 7.379. Links summary
NameTypeSummary

scheduling_policy

SchedulingPolicy

 

scheduling_policy_unit

SchedulingPolicyUnit

 

Appendix A. Primitive types
Copiar enlace

This section describes the primitive data types supported by the API.

A.1. String primitive
Copiar enlace

A finite sequence of Unicode characters.

A.2. Boolean primitive
Copiar enlace

Represents the false and true concepts used in mathematical logic.

The valid values are the strings false and true.

Case is ignored by the engine, so for example False and FALSE also valid values. However the server will always return lower case values.

For backwards compatibility with older versions of the engine, the values 0 and 1 are also accepted. The value 0 has the same meaning than false, and 1 has the same meaning than true. Try to avoid using these values, as support for them may be removed in the future.

A.3. Integer primitive
Copiar enlace

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

Note

In the future the integer type will be implemented using unlimited precission integers, so the above limitations and exceptions will eventually disappear.

A.4. Decimal primitive
Copiar enlace

Represents the mathematical concept of real number.

Currently the engine implements this type using 32 bit IEEE 754 single precision floating point numbers.

For some attributes this isn’t enough precision. In those exceptional cases the engine uses 64 bit double precision floating point numbers, in particular for the following attributes:

  • QuotaStorageLimit.usage
  • QuotaStorageLimit.memory_limit
  • QuotaStorageLimit.memory_usage
Note

In the future the decimal type will be implemented using unlimited precision decimal numbers, so the above limitations and exceptions will eventually disappear.

A.5. Date primitive
Copiar enlace

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 seconds since Jan 1st 1970, also know as epoch time. For example, if you send a request like this to retrieve the JSON representation of a virtual machine: 

GET /ovirt-engine/api/vms/123
Accept: application/json

The response body will contain the following JSON document: 

{
  "id": "123",
  "href="/ovirt-engine/api/vms/123",
  ...
  "creation_time": 1472564909990,
  ...
}
Note

In both cases, the dates returned by the engine use the time zone configured in the server where it is running, in the above examples it is UTC+2.

Appendix B. Changes in version 4 of the API
Copiar enlace

This section enumerates the backwards compatibility breaking changes that have been introduced in version 4 of the API.

B.1. Removed YAML support
Copiar enlace

The support for YAML has been completely removed.

B.2. Renamed complex types
Copiar enlace

The following XML schema complex types have been renamed:

Expand
Version 3Version 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

B.3. Replaced the Status type with enum types
Copiar enlace

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>

B.4. Remove the NIC network and port_mirroring properties
Copiar enlace

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.

B.5. Remove the NIC active property
Copiar enlace

The NIC active property was replaced by plugged some time ago. It has been completely removed now.

B.6. Remove the disk type property
Copiar enlace

The type property of disks has been removed, but kept in the XML schema and ignored. It has been completely removed now.

B.7. Remove the disk size property
Copiar enlace

The disk size property has been replaced by provisioned_size long ago. It has been completely removed now.

B.8. Removed support for pinning a VM to a single host
Copiar enlace

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.

B.9. Removed the capabilities.permits element
Copiar enlace

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>

B.10. Removed the storage_manager element
Copiar enlace

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.

B.11. Removed the data center storage_type element
Copiar enlace

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.

B.12. Remove the timezone element
Copiar enlace

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.

B.13. Removed the guest_info element
Copiar enlace

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.

B.14. Replaced CPU id attribute with type element
Copiar enlace

The cpu element used to have an id attribute that indicates the type of CPU: 

<cpu id="Intel Conroe 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 Conroe Family</type>
  <architecture>X86_64</architecture>
</cpu>

B.15. Use elements instead of attributes in CPU topology
Copiar enlace

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>

B.16. Use elements instead of attributes in VCPU pin
Copiar enlace

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>

B.17. Use elements instead of attributes in VCPU pin
Copiar enlace

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>

B.18. Use elements instead of attributes in memory overcommit
Copiar enlace

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>

B.19. Use elements instead of attributes in console
Copiar enlace

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>

B.20. Use elements instead of attributes in VIRTIO SCSI
Copiar enlace

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>

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>

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>

B.23. Use elements instead of attributes in IP address:
Copiar enlace

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>

B.24. Use elements instead of attributes in MAC address:
Copiar enlace

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>

B.25. Use elements instead of attributes in boot device:
Copiar enlace

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>

B.26. Use element instead of attribute for operating system type
Copiar enlace

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>

B.27. Removed the force parameter from the request to retrieve a host
Copiar enlace

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

B.28. Removed deprecated host power management configuration
Copiar enlace

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.

B.29. Use multiple boot.devices.device instead of multiple boot
Copiar enlace

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>

B.30. Removed the disks.clone and disks.detach_only elements
Copiar enlace

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 don’t 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

B.31. Rename element vmpool to vm_pool
Copiar enlace

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.

B.32. Use logical_units instead of multiple logical_unit
Copiar enlace

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>

B.33. Removed the snapshots.collapse_snapshots element
Copiar enlace

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

B.34. Renamed storage and host_storage elements
Copiar enlace

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>

B.35. Removed the permissions.clone element
Copiar enlace

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>

B.36. Renamed the random number generator source elements
Copiar enlace

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.

B.37. Removed the intermediate tag.parent element
Copiar enlace

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>

B.38. Remove scheduling built-in names and thresholds
Copiar enlace

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.

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

B.40. Renamed the statistics type property to kind
Copiar enlace

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>

B.41. Use multiple vcpu_pins.vcpu_pin instead of multiple vcpu_pin
Copiar enlace

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>

B.42. Use force parameter to force remove a data center
Copiar enlace

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

B.43. Use force parameter to force remove a host
Copiar enlace

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

B.44. Use parameters for force remove storage domain
Copiar enlace

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

B.45. Use host parameter to remove storage server connection
Copiar enlace

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

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

B.47. Don’t remove disks via the VM disk API
Copiar enlace

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

B.48. Use force query parameter to force remove a virtual machine
Copiar enlace

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

B.49. Use POST instead of DELETE to remove multiple bricks
Copiar enlace

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>

B.50. Removed the scheduling_policy.policy element
Copiar enlace

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>

B.51. Added snapshot.snapshot_type
Copiar enlace

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>

B.52. Removed move action from VM
Copiar enlace

The deprecated move action of the VM entity has been removed. Instead, you can move inidividual disks.

B.53. Moved reported_configurations.in_sync to network_attachment
Copiar enlace

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>

B.54. Replaced capabilities with clusterlevels
Copiar enlace

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 Conroe 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 Conroe Family</name>
      <level>2</level>
      <architecture>x86_64</architecture>
    </cpu_type>
    ...
  </cpu_types>
  ...
</cluster_level>

B.55. Replaced disks with diskattachments
Copiar enlace

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>

B.56. Use iscsi_targets element to discover unregistered storage
Copiar enlace

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>
Red Hat logoGithubredditYoutubeTwitter

Aprender

Pruebe, compre y venda

Comunidades

Acerca de la documentación de Red Hat

Ayudamos a los usuarios de Red Hat a innovar y alcanzar sus objetivos con nuestros productos y servicios con contenido en el que pueden confiar. Explore nuestras recientes actualizaciones.

Hacer que el código abierto sea más inclusivo

Red Hat se compromete a reemplazar el lenguaje problemático en nuestro código, documentación y propiedades web. Para más detalles, consulte el Blog de Red Hat.

Acerca de Red Hat

Ofrecemos soluciones reforzadas que facilitan a las empresas trabajar en plataformas y entornos, desde el centro de datos central hasta el perímetro de la red.

Theme

© 2026 Red HatVolver arriba