Red Hat Training

A Red Hat training course is available for Red Hat Virtualization

REST API Guide

Red Hat Virtualization 4.0

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

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

The benefits of the API are:

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

This provides developers and administrators with the ability to:

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

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

1.1. Representational State Transfer

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

1.2. API Prerequisites

Prerequisites for using the Red Hat Virtualization API:

  • A networked installation of Red Hat Virtualization Manager, which includes the API.
  • A client or programming library that initiates and receives HTTP requests from the API server. For example:

  • 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

2.1. TLS/SSL Certification

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

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

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

2.2. Authentication

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

2.2.1. OAuth Authentication

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

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

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

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

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

Table 2.1. OAuth token request parameters

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

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.

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

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

2.2.3.1. Requesting an Authenticated Session

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

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

    This returns a response with the following header:

    Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/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. Quick start example

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

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

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

Important

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

Important

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

Note

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

Note

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

3.1. Example: Access API entry point

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

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.

3.2. Example: List data centers

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

The following request retrieves a representation of the data centers:

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

Same request, using the curl command:

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

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

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

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

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

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

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

3.3. Example: List host clusters

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

The following request retrieves a representation of the cluster collection:

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

Same request, using the curl command:

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

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

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

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

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

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

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

3.4. Example: List logical networks

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

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

The following request retrieves the list of logical networks:

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

Same request, using the curl command:

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

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

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

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

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

3.5. Example: List hosts

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

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

Same request, using the curl command:

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

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

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

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

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

3.6. Example: Create NFS data storage

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

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

The request should be like this:

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

And the request body should be like this:

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

The same request, using the curl command:

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

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

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

3.7. Example: Create NFS ISO storage

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

The request should be like this:

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

And the request body should be like this:

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

The same request, using the curl command:

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

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

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

3.8. Example: Attach storage domains to data center

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

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

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

With a request body like this:

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

Same request, using the curl command:

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

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

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

With a request body like this:

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

Same request, using the curl command:

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

3.9. Example: Create virtual machine

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

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

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

And the request body should be like this:

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

Same request, using the curl command:

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

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

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

3.10. Example: Create a virtual machine NIC

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

The request should be like this:

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

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

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

Same request, using the curl command:

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

3.11. Example: Create virtual disk

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

The request should be like this:

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

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

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

Same request, using the curl command:

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

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

3.12. Example: Attach ISO image to virtual machine

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

ISO images must be available in the myisos ISO domain for the virtual machines to use. 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.

3.13. Example: Start the virtual machine

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

The request should be like this:

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

The request body should be like this:

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

Same request, using the curl command:

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

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

Chapter 4. Requests

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

Chapter 5. Services

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

5.1. AffinityGroup

This service manages a single affinity group.

Table 5.1. Methods summary

NameSummary

get

Retrieve the affinity group details.

remove

Remove the affinity group.

update

Update the affinity group.

5.1.1. get GET

Retrieve the affinity group details.

<affinity_group id="00000000-0000-0000-0000-000000000000">
  <name>AF_GROUP_001</name>
  <cluster id="00000000-0000-0000-0000-000000000000"/>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>

Table 5.2. Parameters summary

NameTypeDirectionSummary

group

AffinityGroup

Out

The affinity group.

5.1.2. remove DELETE

Remove the affinity group.

DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456

Table 5.3. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.1.3. update PUT

Update the affinity group.

Table 5.4. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

group

AffinityGroup

In/Out

The affinity group.

5.2. AffinityGroupVm

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

Table 5.5. Methods summary

NameSummary

remove

Remove this virtual machine from the affinity group.

5.2.1. remove DELETE

Remove this virtual machine from the affinity group.

Table 5.6. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.3. AffinityGroupVms

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

Table 5.7. Methods summary

NameSummary

add

Add a virtual machine to the affinity group.

list

List all virtual machines assigned to this affinity group.

5.3.1. add POST

Add a virtual machine to the affinity group.

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

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

With the following body:

<vm id="000-000"/>

Table 5.8. Parameters summary

NameTypeDirectionSummary

vm

Vm

In/Out

 

5.3.2. list GET

List all virtual machines assigned to this affinity group.

Table 5.9. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of virtual machines to return.

vms

Vm[]

Out

 

5.3.2.1. max

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

5.4. AffinityGroups

Affinity groups service manages virtual machine relationships and dependencies.

Table 5.10. Methods summary

NameSummary

add

Create a new affinity group.

list

List existing affinity groups.

5.4.1. add POST

Create a new affinity group.

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

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

And use the following example in its body:

<affinity_group>
  <name>AF_GROUP_001</name>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>

Table 5.11. Parameters summary

NameTypeDirectionSummary

group

AffinityGroup

In/Out

The affinity group object to create.

5.4.2. list GET

List existing affinity groups.

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

5.4.2.1. max

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

5.5. AffinityLabel

Single affinity label details.

Table 5.13. Methods summary

NameSummary

get

Retrieves details about a label.

remove

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

update

Updates a label.

5.5.1. get GET

Retrieves details about a label.

Table 5.14. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel

Out

 

5.5.2. remove DELETE

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

5.5.3. update PUT

Updates a label.

This call will update all metadata like name or description.

Table 5.15. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

5.6. AffinityLabelHost

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

Table 5.16. Methods summary

NameSummary

get

Retrieves details about a host that has this label assigned.

remove

Remove a label from a host.

5.6.1. get GET

Retrieves details about a host that has this label assigned.

Table 5.17. Parameters summary

NameTypeDirectionSummary

host

Host

Out

 

5.6.2. remove DELETE

Remove a label from a host.

5.7. AffinityLabelHosts

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

Table 5.18. Methods summary

NameSummary

add

Add a label to a host.

list

List all hosts with the label.

5.7.1. add POST

Add a label to a host.

Table 5.19. Parameters summary

NameTypeDirectionSummary

host

Host

In/Out

 

5.7.2. list GET

List all hosts with the label.

Table 5.20. Parameters summary

NameTypeDirectionSummary

hosts

Host[]

Out

 

5.8. AffinityLabelVm

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

Table 5.21. Methods summary

NameSummary

get

Retrieves details about a vm that has this label assigned.

remove

Remove a label from a vm.

5.8.1. get GET

Retrieves details about a vm that has this label assigned.

Table 5.22. Parameters summary

NameTypeDirectionSummary

vm

Vm

Out

 

5.8.2. remove DELETE

Remove a label from a vm.

5.9. AffinityLabelVms

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

Table 5.23. Methods summary

NameSummary

add

Add a label to a vm.

list

List all vms with the label.

5.9.1. add POST

Add a label to a vm.

Table 5.24. Parameters summary

NameTypeDirectionSummary

vm

Vm

In/Out

 

5.9.2. list GET

List all vms with the label.

Table 5.25. Parameters summary

NameTypeDirectionSummary

vms

Vm[]

Out

 

5.10. AffinityLabels

Manages the affinity labels available in the system.

Table 5.26. Methods summary

NameSummary

add

Creates a new label.

list

Lists all labels present in the system.

5.10.1. add POST

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

Table 5.27. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

5.10.2. list GET

Lists all labels present in the system.

Table 5.28. Parameters summary

NameTypeDirectionSummary

labels

AffinityLabel[]

Out

 

max

Integer

In

Sets the maximum number of labels to return.

5.10.2.1. max

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

5.11. AssignedAffinityLabel

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

Table 5.29. Methods summary

NameSummary

get

Retrieves details about the attached label.

remove

Removes the label from an entity.

5.11.1. get GET

Retrieves details about the attached label.

Table 5.30. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel

Out

 

5.11.2. remove DELETE

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

5.12. AssignedAffinityLabels

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

Table 5.31. Methods summary

NameSummary

add

Attaches a label to an entity.

list

Lists all labels that are attached to an entity.

5.12.1. add POST

Attaches a label to an entity.

Table 5.32. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

5.12.2. list GET

Lists all labels that are attached to an entity.

Table 5.33. Parameters summary

NameTypeDirectionSummary

label

AffinityLabel[]

Out

 

5.13. AssignedCpuProfile

Table 5.34. Methods summary

NameSummary

get

 

remove

 

5.13.1. get GET

Table 5.35. Parameters summary

NameTypeDirectionSummary

profile

CpuProfile

Out

 

5.13.2. remove DELETE

Table 5.36. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.14. AssignedCpuProfiles

Table 5.37. Methods summary

NameSummary

add

 

list

 

5.14.1. add POST

Table 5.38. Parameters summary

NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

5.14.2. list GET

Table 5.39. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

CpuProfile[]

Out

 

5.14.2.1. max

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

5.15. AssignedDiskProfile

Table 5.40. Methods summary

NameSummary

get

 

remove

 

5.15.1. get GET

Table 5.41. Parameters summary

NameTypeDirectionSummary

disk_profile

DiskProfile

Out

 

5.15.2. remove DELETE

Table 5.42. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.16. AssignedDiskProfiles

Table 5.43. Methods summary

NameSummary

add

 

list

 

5.16.1. add POST

Table 5.44. Parameters summary

NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

5.16.2. list GET

Table 5.45. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

DiskProfile[]

Out

 

5.16.2.1. max

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

5.17. AssignedNetwork

Table 5.46. Methods summary

NameSummary

get

 

remove

 

update

 

5.17.1. get GET

Table 5.47. Parameters summary

NameTypeDirectionSummary

network

Network

Out

 

5.17.2. remove DELETE

Table 5.48. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.17.3. update PUT

Table 5.49. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

network

Network

In/Out

 

5.18. AssignedNetworks

Table 5.50. Methods summary

NameSummary

add

 

list

 

5.18.1. add POST

Table 5.51. Parameters summary

NameTypeDirectionSummary

network

Network

In/Out

 

5.18.2. list GET

Table 5.52. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

 

5.18.2.1. max

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

5.19. AssignedPermissions

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

Table 5.53. Methods summary

NameSummary

add

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

list

List all the permissions of the specific entity.

5.19.1. add POST

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

For example, to assign the UserVmManager role to the virtual machine with id 123 to the user with id 456 send a request like this:

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

With a request body like this:

<permission>
  <role>
    <name>UserVmManager</name>
  </role>
  <user id="456"/>
</permission>

To assign the SuperUser role to the system to the user with id 456 send a request like this:

POST /ovirt-engine/api/permissions

With a request body like this:

<permission>
  <role>
    <name>SuperUser</name>
  </role>
  <user id="456"/>
</permission>

If you want to assign permission to the group instead of the user please replace the user element with the group element with proper id of the group. For example to assign the UserRole role to the cluster with id 123 to the group with id 789 send a request like this:

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

With a request body like this:

<permission>
  <role>
    <name>UserRole</name>
  </role>
  <group id="789"/>
</permission>

Table 5.54. Parameters summary

NameTypeDirectionSummary

permission

Permission

In/Out

The permission.

5.19.2. list GET

List all the permissions of the specific entity.

For example to list all the permissions of the cluster with id 123 send a request like this:

GET /ovirt-engine/api/clusters/123/permissions
<permissions>
  <permission id="456">
    <cluster id="123"/>
    <role id="789"/>
    <user id="451"/>
  </permission>
  <permission id="654">
    <cluster id="123"/>
    <role id="789"/>
    <group id="127"/>
  </permission>
</permissions>

Table 5.55. Parameters summary

NameTypeDirectionSummary

permissions

Permission[]

Out

The list of permissions.

5.20. AssignedRoles

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

Table 5.56. Methods summary

NameSummary

list

 

5.20.1. list GET

Table 5.57. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out

 

5.20.1.1. max

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

5.21. AssignedTag

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

Table 5.58. Methods summary

NameSummary

get

Gets the information about the assigned tag.

remove

Unassign tag from specific entity in the system.

5.21.1. get GET

Gets the information about the assigned tag.

For example to retrieve the information about the tag with the id 456 which is assigned to virtual machine with id 123 send a request like this:

GET /ovirt-engine/api/vms/123/tags/456
<tag href="/ovirt-engine/api/tags/456" id="456">
  <name>root</name>
  <description>root</description>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</tag>

Table 5.59. Parameters summary

NameTypeDirectionSummary

tag

Tag

Out

The assigned tag.

5.21.2. remove DELETE

Unassign tag from specific entity in the system.

For example to unassign the tag with id 456 from virtual machine with id 123 send a request like this:

DELETE /ovirt-engine/api/vms/123/tags/456

Table 5.60. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.22. AssignedTags

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

Table 5.61. Methods summary

NameSummary

add

Assign tag to specific entity in the system.

list

List all tags assigned to the specific entity.

5.22.1. add POST

Assign tag to specific entity in the system.

For example to assign tag mytag to virtual machine with the id 123 send a request like this:

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

With a request body like this:

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

Table 5.62. Parameters summary

NameTypeDirectionSummary

tag

Tag

In/Out

The assigned tag.

5.22.2. list GET

List all tags assigned to the specific entity.

For example to list all the tags of the virtual machine with id 123 send a request like this:

GET /ovirt-engine/api/vms/123/tags
<tags>
  <tag href="/ovirt-engine/api/tags/222" id="222">
    <name>mytag</name>
    <description>mytag</description>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </tag>
</tags>

Table 5.63. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

The list of assigned tags.

5.22.2.1. max

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

5.23. AssignedVnicProfile

Table 5.64. Methods summary

NameSummary

get

 

remove

 

5.23.1. get GET

Table 5.65. Parameters summary

NameTypeDirectionSummary

profile

VnicProfile

Out

 

5.23.2. remove DELETE

Table 5.66. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.24. AssignedVnicProfiles

Table 5.67. Methods summary

NameSummary

add

 

list

 

5.24.1. add POST

Table 5.68. Parameters summary

NameTypeDirectionSummary

profile

VnicProfile

In/Out

 

5.24.2. list GET

Table 5.69. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

Out

 

5.24.2.1. max

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

5.25. AttachedStorageDomain

Table 5.70. Methods summary

NameSummary

activate

This operation activates an attached storage domain.

deactivate

This operation deactivates an attached storage domain.

get

 

remove

 

5.25.1. activate POST

This operation activates an attached storage domain. Once the storage domain is activated it is ready for use with the data center.

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

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

<action/>

Table 5.71. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

5.25.2. deactivate POST

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

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

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

<action/>

Table 5.72. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

5.25.3. get GET

Table 5.73. Parameters summary

NameTypeDirectionSummary

storage_domain

StorageDomain

Out

 

5.25.4. remove DELETE

Table 5.74. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.26. AttachedStorageDomains

Table 5.75. Methods summary

NameSummary

add

 

list

 

5.26.1. add POST

Table 5.76. Parameters summary

NameTypeDirectionSummary

storage_domain

StorageDomain

In/Out

 

5.26.2. list GET

Table 5.77. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of storage domains to return.

storage_domains

StorageDomain[]

Out

 

5.26.2.1. max

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

5.27. Balance

Table 5.78. Methods summary

NameSummary

get

 

remove

 

5.27.1. get GET

Table 5.79. Parameters summary

NameTypeDirectionSummary

balance

Balance

Out

 

filter

Boolean

In

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

5.27.2. remove DELETE

Table 5.80. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.28. Balances

Table 5.81. Methods summary

NameSummary

add

 

list

 

5.28.1. add POST

Table 5.82. Parameters summary

NameTypeDirectionSummary

balance

Balance

In/Out

 

5.28.2. list GET

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

5.28.2.1. max

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

5.29. Bookmark

A service to manage a bookmark.

Table 5.84. Methods summary

NameSummary

get

Get a bookmark.

remove

Remove a bookmark.

update

Update a bookmark.

5.29.1. get GET

Get a bookmark.

An example for getting a bookmark:

GET /ovirt-engine/api/bookmarks/123
<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
  <name>example_vm</name>
  <value>vm: name=example*</value>
</bookmark>

Table 5.85. Parameters summary

NameTypeDirectionSummary

bookmark

Bookmark

Out

The requested bookmark.

5.29.2. remove DELETE

Remove a bookmark.

An example for removing a bookmark:

DELETE /ovirt-engine/api/bookmarks/123

Table 5.86. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.29.3. update PUT

Update a bookmark.

An example for updating a bookmark:

PUT /ovirt-engine/api/bookmarks/123

With the request body:

<bookmark>
  <name>new_example_vm</name>
  <value>vm: name=new_example*</value>
</bookmark>

Table 5.87. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bookmark

Bookmark

In/Out

The updated bookmark.

5.30. Bookmarks

A service to manage bookmarks.

Table 5.88. Methods summary

NameSummary

add

Adding a new bookmark.

list

Listing all the available bookmarks.

5.30.1. add POST

Adding a new bookmark.

Example of adding a bookmark:

POST /ovirt-engine/api/bookmarks
<bookmark>
  <name>new_example_vm</name>
  <value>vm: name=new_example*</value>
</bookmark>

Table 5.89. Parameters summary

NameTypeDirectionSummary

bookmark

Bookmark

In/Out

The added bookmark.

5.30.2. list GET

Listing all the available bookmarks.

Example of listing bookmarks:

GET /ovirt-engine/api/bookmarks
<bookmarks>
  <bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
    <name>database</name>
    <value>vm: name=database*</value>
  </bookmark>
  <bookmark href="/ovirt-engine/api/bookmarks/456" id="456">
    <name>example</name>
    <value>vm: name=example*</value>
  </bookmark>
</bookmarks>

Table 5.90. Parameters summary

NameTypeDirectionSummary

bookmarks

Bookmark[]

Out

The list of available bookmarks.

max

Integer

In

Sets the maximum number of bookmarks to return.

5.30.2.1. max

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

5.31. Cluster

A service to manage specific cluster.

Table 5.91. Methods summary

NameSummary

get

Get information about the cluster.

remove

Removes cluster from the system.

resetemulatedmachine

 

update

Updates information about the cluster.

5.31.1. get GET

Get information about the cluster.

An example of getting a cluster:

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

Table 5.92. Parameters summary

NameTypeDirectionSummary

cluster

Cluster

Out

 

filter

Boolean

In

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

5.31.2. remove DELETE

Removes cluster from the system.

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000

Table 5.93. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.31.3. resetemulatedmachine POST

Table 5.94. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

5.31.4. update PUT

Updates information about the cluster.

Only specified fields are updated, others remain unchanged.

E.g. update cluster’s CPU:

PUT /ovirt-engine/api/clusters/123

With request body like:

<cluster>
  <cpu>
    <type>Intel Haswell-noTSX Family</type>
  </cpu>
</cluster>

Table 5.95. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

cluster

Cluster

In/Out

 

5.32. ClusterLevel

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

Table 5.96. Methods summary

NameSummary

get

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

5.32.1. get GET

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

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

GET /ovirt-engine/api/clusterlevels/3.6

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

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

Table 5.97. Parameters summary

NameTypeDirectionSummary

level

ClusterLevel

Out

Retreived cluster level.

5.33. ClusterLevels

Provides information about the capabilities of different cluster levels supported by the engine. Version 4.0 of the engine supports levels 4.0 and 3.6. Each of these levels support different sets of CPU types, for example. This service provides that information.

Table 5.98. Methods summary

NameSummary

list

Lists the cluster levels supported by the system.

5.33.1. list GET

Lists the cluster levels supported by the system.

GET /ovirt-engine/api/clusterlevels

This will return a list of available cluster levels.

<cluster_levels>
  <cluster_level id="4.0">
     ...
  </cluster_level>
  ...
</cluster_levels>

Table 5.99. Parameters summary

NameTypeDirectionSummary

levels

ClusterLevel[]

Out

Retrieved cluster levels.

5.34. Clusters

A service to manage clusters.

Table 5.100. Methods summary

NameSummary

add

Creates a new cluster.

list

 

5.34.1. add POST

Creates a new cluster.

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

POST /ovirt-engine/api/clusters

With a request body like this:

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

Table 5.101. Parameters summary

NameTypeDirectionSummary

cluster

Cluster

In/Out

 

5.34.2. list GET

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

5.34.2.1. case_sensitive

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

5.34.2.2. max

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

5.35. Copyable

Table 5.103. Methods summary

NameSummary

copy

 

5.35.1. copy POST

Table 5.104. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

5.36. CpuProfile

Table 5.105. Methods summary

NameSummary

get

 

remove

 

update

 

5.36.1. get GET

Table 5.106. Parameters summary

NameTypeDirectionSummary

profile

CpuProfile

Out

 

5.36.2. remove DELETE

Table 5.107. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.36.3. update PUT

Table 5.108. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

CpuProfile

In/Out

 

5.37. CpuProfiles

Table 5.109. Methods summary

NameSummary

add

 

list

 

5.37.1. add POST

Table 5.110. Parameters summary

NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

5.37.2. list GET

Table 5.111. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profile

CpuProfile[]

Out

 

5.37.2.1. max

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

5.38. DataCenter

A service to manage a data center.

Table 5.112. Methods summary

NameSummary

get

Get a data center.

remove

Removes the data center.

update

Updates the data center.

5.38.1. get GET

Get a data center.

An example of getting a data center:

GET /ovirt-engine/api/datacenters/123
<data_center href="/ovirt-engine/api/datacenters/123" id="123">
  <name>Default</name>
  <description>The default Data Center</description>
  <link href="/ovirt-engine/api/datacenters/123/clusters" rel="clusters"/>
  <link href="/ovirt-engine/api/datacenters/123/storagedomains" rel="storagedomains"/>
  <link href="/ovirt-engine/api/datacenters/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/datacenters/123/networks" rel="networks"/>
  <link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/>
  <link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/>
  <link href="/ovirt-engine/api/datacenters/123/iscsibonds" rel="iscsibonds"/>
  <local>false</local>
  <quota_mode>disabled</quota_mode>
  <status>up</status>
  <storage_format>v3</storage_format>
  <supported_versions>
    <version>
      <major>4</major>
      <minor>0</minor>
   </version>
  </supported_versions>
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  <mac_pool href="/ovirt-engine/api/macpools/456" id="456"/>
</data_center>

Table 5.113. Parameters summary

NameTypeDirectionSummary

data_center

DataCenter

Out

 

filter

Boolean

In

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

5.38.2. remove DELETE

Removes the data center.

DELETE /ovirt-engine/api/datacenters/123

Without any special parameters, the storage domains attached to the data center are detached and then removed from the storage. If something fails when performing this operation, for example if there is no host available to remove the storage domains from the storage, the complete operation will fail.

If the force parameter is true then the operation will always succeed, even if something fails while removing one storage domain, for example. The failure is just ignored and the data center is removed from the database anyway.

Table 5.114. Parameters summary

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.

5.38.2.1. force

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

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

5.38.3. update PUT

Updates the data center.

The name, description, storage_type, version, storage_format and mac_pool elements are updatable post-creation. For example, to change the name and description of data center 123 send a request like this:

PUT /ovirt-engine/api/datacenters/123

With a request body like this:

<data_center>
  <name>myupdatedname</name>
  <description>An updated description for the data center</description>
</data_center>

Table 5.115. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

data_center

DataCenter

In/Out

The data center that is being updated.

5.39. DataCenters

A service to manage data centers.

Table 5.116. Methods summary

NameSummary

add

Creates a new data center.

list

Lists the data centers.

5.39.1. add POST

Creates a new data center.

Creation of a new data center requires the name and local elements. For example, to create a data center named mydc that uses shared storage (NFS, iSCSI or fibre channel) send a request like this:

POST /ovirt-engine/api/datacenters

With a request body like this:

<data_center>
  <name>mydc</name>
  <local>false</local>
</data_center>

Table 5.117. Parameters summary

NameTypeDirectionSummary

data_center

DataCenter

In/Out

The data center that is being added.

5.39.2. list GET

Lists the data centers.

The following request retrieves a representation of the data centers:

GET /ovirt-engine/api/datacenters

The above request performed with curl:

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

This is what an example response could look like:

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

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

The data center also contains a link to the storage domains collection. The data center uses this collection to attach storage domains from the storage domains main collection.

Table 5.118. Parameters summary

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.

5.39.2.1. case_sensitive

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

5.39.2.2. max

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

5.40. Disk

Manages a single disk.

Table 5.119. Methods summary

NameSummary

copy

This operation copies a disk to the specified storage domain.

export

 

get

 

move

Moves a disk to another storage domain.

remove

 

5.40.1. copy POST

This operation copies a disk to the specified storage domain.

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

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

With a request body like this:

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

Table 5.120. Parameters summary

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

 

5.40.2. export POST

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

 

5.40.3. get GET

Table 5.122. Parameters summary

NameTypeDirectionSummary

disk

Disk

Out

 

5.40.4. move POST

Moves a disk to another storage domain.

For example, to move the disk with identifier 123 to a storage domain with identifier 456 send the following request:

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

With the following request body:

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

Table 5.123. Parameters summary

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

 

5.40.5. remove DELETE

Table 5.124. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.41. DiskAttachment

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

Table 5.125. Methods summary

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.

5.41.1. get GET

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

An example of getting a disk attachment:

GET /ovirt-engine/api/vms/123/diskattachments/456
<disk_attachment href="/ovirt-engine/api/vms/123/diskattachments/456" id="456">
  <active>true</active>
  <bootable>true</bootable>
  <interface>virtio</interface>
  <disk href="/ovirt-engine/api/disks/456" id="456"/>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</disk_attachment>

Table 5.126. Parameters summary

NameTypeDirectionSummary

attachment

DiskAttachment

Out

 

5.41.2. remove DELETE

Removes the disk attachment.

This will only detach the disk from the virtual machine, but won’t remove it from the system, unless the detach_only parameter is false.

An example of removing a disk attachment:

DELETE /ovirt-engine/api/vms/123/diskattachments/456?detach_only=true

Table 5.127. Parameters summary

NameTypeDirectionSummary

detach_only

Boolean

In

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

5.41.2.1. detach_only

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

5.41.3. update PUT

Update the disk attachment and the disk properties within it.

PUT /vms/{vm:id}/disksattachments/{attachment:id}
<disk_attachment>
  <bootable>true</bootable>
  <interface>ide</interface>
  <active>true</active>
  <disk>
    <name>mydisk</name>
    <provisioned_size>1024</provisioned_size>
    ...
  </disk>
</disk_attachment>

Table 5.128. Parameters summary

NameTypeDirectionSummary

disk_attachment

DiskAttachment

In/Out

 

5.42. DiskAttachments

This service manages the set of disks attached to a virtual machine. Each attached disk is represented by a DiskAttachment, containing the bootable flag, the disk interface and the reference to the disk.

Table 5.129. Methods summary

NameSummary

add

Adds a new disk attachment to the virtual machine.

list

List the disk that are attached to the virtual machine.

5.42.1. add POST

Adds a new disk attachment to the virtual machine. The attachment parameter can contain just a reference, if the disk already exists:

<disk_attachment>
  <bootable>true</bootable>
  <interface>ide</interface>
  <active>true</active>
  <disk id="123"/>
</disk_attachment>

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

<disk_attachment>
  <bootable>true</bootable>
  <interface>ide</interface>
  <active>true</active>
  <disk>
    <name>mydisk</name>
    <provisioned_size>1024</provisioned_size>
    ...
  </disk>
</disk_attachment>

In this case the disk will be created and then attached to the virtual machine.

In both cases, use the following URL for a virtual machine with an id 345:

POST /ovirt-engine/api/vms/345/diskattachments
Important

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

Table 5.130. Parameters summary

NameTypeDirectionSummary

attachment

DiskAttachment

In/Out

 

5.42.2. list GET

List the disk that are attached to the virtual machine.

Table 5.131. Parameters summary

NameTypeDirectionSummary

attachments

DiskAttachment[]

Out

 

5.43. DiskProfile

Table 5.132. Methods summary

NameSummary

get

 

remove

 

update

 

5.43.1. get GET

Table 5.133. Parameters summary

NameTypeDirectionSummary

profile

DiskProfile

Out

 

5.43.2. remove DELETE

Table 5.134. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.43.3. update PUT

Table 5.135. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

DiskProfile

In/Out

 

5.44. DiskProfiles

Table 5.136. Methods summary

NameSummary

add

 

list

 

5.44.1. add POST

Table 5.137. Parameters summary

NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

5.44.2. list GET

Table 5.138. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profile

DiskProfile[]

Out

 

5.44.2.1. max

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

5.45. DiskSnapshot

Table 5.139. Methods summary

NameSummary

get

 

remove

 

5.45.1. get GET

Table 5.140. Parameters summary

NameTypeDirectionSummary

snapshot

DiskSnapshot

Out

 

5.45.2. remove DELETE

Table 5.141. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.46. DiskSnapshots

Table 5.142. Methods summary

NameSummary

list

 

5.46.1. list GET

Table 5.143. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

DiskSnapshot[]

Out

 

5.46.1.1. max

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

5.47. Disks

Manages the collection of disks available in the system.

Table 5.144. Methods summary

NameSummary

add

Adds a new floating disk.

list

Get list of disks.

5.47.1. add POST

Adds a new floating disk.

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

To create a new floating disk with specified provisioned_size, format and name on a storage domain with an id e9fedf39-5edc-4e0a-8628-253f1b9c5693, send a request as follows:

POST /ovirt-engine/api/disks

With a request body as follows:

<disk>
  <storage_domains>
    <storage_domain id="e9fedf39-5edc-4e0a-8628-253f1b9c5693"/>
  </storage_domains>
  <name>disk1</name>
  <provisioned_size>1048576</provisioned_size>
  <format>cow</format>
</disk>

Table 5.145. Parameters summary

NameTypeDirectionSummary

disk

Disk

In/Out

The disk.

5.47.2. list GET

Get list of disks.

GET /ovirt-engine/api/disks

You will get a XML response which will look like this one:

<disks>
  <disk id="123">
    <actions>...</actions>
    <name>MyDisk</name>
    <description>MyDisk description</description>
    <link href="/ovirt-engine/api/disks/123/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/disks/123/statistics" rel="statistics"/>
    <actual_size>5345845248</actual_size>
    <alias>MyDisk alias</alias>
    ...
    <status>ok</status>
    <storage_type>image</storage_type>
    <wipe_after_delete>false</wipe_after_delete>
    <disk_profile id="123"/>
    <quota id="123"/>
    <storage_domains>...</storage_domains>
  </disk>
  ...
</disks>

Table 5.146. Parameters summary

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.

5.47.2.1. case_sensitive

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

5.47.2.2. max

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

5.48. Domain

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

Table 5.147. Methods summary

NameSummary

get

Gets the authentication domain information.

5.48.1. get GET

Gets the authentication domain information.

Usage:

GET /ovirt-engine/api/domains/5678

Will return the domain information:

<domain href="/ovirt-engine/api/domains/5678" id="5678">
  <name>internal-authz</name>
  <link href="/ovirt-engine/api/domains/5678/users" rel="users"/>
  <link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/>
  <link href="/ovirt-engine/api/domains/5678/users?search={query}" rel="users/search"/>
  <link href="/ovirt-engine/api/domains/5678/groups?search={query}" rel="groups/search"/>
</domain>

Table 5.148. Parameters summary

NameTypeDirectionSummary

domain

Domain

Out

The authentication domain.

5.49. DomainGroup

Table 5.149. Methods summary

NameSummary

get

 

5.49.1. get GET

Table 5.150. Parameters summary

NameTypeDirectionSummary

get

Group

Out

 

5.50. DomainGroups

Table 5.151. Methods summary

NameSummary

list

 

5.50.1. list GET

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

5.50.1.1. case_sensitive

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

5.50.1.2. max

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

5.51. DomainUser

A service to view a domain user in the system.

Table 5.153. Methods summary

NameSummary

get

Gets the domain user information.

5.51.1. get GET

Gets the domain user information.

Usage:

GET /ovirt-engine/api/domains/5678/users/1234

Will return the domain user information:

<user href="/ovirt-engine/api/users/1234" id="1234">
  <name>admin</name>
  <namespace>*</namespace>
  <principal>admin</principal>
  <user_name>admin@internal-authz</user_name>
  <domain href="/ovirt-engine/api/domains/5678" id="5678">
    <name>internal-authz</name>
  </domain>
  <groups/>
</user>

Table 5.154. Parameters summary

NameTypeDirectionSummary

user

User

Out

The domain user.

5.52. DomainUsers

A service to list all domain users in the system.

Table 5.155. Methods summary

NameSummary

list

List all the users in the domain.

5.52.1. list GET

List all the users in the domain.

Usage:

GET /ovirt-engine/api/domains/5678/users

Will return the list of users in the domain:

<users>
  <user href="/ovirt-engine/api/domains/5678/users/1234" id="1234">
    <name>admin</name>
    <namespace>*</namespace>
    <principal>admin</principal>
    <user_name>admin@internal-authz</user_name>
    <domain href="/ovirt-engine/api/domains/5678" id="5678">
      <name>internal-authz</name>
    </domain>
    <groups/>
  </user>
</users>

Table 5.156. Parameters summary

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.

5.52.1.1. case_sensitive

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

5.52.1.2. max

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

5.53. Domains

A service to list all authentication domains in the system.

Table 5.157. Methods summary

NameSummary

list

List all the authentication domains in the system.

5.53.1. list GET

List all the authentication domains in the system.

Usage:

GET /ovirt-engine/api/domains

Will return the list of domains:

<domains>
  <domain href="/ovirt-engine/api/domains/5678" id="5678">
    <name>internal-authz</name>
    <link href="/ovirt-engine/api/domains/5678/users" rel="users"/>
    <link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/>
    <link href="/ovirt-engine/api/domains/5678/users?search={query}" rel="users/search"/>
    <link href="/ovirt-engine/api/domains/5678/groups?search={query}" rel="groups/search"/>
  </domain>
</domains>

Table 5.158. Parameters summary

NameTypeDirectionSummary

domains

Domain[]

Out

The list of domains.

max

Integer

In

Sets the maximum number of domains to return.

5.53.1.1. max

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

5.54. EngineKatelloErrata

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

Table 5.159. Methods summary

NameSummary

list

Retrieves the representation of the Katello errata.

5.54.1. list GET

Retrieves the representation of the Katello errata.

GET /ovirt-engine/api/katelloerrata

You will receive response in XML like this one:

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

Table 5.160. Parameters summary

NameTypeDirectionSummary

errata

KatelloErratum[]

Out

A representation of Katello errata.

max

Integer

In

Sets the maximum number of errata to return.

5.54.1.1. max

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

5.55. Event

A service to manage an event in the system.

Table 5.161. Methods summary

NameSummary

get

Get an event.

remove

Removes an event from internal audit log.

5.55.1. get GET

Get an event.

An example of getting an event:

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

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

Table 5.162. Parameters summary

NameTypeDirectionSummary

event

Event

Out

 

5.55.2. remove DELETE

Removes an event from internal audit log.

An event can be removed by sending following request

DELETE /ovirt-engine/api/events/123

Table 5.163. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.56. Events

A service to manage events in the system.

Table 5.164. Methods summary

NameSummary

add

Adds an external event to the internal audit log.

list

Get list of events.

undelete

 

5.56.1. add POST

Adds an external event to the internal audit log.

This is intended for integration with external systems that detect or produce events relevant for the administrator of the system. For example, an external monitoring tool may be able to detect that a file system is full inside the guest operating system of a virtual machine. This event can be added to the internal audit log sending a request like this:

POST /ovirt-engine/api/events
<event>
  <description>File system /home is full</description>
  <severity>alert</severity>
  <origin>mymonitor</origin>
  <custom_id>1467879754</custom_id>
</event>

Events can also be linked to specific objects. For example, the above event could be linked to the specific virtual machine where it happened, using the vm link:

POST /ovirt-engine/api/events
<event>
  <description>File system /home is full</description>
  <severity>alert</severity>
  <origin>mymonitor</origin>
  <custom_id>1467879754</custom_id>
  <vm id="aae98225-5b73-490d-a252-899209af17e9"/>
</event>
Note

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

Table 5.165. Parameters summary

NameTypeDirectionSummary

event

Event

In/Out

 

5.56.2. list GET

Get list of events.

GET /ovirt-engine/api/events

To the above request we get following response:

<events>
  <event href="/ovirt-engine/api/events/2" id="2">
    <description>User admin@internal-authz logged out.</description>
    <code>31</code>
    <correlation_id>1e892ea9</correlation_id>
    <custom_id>-1</custom_id>
    <flood_rate>30</flood_rate>
    <origin>oVirt</origin>
    <severity>normal</severity>
    <time>2016-09-14T12:14:34.541+02:00</time>
    <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
  </event>
  <event href="/ovirt-engine/api/events/1" id="1">
    <description>User admin logged in.</description>
    <code>30</code>
    <correlation_id>1fbd81f4</correlation_id>
    <custom_id>-1</custom_id>
    <flood_rate>30</flood_rate>
    <origin>oVirt</origin>
    <severity>normal</severity>
    <time>2016-09-14T11:54:35.229+02:00</time>
    <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/>
  </event>
</events>

The following events occur:

  • id="1" - The API logs in the admin user account.
  • id="2" - The API logs out of the admin user account.

Table 5.166. Parameters summary

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.

5.56.2.1. case_sensitive

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

5.56.2.2. from

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

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

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

5.56.2.3. max

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

5.56.3. undelete POST

Table 5.167. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the un-delete should be performed asynchronously.

5.57. ExternalComputeResource

Table 5.168. Methods summary

NameSummary

get

 

5.57.1. get GET

Table 5.169. Parameters summary

NameTypeDirectionSummary

resource

ExternalComputeResource

Out

 

5.58. ExternalComputeResources

Table 5.170. Methods summary

NameSummary

list

 

5.58.1. list GET

Table 5.171. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of resources to return.

resources

ExternalComputeResource[]

Out

 

5.58.1.1. max

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

5.59. ExternalDiscoveredHost

Table 5.172. Methods summary

NameSummary

get

 

5.59.1. get GET

Table 5.173. Parameters summary

NameTypeDirectionSummary

host

ExternalDiscoveredHost

Out

 

5.60. ExternalDiscoveredHosts

Table 5.174. Methods summary

NameSummary

list

 

5.60.1. list GET

Table 5.175. Parameters summary

NameTypeDirectionSummary

hosts

ExternalDiscoveredHost[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

5.60.1.1. max

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

5.61. ExternalHost

Table 5.176. Methods summary

NameSummary

get

 

5.61.1. get GET

Table 5.177. Parameters summary

NameTypeDirectionSummary

host

ExternalHost

Out

 

5.62. ExternalHostGroup

Table 5.178. Methods summary

NameSummary

get

 

5.62.1. get GET

Table 5.179. Parameters summary

NameTypeDirectionSummary

group

ExternalHostGroup

Out

 

5.63. ExternalHostGroups

Table 5.180. Methods summary

NameSummary

list

 

5.63.1. list GET

Table 5.181. Parameters summary

NameTypeDirectionSummary

groups

ExternalHostGroup[]

Out

 

max

Integer

In

Sets the maximum number of groups to return.

5.63.1.1. max

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

5.64. ExternalHostProvider

Table 5.182. Methods summary

NameSummary

get

 

importcertificates

 

remove

 

testconnectivity

 

update

 

5.64.1. get GET

Table 5.183. Parameters summary

NameTypeDirectionSummary

provider

ExternalHostProvider

Out

 

5.64.2. importcertificates POST

Table 5.184. Parameters summary

NameTypeDirectionSummary

certificates

Certificate[]

In

 

5.64.3. remove DELETE

Table 5.185. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.64.4. testconnectivity POST

Table 5.186. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

5.64.5. update PUT

Table 5.187. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

ExternalHostProvider

In/Out

 

5.65. ExternalHostProviders

Table 5.188. Methods summary

NameSummary

add

 

list

 

5.65.1. add POST

Table 5.189. Parameters summary

NameTypeDirectionSummary

provider

ExternalHostProvider

In/Out

 

5.65.2. list GET

Table 5.190. Parameters summary

NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

ExternalHostProvider[]

Out

 

5.65.2.1. max

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

5.66. ExternalHosts

Table 5.191. Methods summary

NameSummary

list

 

5.66.1. list GET

Table 5.192. Parameters summary

NameTypeDirectionSummary

hosts

ExternalHost[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

5.66.1.1. max

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

5.67. ExternalProvider

Table 5.193. Methods summary

NameSummary

importcertificates

 

testconnectivity

 

5.67.1. importcertificates POST

Table 5.194. Parameters summary

NameTypeDirectionSummary

certificates

Certificate[]

In

 

5.67.2. testconnectivity POST

Table 5.195. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

5.68. ExternalProviderCertificate

Table 5.196. Methods summary

NameSummary

get

 

5.68.1. get GET

Table 5.197. Parameters summary

NameTypeDirectionSummary

certificate

Certificate

Out

 

5.69. ExternalProviderCertificates

Table 5.198. Methods summary

NameSummary

list

 

5.69.1. list GET

Table 5.199. Parameters summary

NameTypeDirectionSummary

certificates

Certificate[]

Out

 

max

Integer

In

Sets the maximum number of certificates to return.

5.69.1.1. max

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

5.70. ExternalVmImports

Provides capability to import external virtual machines.

Table 5.200. Methods summary

NameSummary

add

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

5.70.1. add POST

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

For example import of a virtual machine from VMware can be facilitated using the following request:

POST /externalvmimports

With request body of type ExternalVmImport, for example:

<external_vm_import>
  <vm>
    <name>my_vm</name>
  </vm>
  <cluster id="360014051136c20574f743bdbd28177fd" />
  <storage_domain id="8bb5ade5-e988-4000-8b93-dbfc6717fe50" />
  <name>vm_name_as_is_in_vmware</name>
  <sparse>true</sparse>
  <username>vmware_user</username>
  <password>123456</password>
  <provider>VMWARE</provider>
  <url>vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1</url>
  <drivers_iso id="virtio-win-1.6.7.iso" />
</external_vm_import>

Table 5.201. Parameters summary

NameTypeDirectionSummary

import

ExternalVmImport

In/Out

 

5.71. FenceAgent

Table 5.202. Methods summary

NameSummary

get

 

remove

 

update

 

5.71.1. get GET

Table 5.203. Parameters summary

NameTypeDirectionSummary

agent

Agent

Out

 

5.71.2. remove DELETE

Table 5.204. Parameters summary

NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

5.71.3. update PUT

Table 5.205. Parameters summary

NameTypeDirectionSummary

agent

Agent

In/Out

 

async

Boolean

In

Indicates if the update should be performed asynchronously.

5.72. FenceAgents

Table 5.206. Methods summary

NameSummary

add

 

list

 

5.72.1. add POST

Table 5.207. Parameters summary

NameTypeDirectionSummary

agent

Agent

In/Out

 

5.72.2. list GET

Table 5.208. Parameters summary

NameTypeDirectionSummary

agents

Agent[]

Out

 

max

Integer

In

Sets the maximum number of agents to return.

5.72.2.1. max

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

5.73. File

Table 5.209. Methods summary

NameSummary

get

 

5.73.1. get GET

Table 5.210. Parameters summary

NameTypeDirectionSummary