Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Services

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

6.1. AffinityGroup
Copy link

This service manages a single affinity group.

Expand
Table 6.1. Methods summary
NameSummary

get

Retrieve the affinity group details.

remove

Remove the affinity group.

update

Update the affinity group.

6.1.1. get GET
Copy link

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.2. Parameters summary
NameTypeDirectionSummary

group

AffinityGroup

Out

The affinity group.

6.1.2. remove DELETE
Copy link

Remove the affinity group. 

DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456
Copy to Clipboard Toggle word wrap
Expand
Table 6.3. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.1.3. update PUT
Copy link

Update the affinity group.

Expand
Table 6.4. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

group

AffinityGroup

In/Out

The affinity group.

6.2. AffinityGroupVm
Copy link

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

Expand
Table 6.5. Methods summary
NameSummary

remove

Remove this virtual machine from the affinity group.

6.2.1. remove DELETE
Copy link

Remove this virtual machine from the affinity group.

Expand
Table 6.6. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the removal should be performed asynchronously.

6.3. AffinityGroupVms
Copy link

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

Expand
Table 6.7. Methods summary
NameSummary

add

Add a virtual machine to the affinity group.

list

List all virtual machines assigned to this affinity group.

6.3.1. add POST
Copy link

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
Copy to Clipboard Toggle word wrap

With the following body: 

<vm id="000-000"/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.8. Parameters summary
NameTypeDirectionSummary

vm

Vm

In/Out

 

6.3.2. list GET
Copy link

List all virtual machines assigned to this affinity group.

Expand
Table 6.9. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of virtual machines to return.

vms

Vm[]

Out

 

6.3.2.1. max
Copy link

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

6.4. AffinityGroups
Copy link

The affinity groups service manages virtual machine relationships and dependencies.

Expand
Table 6.10. Methods summary
NameSummary

add

Create a new affinity group.

list

List existing affinity groups.

6.4.1. add POST
Copy link

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
Copy to Clipboard Toggle word wrap

And use the following example in its body: 

<affinity_group>
  <name>AF_GROUP_001</name>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
Copy to Clipboard Toggle word wrap
Expand
Table 6.11. Parameters summary
NameTypeDirectionSummary

group

AffinityGroup

In/Out

The affinity group object to create.

6.4.2. list GET
Copy link

List existing affinity groups.

Expand
Table 6.12. Parameters summary
NameTypeDirectionSummary

groups

AffinityGroup[]

Out

The list of existing affinity groups.

max

Integer

In

Sets the maximum number of affinity groups to return.

6.4.2.1. max
Copy link

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

6.5. AffinityLabel
Copy link

The details of a single affinity label.

Expand
Table 6.13. Methods summary
NameSummary

get

Retrieves the details of a label.

remove

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

update

Updates a label.

6.5.1. get GET
Copy link

Retrieves the details of a label.

Expand
Table 6.14. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

Out

 

6.5.2. remove DELETE
Copy link

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

6.5.3. update PUT
Copy link

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

Expand
Table 6.15. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.6. AffinityLabelHost
Copy link

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

Expand
Table 6.16. Methods summary
NameSummary

get

Retrieves details about a host that has this label assigned.

remove

Remove a label from a host.

6.6.1. get GET
Copy link

Retrieves details about a host that has this label assigned.

Expand
Table 6.17. Parameters summary
NameTypeDirectionSummary

host

Host

Out

 

6.6.2. remove DELETE
Copy link

Remove a label from a host.

6.7. AffinityLabelHosts
Copy link

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

Expand
Table 6.18. Methods summary
NameSummary

add

Add a label to a host.

list

List all hosts with the label.

6.7.1. add POST
Copy link

Add a label to a host.

Expand
Table 6.19. Parameters summary
NameTypeDirectionSummary

host

Host

In/Out

 

6.7.2. list GET
Copy link

List all hosts with the label.

Expand
Table 6.20. Parameters summary
NameTypeDirectionSummary

hosts

Host[]

Out

 

6.8. AffinityLabelVm
Copy link

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

Expand
Table 6.21. Methods summary
NameSummary

get

Retrieves details about a vm that has this label assigned.

remove

Remove a label from a vm.

6.8.1. get GET
Copy link

Retrieves details about a vm that has this label assigned.

Expand
Table 6.22. Parameters summary
NameTypeDirectionSummary

vm

Vm

Out

 

6.8.2. remove DELETE
Copy link

Remove a label from a vm.

6.9. AffinityLabelVms
Copy link

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

Expand
Table 6.23. Methods summary
NameSummary

add

Add a label to a vm.

list

List all vms with the label.

6.9.1. add POST
Copy link

Add a label to a vm.

Expand
Table 6.24. Parameters summary
NameTypeDirectionSummary

vm

Vm

In/Out

 

6.9.2. list GET
Copy link

List all vms with the label.

Expand
Table 6.25. Parameters summary
NameTypeDirectionSummary

vms

Vm[]

Out

 

6.10. AffinityLabels
Copy link

Manages the affinity labels available in the system.

Expand
Table 6.26. Methods summary
NameSummary

add

Creates a new label.

list

Lists all labels present in the system.

6.10.1. add POST
Copy link

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

Expand
Table 6.27. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.10.2. list GET
Copy link

Lists all labels present in the system.

Expand
Table 6.28. Parameters summary
NameTypeDirectionSummary

labels

AffinityLabel[]

Out

 

max

Integer

In

Sets the maximum number of labels to return.

6.10.2.1. max
Copy link

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

6.11. AssignedAffinityLabel
Copy link

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

Expand
Table 6.29. Methods summary
NameSummary

get

Retrieves details about the attached label.

remove

Removes the label from an entity.

6.11.1. get GET
Copy link

Retrieves details about the attached label.

Expand
Table 6.30. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

Out

 

6.11.2. remove DELETE
Copy link

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

6.12. AssignedAffinityLabels
Copy link

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

Expand
Table 6.31. Methods summary
NameSummary

add

Attaches a label to an entity.

list

Lists all labels that are attached to an entity.

6.12.1. add POST
Copy link

Attaches a label to an entity.

Expand
Table 6.32. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel

In/Out

 

6.12.2. list GET
Copy link

Lists all labels that are attached to an entity.

Expand
Table 6.33. Parameters summary
NameTypeDirectionSummary

label

AffinityLabel[]

Out

 

6.13. AssignedCpuProfile
Copy link

Expand
Table 6.34. Methods summary
NameSummary

get

 

remove

 

6.13.1. get GET
Copy link

Expand
Table 6.35. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

Out

 

6.13.2. remove DELETE
Copy link

Expand
Table 6.36. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.14. AssignedCpuProfiles
Copy link

Expand
Table 6.37. Methods summary
NameSummary

add

 

list

 

6.14.1. add POST
Copy link

Expand
Table 6.38. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

6.14.2. list GET
Copy link

Expand
Table 6.39. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

CpuProfile[]

Out

 

6.14.2.1. max
Copy link

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

6.15. AssignedDiskProfile
Copy link

Expand
Table 6.40. Methods summary
NameSummary

get

 

remove

 

6.15.1. get GET
Copy link

Expand
Table 6.41. Parameters summary
NameTypeDirectionSummary

disk_profile

DiskProfile

Out

 

6.15.2. remove DELETE
Copy link

Expand
Table 6.42. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.16. AssignedDiskProfiles
Copy link

Expand
Table 6.43. Methods summary
NameSummary

add

 

list

 

6.16.1. add POST
Copy link

Expand
Table 6.44. Parameters summary
NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

6.16.2. list GET
Copy link

Expand
Table 6.45. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

DiskProfile[]

Out

 

6.16.2.1. max
Copy link

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

6.17. AssignedPermissions
Copy link

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

Expand
Table 6.46. Methods summary
NameSummary

add

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

list

List all the permissions of the specific entity.

6.17.1. add POST
Copy link

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<permission>
  <role>
    <name>UserVmManager</name>
  </role>
  <user id="456"/>
</permission>
Copy to Clipboard Toggle word wrap

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

POST /ovirt-engine/api/permissions
Copy to Clipboard Toggle word wrap

With a request body like this: 

<permission>
  <role>
    <name>SuperUser</name>
  </role>
  <user id="456"/>
</permission>
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<permission>
  <role>
    <name>UserRole</name>
  </role>
  <group id="789"/>
</permission>
Copy to Clipboard Toggle word wrap
Expand
Table 6.47. Parameters summary
NameTypeDirectionSummary

permission

Permission

In/Out

The permission.

6.17.2. list GET
Copy link

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
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.48. Parameters summary
NameTypeDirectionSummary

permissions

Permission[]

Out

The list of permissions.

6.18. AssignedRoles
Copy link

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

Expand
Table 6.49. Methods summary
NameSummary

list

 

6.18.1. list GET
Copy link

Expand
Table 6.50. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out

 

6.18.1.1. max
Copy link

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

6.19. AssignedTag
Copy link

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

Expand
Table 6.51. Methods summary
NameSummary

get

Gets the information about the assigned tag.

remove

Unassign tag from specific entity in the system.

6.19.1. get GET
Copy link

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
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.52. Parameters summary
NameTypeDirectionSummary

tag

Tag

Out

The assigned tag.

6.19.2. remove DELETE
Copy link

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
Copy to Clipboard Toggle word wrap
Expand
Table 6.53. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.20. AssignedTags
Copy link

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

Expand
Table 6.54. Methods summary
NameSummary

add

Assign tag to specific entity in the system.

list

List all tags assigned to the specific entity.

6.20.1. add POST
Copy link

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<tag>
  <name>mytag</name>
</tag>
Copy to Clipboard Toggle word wrap
Expand
Table 6.55. Parameters summary
NameTypeDirectionSummary

tag

Tag

In/Out

The assigned tag.

6.20.2. list GET
Copy link

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
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.56. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

The list of assigned tags.

6.20.2.1. max
Copy link

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

6.21. AssignedVnicProfile
Copy link

Expand
Table 6.57. Methods summary
NameSummary

get

 

remove

 

6.21.1. get GET
Copy link

Expand
Table 6.58. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

Out

 

6.21.2. remove DELETE
Copy link

Expand
Table 6.59. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.22. AssignedVnicProfiles
Copy link

Expand
Table 6.60. Methods summary
NameSummary

add

 

list

 

6.22.1. add POST
Copy link

Expand
Table 6.61. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

In/Out

 

6.22.2. list GET
Copy link

Expand
Table 6.62. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

Out

 

6.22.2.1. max
Copy link

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

6.23. AttachedStorageDomain
Copy link

Expand
Table 6.63. Methods summary
NameSummary

activate

This operation activates an attached storage domain.

deactivate

This operation deactivates an attached storage domain.

get

 

remove

 

6.23.1. activate POST
Copy link

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
Copy to Clipboard Toggle word wrap

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

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.64. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.23.2. deactivate POST
Copy link

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
Copy to Clipboard Toggle word wrap

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

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.65. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

6.23.3. get GET
Copy link

Expand
Table 6.66. Parameters summary
NameTypeDirectionSummary

storage_domain

StorageDomain

Out

 

6.23.4. remove DELETE
Copy link

Expand
Table 6.67. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.24. AttachedStorageDomains
Copy link

Expand
Table 6.68. Methods summary
NameSummary

add

 

list

 

6.24.1. add POST
Copy link

Expand
Table 6.69. Parameters summary
NameTypeDirectionSummary

storage_domain

StorageDomain

In/Out

 

6.24.2. list GET
Copy link

Expand
Table 6.70. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of storage domains to return.

storage_domains

StorageDomain[]

Out

 

6.24.2.1. max
Copy link

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

6.25. Balance
Copy link

Expand
Table 6.71. Methods summary
NameSummary

get

 

remove

 

6.25.1. get GET
Copy link

Expand
Table 6.72. Parameters summary
NameTypeDirectionSummary

balance

Balance

Out

 

filter

Boolean

In

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

6.25.2. remove DELETE
Copy link

Expand
Table 6.73. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.26. Balances
Copy link

Expand
Table 6.74. Methods summary
NameSummary

add

 

list

 

6.26.1. add POST
Copy link

Expand
Table 6.75. Parameters summary
NameTypeDirectionSummary

balance

Balance

In/Out

 

6.26.2. list GET
Copy link

Expand
Table 6.76. Parameters summary
NameTypeDirectionSummary

balances

Balance[]

Out

 

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of balances to return.

6.26.2.1. max
Copy link

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

6.27. Bookmark
Copy link

A service to manage a bookmark.

Expand
Table 6.77. Methods summary
NameSummary

get

Get a bookmark.

remove

Remove a bookmark.

update

Update a bookmark.

6.27.1. get GET
Copy link

Get a bookmark.

An example for getting a bookmark: 

GET /ovirt-engine/api/bookmarks/123
Copy to Clipboard Toggle word wrap 
<bookmark href="/ovirt-engine/api/bookmarks/123" id="123">
  <name>example_vm</name>
  <value>vm: name=example*</value>
</bookmark>
Copy to Clipboard Toggle word wrap
Expand
Table 6.78. Parameters summary
NameTypeDirectionSummary

bookmark

Bookmark

Out

The requested bookmark.

6.27.2. remove DELETE
Copy link

Remove a bookmark.

An example for removing a bookmark: 

DELETE /ovirt-engine/api/bookmarks/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.79. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.27.3. update PUT
Copy link

Update a bookmark.

An example for updating a bookmark: 

PUT /ovirt-engine/api/bookmarks/123
Copy to Clipboard Toggle word wrap

With the request body: 

<bookmark>
  <name>new_example_vm</name>
  <value>vm: name=new_example*</value>
</bookmark>
Copy to Clipboard Toggle word wrap
Expand
Table 6.80. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bookmark

Bookmark

In/Out

The updated bookmark.

6.28. Bookmarks
Copy link

A service to manage bookmarks.

Expand
Table 6.81. Methods summary
NameSummary

add

Adding a new bookmark.

list

Listing all the available bookmarks.

6.28.1. add POST
Copy link

Adding a new bookmark.

Example of adding a bookmark: 

POST /ovirt-engine/api/bookmarks
Copy to Clipboard Toggle word wrap 
<bookmark>
  <name>new_example_vm</name>
  <value>vm: name=new_example*</value>
</bookmark>
Copy to Clipboard Toggle word wrap
Expand
Table 6.82. Parameters summary
NameTypeDirectionSummary

bookmark

Bookmark

In/Out

The added bookmark.

6.28.2. list GET
Copy link

Listing all the available bookmarks.

Example of listing bookmarks: 

GET /ovirt-engine/api/bookmarks
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.83. Parameters summary
NameTypeDirectionSummary

bookmarks

Bookmark[]

Out

The list of available bookmarks.

max

Integer

In

Sets the maximum number of bookmarks to return.

6.28.2.1. max
Copy link

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

6.29. Cluster
Copy link

A service to manage specific cluster.

Expand
Table 6.84. Methods summary
NameSummary

get

Get information about the cluster.

remove

Removes cluster from the system.

resetemulatedmachine

 

update

Updates information about the cluster.

6.29.1. get GET
Copy link

Get information about the cluster.

An example of getting a cluster: 

GET /ovirt-engine/api/clusters/123
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.85. Parameters summary
NameTypeDirectionSummary

cluster

Cluster

Out

 

filter

Boolean

In

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

6.29.2. remove DELETE
Copy link

Removes cluster from the system. 

DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
Copy to Clipboard Toggle word wrap
Expand
Table 6.86. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.29.3. resetemulatedmachine POST
Copy link

Expand
Table 6.87. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

6.29.4. update PUT
Copy link

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
Copy to Clipboard Toggle word wrap

With request body like: 

<cluster>
  <cpu>
    <type>Intel Haswell-noTSX Family</type>
  </cpu>
</cluster>
Copy to Clipboard Toggle word wrap
Expand
Table 6.88. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

cluster

Cluster

In/Out

 

6.30. ClusterLevel
Copy link

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

Expand
Table 6.89. Methods summary
NameSummary

get

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

6.30.1. get GET
Copy link

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
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.90. Parameters summary
NameTypeDirectionSummary

level

ClusterLevel

Out

Retreived cluster level.

6.31. ClusterLevels
Copy link

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

Expand
Table 6.91. Methods summary
NameSummary

list

Lists the cluster levels supported by the system.

6.31.1. list GET
Copy link

Lists the cluster levels supported by the system. 

GET /ovirt-engine/api/clusterlevels
Copy to Clipboard Toggle word wrap

This will return a list of available cluster levels. 

<cluster_levels>
  <cluster_level id="4.0">
     ...
  </cluster_level>
  ...
</cluster_levels>
Copy to Clipboard Toggle word wrap
Expand
Table 6.92. Parameters summary
NameTypeDirectionSummary

levels

ClusterLevel[]

Out

Retrieved cluster levels.

6.32. ClusterNetwork
Copy link

A service to manage a specific cluster network.

Expand
Table 6.93. Methods summary
NameSummary

get

Retrieves the cluster network details.

remove

Unassigns the network from a cluster.

update

Updates the network in the cluster.

6.32.1. get GET
Copy link

Retrieves the cluster network details.

Expand
Table 6.94. Parameters summary
NameTypeDirectionSummary

network

Network

Out

The cluster network.

6.32.2. remove DELETE
Copy link

Unassigns the network from a cluster.

6.32.3. update PUT
Copy link

Updates the network in the cluster.

Expand
Table 6.95. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The cluster network.

6.33. ClusterNetworks
Copy link

A service to manage cluster networks.

Expand
Table 6.96. Methods summary
NameSummary

add

Assigns the network to a cluster.

list

Lists the networks that are assigned to the cluster.

6.33.1. add POST
Copy link

Assigns the network to a cluster.

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

POST /ovirt-engine/api/clusters/123/networks
Copy to Clipboard Toggle word wrap

Use the following example in its body: 

<network id="123" />
Copy to Clipboard Toggle word wrap
Expand
Table 6.97. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The network object to be assigned to the cluster.

6.33.2. list GET
Copy link

Lists the networks that are assigned to the cluster.

Expand
Table 6.98. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

The list of networks that are assigned to the cluster.

6.33.2.1. max
Copy link

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

6.34. Clusters
Copy link

A service to manage clusters.

Expand
Table 6.99. Methods summary
NameSummary

add

Creates a new cluster.

list

 

6.34.1. add POST
Copy link

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<cluster>
  <name>mycluster</name>
  <cpu>
    <type>Intel Penryn Family</type>
  </cpu>
  <data_center id="123"/>
</cluster>
Copy to Clipboard Toggle word wrap
Expand
Table 6.100. Parameters summary
NameTypeDirectionSummary

cluster

Cluster

In/Out

 

6.34.2. list GET
Copy link

Expand
Table 6.101. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

clusters

Cluster[]

Out

 

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of clusters to return.

search

String

In

A query string used to restrict the returned clusters.

6.34.2.1. case_sensitive
Copy link

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

6.34.2.2. max
Copy link

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

6.35. Copyable
Copy link

Expand
Table 6.102. Methods summary
NameSummary

copy

 

6.35.1. copy POST
Copy link

Expand
Table 6.103. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

6.36. CpuProfile
Copy link

Expand
Table 6.104. Methods summary
NameSummary

get

 

remove

 

update

 

6.36.1. get GET
Copy link

Expand
Table 6.105. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

Out

 

6.36.2. remove DELETE
Copy link

Expand
Table 6.106. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.36.3. update PUT
Copy link

Expand
Table 6.107. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

CpuProfile

In/Out

 

6.37. CpuProfiles
Copy link

Expand
Table 6.108. Methods summary
NameSummary

add

 

list

 

6.37.1. add POST
Copy link

Expand
Table 6.109. Parameters summary
NameTypeDirectionSummary

profile

CpuProfile

In/Out

 

6.37.2. list GET
Copy link

Expand
Table 6.110. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profile

CpuProfile[]

Out

 

6.37.2.1. max
Copy link

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

6.38. DataCenter
Copy link

A service to manage a data center.

Expand
Table 6.111. Methods summary
NameSummary

get

Get a data center.

remove

Removes the data center.

update

Updates the data center.

6.38.1. get GET
Copy link

Get a data center.

An example of getting a data center: 

GET /ovirt-engine/api/datacenters/123
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.112. Parameters summary
NameTypeDirectionSummary

data_center

DataCenter

Out

 

filter

Boolean

In

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

6.38.2. remove DELETE
Copy link

Removes the data center. 

DELETE /ovirt-engine/api/datacenters/123
Copy to Clipboard Toggle word wrap

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

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

Expand
Table 6.113. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

force

Boolean

In

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

6.38.2.1. force
Copy link

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

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

6.38.3. update PUT
Copy link

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<data_center>
  <name>myupdatedname</name>
  <description>An updated description for the data center</description>
</data_center>
Copy to Clipboard Toggle word wrap
Expand
Table 6.114. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

data_center

DataCenter

In/Out

The data center that is being updated.

6.39. DataCenterNetwork
Copy link

A service to manage a specific data center network.

Expand
Table 6.115. Methods summary
NameSummary

get

Retrieves the data center network details.

remove

Removes the network.

update

Updates the network in the data center.

6.39.1. get GET
Copy link

Retrieves the data center network details.

Expand
Table 6.116. Parameters summary
NameTypeDirectionSummary

network

Network

Out

The data center network.

6.39.2. remove DELETE
Copy link

Removes the network.

6.39.3. update PUT
Copy link

Updates the network in the data center.

Expand
Table 6.117. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The data center network.

6.40. DataCenterNetworks
Copy link

A service to manage data center networks.

Expand
Table 6.118. Methods summary
NameSummary

add

Create a new network in a data center.

list

Lists networks in the data center.

6.40.1. add POST
Copy link

Create a new network in a data center.

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

POST /ovirt-engine/api/datacenters/123/networks
Copy to Clipboard Toggle word wrap

Use the following example in its body: 

<network>
  <name>mynetwork</name>
</network>
Copy to Clipboard Toggle word wrap
Expand
Table 6.119. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

The network object to be created in the data center.

6.40.2. list GET
Copy link

Lists networks in the data center.

Expand
Table 6.120. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

The list of networks which are in the data center.

6.40.2.1. max
Copy link

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

6.41. DataCenters
Copy link

A service to manage data centers.

Expand
Table 6.121. Methods summary
NameSummary

add

Creates a new data center.

list

Lists the data centers.

6.41.1. add POST
Copy link

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<data_center>
  <name>mydc</name>
  <local>false</local>
</data_center>
Copy to Clipboard Toggle word wrap
Expand
Table 6.122. Parameters summary
NameTypeDirectionSummary

data_center

DataCenter

In/Out

The data center that is being added.

6.41.2. list GET
Copy link

Lists the data centers.

The following request retrieves a representation of the data centers: 

GET /ovirt-engine/api/datacenters
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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

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

Expand
Table 6.123. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

data_centers

DataCenter[]

Out

 

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of data centers to return.

search

String

In

A query string used to restrict the returned data centers.

6.41.2.1. case_sensitive
Copy link

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

6.41.2.2. max
Copy link

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

6.42. Disk
Copy link

Manages a single disk.

Expand
Table 6.124. Methods summary
NameSummary

copy

This operation copies a disk to the specified storage domain.

export

 

get

 

move

Moves a disk to another storage domain.

remove

 

sparsify

Sparsify the disk.

6.42.1. copy POST
Copy link

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action>
  <storage_domain id="456"/>
  <disk>
    <name>mydisk</name>
  </disk>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.125. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

disk

Disk

In

 

filter

Boolean

In

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

storage_domain

StorageDomain

In

 

6.42.2. export POST
Copy link

Expand
Table 6.126. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the export should be performed asynchronously.

filter

Boolean

In

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

storage_domain

StorageDomain

In

 

6.42.3. get GET
Copy link

Expand
Table 6.127. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.42.4. move POST
Copy link

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
Copy to Clipboard Toggle word wrap

With the following request body: 

<action>
  <storage_domain id="456"/>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.128. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the move should be performed asynchronously.

filter

Boolean

In

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

storage_domain

StorageDomain

In

 

6.42.5. remove DELETE
Copy link

Expand
Table 6.129. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.42.6. sparsify POST
Copy link

Sparsify the disk.

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

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

6.43. DiskAttachment
Copy link

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

Expand
Table 6.130. Methods summary
NameSummary

get

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

remove

Removes the disk attachment.

update

Update the disk attachment and the disk properties within it.

6.43.1. get GET
Copy link

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
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.131. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

Out

 

6.43.2. remove DELETE
Copy link

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
Copy to Clipboard Toggle word wrap
Expand
Table 6.132. Parameters summary
NameTypeDirectionSummary

detach_only

Boolean

In

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

6.43.2.1. detach_only
Copy link

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

6.43.3. update PUT
Copy link

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.133. Parameters summary
NameTypeDirectionSummary

disk_attachment

DiskAttachment

In/Out

 

6.44. DiskAttachments
Copy link

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

Expand
Table 6.134. Methods summary
NameSummary

add

Adds a new disk attachment to the virtual machine.

list

List the disk that are attached to the virtual machine.

6.44.1. add POST
Copy link

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

<disk_attachment>
  <bootable>true</bootable>
  <pass_discard>true</pass_discard>
  <interface>ide</interface>
  <active>true</active>
  <disk id="123"/>
</disk_attachment>
Copy to Clipboard Toggle word wrap

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

<disk_attachment>
  <bootable>true</bootable>
  <pass_discard>true</pass_discard>
  <interface>ide</interface>
  <active>true</active>
  <disk>
    <name>mydisk</name>
    <provisioned_size>1024</provisioned_size>
    ...
  </disk>
</disk_attachment>
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap
Important

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

Expand
Table 6.135. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

In/Out

 

6.44.2. list GET
Copy link

List the disk that are attached to the virtual machine.

Expand
Table 6.136. Parameters summary
NameTypeDirectionSummary

attachments

DiskAttachment[]

Out

 

6.45. DiskProfile
Copy link

Expand
Table 6.137. Methods summary
NameSummary

get

 

remove

 

update

 

6.45.1. get GET
Copy link

Expand
Table 6.138. Parameters summary
NameTypeDirectionSummary

profile

DiskProfile

Out

 

6.45.2. remove DELETE
Copy link

Expand
Table 6.139. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.45.3. update PUT
Copy link

Expand
Table 6.140. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

DiskProfile

In/Out

 

6.46. DiskProfiles
Copy link

Expand
Table 6.141. Methods summary
NameSummary

add

 

list

 

6.46.1. add POST
Copy link

Expand
Table 6.142. Parameters summary
NameTypeDirectionSummary

profile

DiskProfile

In/Out

 

6.46.2. list GET
Copy link

Expand
Table 6.143. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profile

DiskProfile[]

Out

 

6.46.2.1. max
Copy link

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

6.47. DiskSnapshot
Copy link

Expand
Table 6.144. Methods summary
NameSummary

get

 

remove

 

6.47.1. get GET
Copy link

Expand
Table 6.145. Parameters summary
NameTypeDirectionSummary

snapshot

DiskSnapshot

Out

 

6.47.2. remove DELETE
Copy link

Expand
Table 6.146. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.48. DiskSnapshots
Copy link

Expand
Table 6.147. Methods summary
NameSummary

list

 

6.48.1. list GET
Copy link

Expand
Table 6.148. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

DiskSnapshot[]

Out

 

6.48.1.1. max
Copy link

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

6.49. Disks
Copy link

Manages the collection of disks available in the system.

Expand
Table 6.149. Methods summary
NameSummary

add

Adds a new floating disk.

list

Get list of disks.

6.49.1. add POST
Copy link

Adds a new floating disk.

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

Adding a new image disk:

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

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

POST /ovirt-engine/api/disks
Copy to Clipboard Toggle word wrap

With a request body as follows: 

<disk>
  <storage_domains>
    <storage_domain id="123"/>
  </storage_domains>
  <name>mydisk</name>
  <provisioned_size>1048576</provisioned_size>
  <format>cow</format>
</disk>
Copy to Clipboard Toggle word wrap

Adding a new direct LUN disk:

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

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

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

POST /ovirt-engine/api/disks
Copy to Clipboard Toggle word wrap

With a request body as follows: 

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

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

Adding a new Cinder disk:

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

POST /ovirt-engine/api/disks
Copy to Clipboard Toggle word wrap

With a request body as follows: 

<disk>
  <openstack_volume_type>
    <name>myceph</name>
  </openstack_volume_type>
  <storage_domains>
    <storage_domain>
      <name>cinderDomain</name>
    </storage_domain>
  </storage_domains>
  <provisioned_size>1073741824</provisioned_size>
  <interface>virtio</interface>
  <format>raw</format>
</disk>
Copy to Clipboard Toggle word wrap
Expand
Table 6.150. Parameters summary
NameTypeDirectionSummary

disk

Disk

In/Out

The disk.

6.49.2. list GET
Copy link

Get list of disks. 

GET /ovirt-engine/api/disks
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.151. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

disks

Disk[]

Out

List of retrieved disks.

max

Integer

In

Sets the maximum number of disks to return.

search

String

In

A query string used to restrict the returned disks.

unregistered

Boolean

In

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

6.49.2.1. case_sensitive
Copy link

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

6.49.2.2. max
Copy link

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

6.49.2.3. unregistered
Copy link

Indicates whether to retrieve a list of registered or unregistered disks in the storage domain. To get a list of unregistered disks in the storage domain the call should indicate the unregistered flag. For example, to get a list of unregistered disks the REST API call should look like this: 

GET /ovirt-engine/api/storagedomains/123/disks?unregistered=true
Copy to Clipboard Toggle word wrap

The default value of the unregistered flag is false.

Important

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

6.50. Domain
Copy link

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

Expand
Table 6.152. Methods summary
NameSummary

get

Gets the authentication domain information.

6.50.1. get GET
Copy link

Gets the authentication domain information.

Usage: 

GET /ovirt-engine/api/domains/5678
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.153. Parameters summary
NameTypeDirectionSummary

domain

Domain

Out

The authentication domain.

6.51. DomainGroup
Copy link

Expand
Table 6.154. Methods summary
NameSummary

get

 

6.51.1. get GET
Copy link

Expand
Table 6.155. Parameters summary
NameTypeDirectionSummary

get

Group

Out

 

6.52. DomainGroups
Copy link

Expand
Table 6.156. Methods summary
NameSummary

list

 

6.52.1. list GET
Copy link

Expand
Table 6.157. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

groups

Group[]

Out

 

max

Integer

In

Sets the maximum number of groups to return.

search

String

In

A query string used to restrict the returned groups.

6.52.1.1. case_sensitive
Copy link

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

6.52.1.2. max
Copy link

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

6.53. DomainUser
Copy link

A service to view a domain user in the system.

Expand
Table 6.158. Methods summary
NameSummary

get

Gets the domain user information.

6.53.1. get GET
Copy link

Gets the domain user information.

Usage: 

GET /ovirt-engine/api/domains/5678/users/1234
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.159. Parameters summary
NameTypeDirectionSummary

user

User

Out

The domain user.

6.54. DomainUsers
Copy link

A service to list all domain users in the system.

Expand
Table 6.160. Methods summary
NameSummary

list

List all the users in the domain.

6.54.1. list GET
Copy link

List all the users in the domain.

Usage: 

GET /ovirt-engine/api/domains/5678/users
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.161. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

max

Integer

In

Sets the maximum number of users to return.

search

String

In

A query string used to restrict the returned users.

users

User[]

Out

The list of users in the domain.

6.54.1.1. case_sensitive
Copy link

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

6.54.1.2. max
Copy link

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

6.55. Domains
Copy link

A service to list all authentication domains in the system.

Expand
Table 6.162. Methods summary
NameSummary

list

List all the authentication domains in the system.

6.55.1. list GET
Copy link

List all the authentication domains in the system.

Usage: 

GET /ovirt-engine/api/domains
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.163. Parameters summary
NameTypeDirectionSummary

domains

Domain[]

Out

The list of domains.

max

Integer

In

Sets the maximum number of domains to return.

6.55.1.1. max
Copy link

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

6.56. EngineKatelloErrata
Copy link

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

Expand
Table 6.164. Methods summary
NameSummary

list

Retrieves the representation of the Katello errata.

6.56.1. list GET
Copy link

Retrieves the representation of the Katello errata. 

GET /ovirt-engine/api/katelloerrata
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.165. Parameters summary
NameTypeDirectionSummary

errata

KatelloErratum[]

Out

A representation of Katello errata.

max

Integer

In

Sets the maximum number of errata to return.

6.56.1.1. max
Copy link

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

6.57. Event
Copy link

A service to manage an event in the system.

Expand
Table 6.166. Methods summary
NameSummary

get

Get an event.

remove

Removes an event from internal audit log.

6.57.1. get GET
Copy link

Get an event.

An example of getting an event: 

GET /ovirt-engine/api/events/123
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap

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

Expand
Table 6.167. Parameters summary
NameTypeDirectionSummary

event

Event

Out

 

6.57.2. remove DELETE
Copy link

Removes an event from internal audit log.

An event can be removed by sending following request 

DELETE /ovirt-engine/api/events/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.168. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.58. Events
Copy link

A service to manage events in the system.

Expand
Table 6.169. Methods summary
NameSummary

add

Adds an external event to the internal audit log.

list

Get list of events.

undelete

 

6.58.1. add POST
Copy link

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>
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Note

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

Expand
Table 6.170. Parameters summary
NameTypeDirectionSummary

event

Event

In/Out

 

6.58.2. list GET
Copy link

Get list of events. 

GET /ovirt-engine/api/events
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

The following events occur:

  • id="1" - The API logs in the admin user account.
  • id="2" - The API logs out of the admin user account.
Expand
Table 6.171. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

events

Event[]

Out

 

from

Integer

In

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

max

Integer

In

Sets the maximum number of events to return.

search

String

In

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

6.58.2.1. case_sensitive
Copy link

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

6.58.2.2. from
Copy link

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
Copy to Clipboard Toggle word wrap

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

6.58.2.3. max
Copy link

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

6.58.3. undelete POST
Copy link

Expand
Table 6.172. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the un-delete should be performed asynchronously.

6.59. ExternalComputeResource
Copy link

Expand
Table 6.173. Methods summary
NameSummary

get

 

6.59.1. get GET
Copy link

Expand
Table 6.174. Parameters summary
NameTypeDirectionSummary

resource

ExternalComputeResource

Out

 

6.60. ExternalComputeResources
Copy link

Expand
Table 6.175. Methods summary
NameSummary

list

 

6.60.1. list GET
Copy link

Expand
Table 6.176. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of resources to return.

resources

ExternalComputeResource[]

Out

 

6.60.1.1. max
Copy link

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

6.61. ExternalDiscoveredHost
Copy link

Expand
Table 6.177. Methods summary
NameSummary

get

 

6.61.1. get GET
Copy link

Expand
Table 6.178. Parameters summary
NameTypeDirectionSummary

host

ExternalDiscoveredHost

Out

 

6.62. ExternalDiscoveredHosts
Copy link

Expand
Table 6.179. Methods summary
NameSummary

list

 

6.62.1. list GET
Copy link

Expand
Table 6.180. Parameters summary
NameTypeDirectionSummary

hosts

ExternalDiscoveredHost[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

6.62.1.1. max
Copy link

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

6.63. ExternalHost
Copy link

Expand
Table 6.181. Methods summary
NameSummary

get

 

6.63.1. get GET
Copy link

Expand
Table 6.182. Parameters summary
NameTypeDirectionSummary

host

ExternalHost

Out

 

6.64. ExternalHostGroup
Copy link

Expand
Table 6.183. Methods summary
NameSummary

get

 

6.64.1. get GET
Copy link

Expand
Table 6.184. Parameters summary
NameTypeDirectionSummary

group

ExternalHostGroup

Out

 

6.65. ExternalHostGroups
Copy link

Expand
Table 6.185. Methods summary
NameSummary

list

 

6.65.1. list GET
Copy link

Expand
Table 6.186. Parameters summary
NameTypeDirectionSummary

groups

ExternalHostGroup[]

Out

 

max

Integer

In

Sets the maximum number of groups to return.

6.65.1.1. max
Copy link

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

6.66. ExternalHostProvider
Copy link

Expand
Table 6.187. Methods summary
NameSummary

get

 

importcertificates

 

remove

 

testconnectivity

 

update

 

6.66.1. get GET
Copy link

Expand
Table 6.188. Parameters summary
NameTypeDirectionSummary

provider

ExternalHostProvider

Out

 

6.66.2. importcertificates POST
Copy link

Expand
Table 6.189. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.66.3. remove DELETE
Copy link

Expand
Table 6.190. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.66.4. testconnectivity POST
Copy link

Expand
Table 6.191. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.66.5. update PUT
Copy link

Expand
Table 6.192. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

ExternalHostProvider

In/Out

 

6.67. ExternalHostProviders
Copy link

Expand
Table 6.193. Methods summary
NameSummary

add

 

list

 

6.67.1. add POST
Copy link

Expand
Table 6.194. Parameters summary
NameTypeDirectionSummary

provider

ExternalHostProvider

In/Out

 

6.67.2. list GET
Copy link

Expand
Table 6.195. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

ExternalHostProvider[]

Out

 

6.67.2.1. max
Copy link

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

6.68. ExternalHosts
Copy link

Expand
Table 6.196. Methods summary
NameSummary

list

 

6.68.1. list GET
Copy link

Expand
Table 6.197. Parameters summary
NameTypeDirectionSummary

hosts

ExternalHost[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

6.68.1.1. max
Copy link

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

6.69. ExternalProvider
Copy link

Expand
Table 6.198. Methods summary
NameSummary

importcertificates

 

testconnectivity

 

6.69.1. importcertificates POST
Copy link

Expand
Table 6.199. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.69.2. testconnectivity POST
Copy link

Expand
Table 6.200. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.70. ExternalProviderCertificate
Copy link

Expand
Table 6.201. Methods summary
NameSummary

get

 

6.70.1. get GET
Copy link

Expand
Table 6.202. Parameters summary
NameTypeDirectionSummary

certificate

Certificate

Out

 

6.71. ExternalProviderCertificates
Copy link

Expand
Table 6.203. Methods summary
NameSummary

list

 

6.71.1. list GET
Copy link

Expand
Table 6.204. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

Out

 

max

Integer

In

Sets the maximum number of certificates to return.

6.71.1.1. max
Copy link

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

6.72. ExternalVmImports
Copy link

Provides capability to import external virtual machines.

Expand
Table 6.205. Methods summary
NameSummary

add

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

6.72.1. add POST
Copy link

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
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.206. Parameters summary
NameTypeDirectionSummary

import

ExternalVmImport

In/Out

 

6.73. FenceAgent
Copy link

Expand
Table 6.207. Methods summary
NameSummary

get

 

remove

 

update

 

6.73.1. get GET
Copy link

Expand
Table 6.208. Parameters summary
NameTypeDirectionSummary

agent

Agent

Out

 

6.73.2. remove DELETE
Copy link

Expand
Table 6.209. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.73.3. update PUT
Copy link

Expand
Table 6.210. Parameters summary
NameTypeDirectionSummary

agent

Agent

In/Out

 

async

Boolean

In

Indicates if the update should be performed asynchronously.

6.74. FenceAgents
Copy link

Expand
Table 6.211. Methods summary
NameSummary

add

 

list

 

6.74.1. add POST
Copy link

Expand
Table 6.212. Parameters summary
NameTypeDirectionSummary

agent

Agent

In/Out

 

6.74.2. list GET
Copy link

Expand
Table 6.213. Parameters summary
NameTypeDirectionSummary

agents

Agent[]

Out

 

max

Integer

In

Sets the maximum number of agents to return.

6.74.2.1. max
Copy link

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

6.75. File
Copy link

Expand
Table 6.214. Methods summary
NameSummary

get

 

6.75.1. get GET
Copy link

Expand
Table 6.215. Parameters summary
NameTypeDirectionSummary

file

File

Out

 

6.76. Files
Copy link

Provides a way for clients to list available files.

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

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

Expand
Table 6.216. Methods summary
NameSummary

list

 

6.76.1. list GET
Copy link

Expand
Table 6.217. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

file

File[]

Out

 

max

Integer

In

Sets the maximum number of files to return.

search

String

In

A query string used to restrict the returned files.

6.76.1.1. case_sensitive
Copy link

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

6.76.1.2. max
Copy link

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

6.77. Filter
Copy link

Expand
Table 6.218. Methods summary
NameSummary

get

 

remove

 

6.77.1. get GET
Copy link

Expand
Table 6.219. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

result

Filter

Out

 

6.77.2. remove DELETE
Copy link

Expand
Table 6.220. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.78. Filters
Copy link

Expand
Table 6.221. Methods summary
NameSummary

add

 

list

 

6.78.1. add POST
Copy link

Expand
Table 6.222. Parameters summary
NameTypeDirectionSummary

filter

Filter

In/Out

 

6.78.2. list GET
Copy link

Expand
Table 6.223. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

filters

Filter[]

Out

 

max

Integer

In

Sets the maximum number of filters to return.

6.78.2.1. max
Copy link

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

6.79. GlusterBrick
Copy link

This service manages a single gluster brick.

Expand
Table 6.224. Methods summary
NameSummary

get

Get details of a brick.

remove

Removes a brick.

replace

Replaces this brick with a new one.

6.79.1. get GET
Copy link

Get details of a brick.

Retrieves status details of brick from underlying gluster volume with header All-Content set to true. This is the equivalent of running gluster volume status <volumename> <brickname> detail.

For example, to get the details of brick 234 of gluster volume 123, send a request like this: 

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234
Copy to Clipboard Toggle word wrap

Which will return a response body like this: 

<brick id="234">
  <name>host1:/rhgs/data/brick1</name>
  <brick_dir>/rhgs/data/brick1</brick_dir>
  <server_id>111</server_id>
  <status>up</status>
  <device>/dev/mapper/RHGS_vg1-lv_vmaddldisks</device>
  <fs_name>xfs</fs_name>
  <gluster_clients>
    <gluster_client>
      <bytes_read>2818417648</bytes_read>
      <bytes_written>1384694844</bytes_written>
      <client_port>1011</client_port>
      <host_name>client2</host_name>
    </gluster_client>
  </gluster_clients>
  <memory_pools>
    <memory_pool>
      <name>data-server:fd_t</name>
      <alloc_count>1626348</alloc_count>
      <cold_count>1020</cold_count>
      <hot_count>4</hot_count>
      <max_alloc>23</max_alloc>
      <max_stdalloc>0</max_stdalloc>
      <padded_size>140</padded_size>
      <pool_misses>0</pool_misses>
    </memory_pool>
  </memory_pools>
  <mnt_options>rw,seclabel,noatime,nodiratime,attr2,inode64,sunit=512,swidth=2048,noquota</mnt_options>
  <pid>25589</pid>
  <port>49155</port>
</brick>
Copy to Clipboard Toggle word wrap
Expand
Table 6.225. Parameters summary
NameTypeDirectionSummary

brick

GlusterBrick

Out

 

6.79.2. remove DELETE
Copy link

Removes a brick.

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

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

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234
Copy to Clipboard Toggle word wrap
Expand
Table 6.226. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.79.3. replace POST
Copy link

Replaces this brick with a new one.

Important

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

Expand
Table 6.227. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the replacement should be performed asynchronously.

force

Boolean

In

 

6.80. GlusterBricks
Copy link

This service manages the gluster bricks in a gluster volume

Expand
Table 6.228. Methods summary
NameSummary

activate

Activate the bricks post data migration of remove brick operation.

add

Adds a list of bricks to gluster volume.

list

Lists the bricks of a gluster volume.

migrate

Start migration of data prior to removing bricks.

remove

Removes bricks from gluster volume.

stopmigrate

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

6.80.1. activate POST
Copy link

Activate the bricks post data migration of remove brick operation.

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

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

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/activate
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.229. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

bricks

GlusterBrick[]

In

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

6.80.2. add POST
Copy link

Adds a list of bricks to gluster volume.

Used to expand a gluster volume by adding bricks. For replicated volume types, the parameter replica_count needs to be passed. In case the replica count is being increased, then the number of bricks needs to be equivalent to the number of replica sets.

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

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
Copy to Clipboard Toggle word wrap

With a request body like this: 

<bricks>
  <brick>
    <server_id>111</server_id>
    <brick_dir>/export/data/brick3</brick_dir>
  </brick>
</bricks>
Copy to Clipboard Toggle word wrap
Expand
Table 6.230. Parameters summary
NameTypeDirectionSummary

bricks

GlusterBrick[]

In/Out

The list of bricks to be added to the volume

replica_count

Integer

In

Replica count of volume post add operation.

stripe_count

Integer

In

Stripe count of volume post add operation.

6.80.3. list GET
Copy link

Lists the bricks of a gluster volume.

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

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
Copy to Clipboard Toggle word wrap

Provides an output as below: 

<bricks>
  <brick id="234">
    <name>host1:/rhgs/data/brick1</name>
    <brick_dir>/rhgs/data/brick1</brick_dir>
    <server_id>111</server_id>
    <status>up</status>
  </brick>
  <brick id="233">
    <name>host2:/rhgs/data/brick1</name>
    <brick_dir>/rhgs/data/brick1</brick_dir>
    <server_id>222</server_id>
    <status>up</status>
  </brick>
</bricks>
Copy to Clipboard Toggle word wrap
Expand
Table 6.231. Parameters summary
NameTypeDirectionSummary

bricks

GlusterBrick[]

Out

 

max

Integer

In

Sets the maximum number of bricks to return.

6.80.3.1. max
Copy link

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

6.80.4. migrate POST
Copy link

Start migration of data prior to removing bricks.

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

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

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/migrate
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>
Copy to Clipboard Toggle word wrap

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

Expand
Table 6.232. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the migration should be performed asynchronously.

bricks

GlusterBrick[]

In

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

6.80.5. remove DELETE
Copy link

Removes bricks from gluster volume.

The recommended way to remove bricks without data loss is to first migrate the data using stopmigrate and then removing them. If migrate was not called on bricks prior to remove, the bricks are removed without data migration which may lead to data loss.

For example, to delete the bricks from gluster volume 123, send a request like this: 

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
Copy to Clipboard Toggle word wrap

With a request body like this: 

<bricks>
  <brick>
    <name>host:brick_directory</name>
  </brick>
</bricks>
Copy to Clipboard Toggle word wrap
Expand
Table 6.233. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

bricks

GlusterBrick[]

In

The list of bricks to be removed

replica_count

Integer

In

Replica count of volume post add operation.

6.80.6. stopmigrate POST
Copy link

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

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

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

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/stopmigrate
Copy to Clipboard Toggle word wrap

With a request body like this: 

<bricks>
  <brick>
    <name>host:brick_directory</name>
  </brick>
</bricks>
Copy to Clipboard Toggle word wrap
Expand
Table 6.234. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

bricks

GlusterBrick[]

In

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

6.80.6.1. bricks
Copy link

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

6.81. GlusterHook
Copy link

Expand
Table 6.235. Methods summary
NameSummary

disable

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

enable

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

get

 

remove

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

resolve

Resolves missing hook conflict depending on the resolution type.

6.81.1. disable POST
Copy link

Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the cluster. This updates the hook status to DISABLED in database.

Expand
Table 6.236. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.81.2. enable POST
Copy link

Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the cluster. This updates the hook status to DISABLED in database.

Expand
Table 6.237. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.81.3. get GET
Copy link

Expand
Table 6.238. Parameters summary
NameTypeDirectionSummary

hook

GlusterHook

Out

 

6.81.4. remove DELETE
Copy link

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

Expand
Table 6.239. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.81.5. resolve POST
Copy link

Resolves missing hook conflict depending on the resolution type.

For ADD resolves by copying hook stored in engine database to all servers where the hook is missing. The engine maintains a list of all servers where hook is missing.

For COPY resolves conflict in hook content by copying hook stored in engine database to all servers where the hook is missing. The engine maintains a list of all servers where the content is conflicting. If a host id is passed as parameter, the hook content from the server is used as the master to copy to other servers in cluster.

Expand
Table 6.240. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

host

Host

In

 

resolution_type

String

In

 

6.82. GlusterHooks
Copy link

Expand
Table 6.241. Methods summary
NameSummary

list

 

6.82.1. list GET
Copy link

Expand
Table 6.242. Parameters summary
NameTypeDirectionSummary

hooks

GlusterHook[]

Out

 

max

Integer

In

Sets the maximum number of hooks to return.

6.82.1.1. max
Copy link

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

6.83. GlusterVolume
Copy link

This service manages a single gluster volume.

Expand
Table 6.243. Methods summary
NameSummary

get

Get the gluster volume details.

getprofilestatistics

Get gluster volume profile statistics.

rebalance

Rebalance the gluster volume.

remove

Removes the gluster volume.

resetalloptions

Resets all the options set in the gluster volume.

resetoption

Resets a particular option in the gluster volume.

setoption

Sets a particular option in the gluster volume.

start

Starts the gluster volume.

startprofile

Start profiling the gluster volume.

stop

Stops the gluster volume.

stopprofile

Stop profiling the gluster volume.

stoprebalance

Stop rebalancing the gluster volume.

6.83.1. get GET
Copy link

Get the gluster volume details.

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

GET /ovirt-engine/api/clusters/456/glustervolumes/123
Copy to Clipboard Toggle word wrap

This GET request will return the following output: 

<gluster_volume id="123">
 <name>data</name>
 <link href="/ovirt-engine/api/clusters/456/glustervolumes/123/glusterbricks" rel="glusterbricks"/>
 <disperse_count>0</disperse_count>
 <options>
   <option>
     <name>storage.owner-gid</name>
     <value>36</value>
   </option>
   <option>
     <name>performance.io-cache</name>
     <value>off</value>
   </option>
   <option>
     <name>cluster.data-self-heal-algorithm</name>
     <value>full</value>
   </option>
 </options>
 <redundancy_count>0</redundancy_count>
 <replica_count>3</replica_count>
 <status>up</status>
 <stripe_count>0</stripe_count>
 <transport_types>
   <transport_type>tcp</transport_type>
 </transport_types>
 <volume_type>replicate</volume_type>
 </gluster_volume>
Copy to Clipboard Toggle word wrap
Expand
Table 6.244. Parameters summary
NameTypeDirectionSummary

volume

GlusterVolume

Out

Representation of the gluster volume.

6.83.2. getprofilestatistics POST
Copy link

Get gluster volume profile statistics.

For example, to get profile statistics for a gluster volume with identifier 123 in cluster 456, send a request like this: 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/getprofilestatistics
Copy to Clipboard Toggle word wrap
Expand
Table 6.245. Parameters summary
NameTypeDirectionSummary

details

GlusterVolumeProfileDetails

Out

Gluster volume profiling information returned from the action.

6.83.3. rebalance POST
Copy link

Rebalance the gluster volume.

Rebalancing a gluster volume helps to distribute the data evenly across all the bricks. After expanding or shrinking a gluster volume (without migrating data), we need to rebalance the data among the bricks. In a non-replicated volume, all bricks should be online to perform the rebalance operation. In a replicated volume, at least one of the bricks in the replica should be online.

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

POST /ovirt-engine/api/clusters/456/glustervolumes/123/rebalance
Copy to Clipboard Toggle word wrap
Expand
Table 6.246. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the rebalance should be performed asynchronously.

fix_layout

Boolean

In

If set to true, rebalance will only fix the layout so that new data added to the volume is distributed across all the hosts.

force

Boolean

In

Indicates if the rebalance should be force started.

6.83.3.1. fix_layout
Copy link

If set to true, rebalance will only fix the layout so that new data added to the volume is distributed across all the hosts. But it will not migrate/rebalance the existing data. Default is false.

6.83.3.2. force
Copy link

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

6.83.4. remove DELETE
Copy link

Removes the gluster volume.

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

DELETE /ovirt-engine/api/clusters/456/glustervolumes/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.247. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.83.5. resetalloptions POST
Copy link

Resets all the options set in the gluster volume.

For example, to reset all options in a gluster volume with identifier 123 in cluster 456, send a request like this: 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetalloptions
Copy to Clipboard Toggle word wrap
Expand
Table 6.248. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

6.83.6. resetoption POST
Copy link

Resets a particular option in the gluster volume.

For example, to reset a particular option option1 in a gluster volume with identifier 123 in cluster 456, send a request like this: 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetoption
Copy to Clipboard Toggle word wrap

With the following request body: 

<action>
 <option name="option1"/>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.249. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reset should be performed asynchronously.

force

Boolean

In

 

option

Option

In

Option to reset.

6.83.7. setoption POST
Copy link

Sets a particular option in the gluster volume.

For example, to set option1 with value value1 in a gluster volume with identifier 123 in cluster 456, send a request like this: 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/setoption
Copy to Clipboard Toggle word wrap

With the following request body: 

<action>
 <option name="option1" value="value1"/>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.250. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

option

Option

In

Option to set.

6.83.8. start POST
Copy link

Starts the gluster volume.

A Gluster Volume should be started to read/write data. For example, to start a gluster volume with identifier 123 in cluster 456, send a request like this: 

POST /ovirt-engine/api/clusters/456/glustervolumes/123/start
Copy to Clipboard Toggle word wrap
Expand
Table 6.251. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

Indicates if the volume should be force started.

6.83.8.1. force
Copy link

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

6.83.9. startprofile POST
Copy link

Start profiling the gluster volume.

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

POST /ovirt-engine/api/clusters/456/glustervolumes/123/startprofile
Copy to Clipboard Toggle word wrap
Expand
Table 6.252. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.83.10. stop POST
Copy link

Stops the gluster volume.

Stopping a volume will make its data inaccessible.

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

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stop
Copy to Clipboard Toggle word wrap
Expand
Table 6.253. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

 

6.83.11. stopprofile POST
Copy link

Stop profiling the gluster volume.

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

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stopprofile
Copy to Clipboard Toggle word wrap
Expand
Table 6.254. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.83.12. stoprebalance POST
Copy link

Stop rebalancing the gluster volume.

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

POST /ovirt-engine/api/clusters/456/glustervolumes/123/stoprebalance
Copy to Clipboard Toggle word wrap
Expand
Table 6.255. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.84. GlusterVolumes
Copy link

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

Expand
Table 6.256. Methods summary
NameSummary

add

Creates a new gluster volume.

list

Lists all gluster volumes in the cluster.

6.84.1. add POST
Copy link

Creates a new gluster volume.

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

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

POST /ovirt-engine/api/clusters/123/glustervolumes
Copy to Clipboard Toggle word wrap

With the following request body: 

<gluster_volume>
  <name>myvolume</name>
  <volume_type>replicate</volume_type>
  <replica_count>3</replica_count>
  <bricks>
    <brick>
      <server_id>server1</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
    <brick>
      <server_id>server2</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
    <brick>
      <server_id>server3</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
  <bricks>
</gluster_volume>
Copy to Clipboard Toggle word wrap
Expand
Table 6.257. Parameters summary
NameTypeDirectionSummary

volume

GlusterVolume

In/Out

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

6.84.2. list GET
Copy link

Lists all gluster volumes in the cluster.

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

GET /ovirt-engine/api/clusters/456/glustervolumes
Copy to Clipboard Toggle word wrap
Expand
Table 6.258. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

max

Integer

In

Sets the maximum number of volumes to return.

search

String

In

A query string used to restrict the returned volumes.

volumes

GlusterVolume[]

Out

 

6.84.2.1. case_sensitive
Copy link

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

6.84.2.2. max
Copy link

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

6.85. Group
Copy link

Expand
Table 6.259. Methods summary
NameSummary

get

 

remove

 

6.85.1. get GET
Copy link

Expand
Table 6.260. Parameters summary
NameTypeDirectionSummary

get

Group

Out

 

6.85.2. remove DELETE
Copy link

Expand
Table 6.261. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.86. Groups
Copy link

Expand
Table 6.262. Methods summary
NameSummary

add

Add group from a directory service.

list

 

6.86.1. add POST
Copy link

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

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

POST /ovirt-engine/api/groups
Copy to Clipboard Toggle word wrap

With a request body like this: 

<group>
  <name>Developers</name>
  <domain>
    <name>internal-authz</name>
  </domain>
</group>
Copy to Clipboard Toggle word wrap
Expand
Table 6.263. Parameters summary
NameTypeDirectionSummary

group

Group

In/Out

 

6.86.2. list GET
Copy link

Expand
Table 6.264. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

groups

Group[]

Out

 

max

Integer

In

Sets the maximum number of groups to return.

search

String

In

A query string used to restrict the returned groups.

6.86.2.1. case_sensitive
Copy link

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

6.86.2.2. max
Copy link

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

6.87. Host
Copy link

A service to manage a host.

Expand
Table 6.265. Methods summary
NameSummary

activate

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

approve

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

commitnetconfig

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

deactivate

Deactivate the host to perform maintenance tasks.

enrollcertificate

Enroll certificate of the host.

fence

Controls host’s power management device.

forceselectspm

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

get

Get the host details.

install

Install VDSM and related software on the host.

iscsidiscover

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

iscsilogin

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

refresh

Refresh the host devices and capabilities.

remove

Remove the host from the system.

setupnetworks

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

unregisteredstoragedomainsdiscover

 

update

Update the host properties.

upgrade

Upgrade VDSM and selected software on the host.

upgradecheck

Check if there are upgrades available for the host.

6.87.1. activate POST
Copy link

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

Expand
Table 6.266. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.87.2. approve POST
Copy link

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

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

Expand
Table 6.267. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the approval should be performed asynchronously.

cluster

Cluster

In

 

6.87.3. commitnetconfig POST
Copy link

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

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

Important

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

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

POST /ovirt-engine/api/hosts/123/commitnetconfig
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.268. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.87.4. deactivate POST
Copy link

Deactivate the host to perform maintenance tasks.

Expand
Table 6.269. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

reason

String

In

 

stop_gluster_service

Boolean

In

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

6.87.4.1. stop_gluster_service
Copy link

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

6.87.5. enrollcertificate POST
Copy link

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

Expand
Table 6.270. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the enrollment should be performed asynchronously.

6.87.6. fence POST
Copy link

Controls host’s power management device.

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

#!/bin/sh -ex

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

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

async

Boolean

In

Indicates if the fencing should be performed asynchronously.

fence_type

String

In

 

power_management

PowerManagement

Out

 

6.87.7. forceselectspm POST
Copy link

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

POST /ovirt-engine/api/hosts/123/forceselectspm
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.272. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.87.8. get GET
Copy link

Get the host details.

Expand
Table 6.273. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

host

Host

Out

 

6.87.9. install POST
Copy link

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

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

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

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

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

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

Expand
Table 6.274. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the installation should be performed asynchronously.

deploy_hosted_engine

Boolean

In

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

host

Host

In

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

image

String

In

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

root_password

String

In

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

ssh

Ssh

In

The SSH details used to connect to the host.

undeploy_hosted_engine

Boolean

In

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

6.87.9.1. deploy_hosted_engine
Copy link

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

6.87.9.2. undeploy_hosted_engine
Copy link

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

6.87.10. iscsidiscover POST
Copy link

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

Expand
Table 6.275. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the discovery should be performed asynchronously.

iscsi

IscsiDetails

In

The target iSCSI device.

iscsi_targets

String[]

Out

The iSCSI targets.

6.87.11. iscsilogin POST
Copy link

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

Expand
Table 6.276. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the login should be performed asynchronously.

iscsi

IscsiDetails

In

The target iSCSI device.

6.87.12. refresh POST
Copy link

Refresh the host devices and capabilities.

Expand
Table 6.277. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the refresh should be performed asynchronously.

6.87.13. remove DELETE
Copy link

Remove the host from the system. 

#!/bin/sh -ex

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

curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request DELETE \
--header "Version: 4" \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc"
Copy to Clipboard Toggle word wrap
Expand
Table 6.278. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.87.14. setupnetworks POST
Copy link

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

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

#!/bin/sh -ex

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

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

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

<options name="mode" value="4"/>
<options name="miimon" value="100"/>
<ip address="192.168.122.10" netmask="255.255.255.0"/>
Copy to Clipboard Toggle word wrap

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

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

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

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

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

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

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

Expand
Table 6.279. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

check_connectivity

Boolean

In

 

connectivity_timeout

Integer

In

 

modified_bonds

HostNic[]

In

 

modified_labels

NetworkLabel[]

In

 

modified_network_attachments

NetworkAttachment[]

In

 

removed_bonds

HostNic[]

In

 

removed_labels

NetworkLabel[]

In

 

removed_network_attachments

NetworkAttachment[]

In

 

synchronized_network_attachments

NetworkAttachment[]

In

 

6.87.15. unregisteredstoragedomainsdiscover POST
Copy link

Expand
Table 6.280. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the discovery should be performed asynchronously.

iscsi

IscsiDetails

In

 

storage_domains

StorageDomain[]

Out

 

6.87.16. update PUT
Copy link

Update the host properties.

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

PUT /ovirt-engine/api/hosts/123
Copy to Clipboard Toggle word wrap

With request body like this: 

<host>
  <os>
    <custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline>
  </os>
</host>
Copy to Clipboard Toggle word wrap
Expand
Table 6.281. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

host

Host

In/Out

 

6.87.17. upgrade POST
Copy link

Upgrade VDSM and selected software on the host.

Expand
Table 6.282. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the upgrade should be performed asynchronously.

6.87.18. upgradecheck POST
Copy link

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

6.88. HostDevice
Copy link

A service to access a particular device of a host.

Expand
Table 6.283. Methods summary
NameSummary

get

Retrieve information about a particular host’s device.

6.88.1. get GET
Copy link

Retrieve information about a particular host’s device.

An example of getting a host device: 

GET /ovirt-engine/api/hosts/123/devices/456
Copy to Clipboard Toggle word wrap 
<host_device href="/ovirt-engine/api/hosts/123/devices/456" id="456">
  <name>usb_1_9_1_1_0</name>
  <capability>usb</capability>
  <host href="/ovirt-engine/api/hosts/123" id="123"/>
  <parent_device href="/ovirt-engine/api/hosts/123/devices/789" id="789">
    <name>usb_1_9_1</name>
  </parent_device>
</host_device>
Copy to Clipboard Toggle word wrap
Expand
Table 6.284. Parameters summary
NameTypeDirectionSummary

device

HostDevice

Out

 

6.89. HostDevices
Copy link

A service to access host devices.

Expand
Table 6.285. Methods summary
NameSummary

list

List the devices of a host.

6.89.1. list GET
Copy link

List the devices of a host.

Expand
Table 6.286. Parameters summary
NameTypeDirectionSummary

devices

HostDevice[]

Out

 

max

Integer

In

Sets the maximum number of devices to return.

6.89.1.1. max
Copy link

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

6.90. HostHook
Copy link

Expand
Table 6.287. Methods summary
NameSummary

get

 

6.90.1. get GET
Copy link

Expand
Table 6.288. Parameters summary
NameTypeDirectionSummary

hook

Hook

Out

 

6.91. HostHooks
Copy link

Expand
Table 6.289. Methods summary
NameSummary

list

 

6.91.1. list GET
Copy link

Expand
Table 6.290. Parameters summary
NameTypeDirectionSummary

hooks

Hook[]

Out

 

max

Integer

In

Sets the maximum number of hooks to return.

6.91.1.1. max
Copy link

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

6.92. HostNic
Copy link

A service to manage a network interface of a host.

Expand
Table 6.291. Methods summary
NameSummary

get

 

updatevirtualfunctionsconfiguration

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

6.92.1. get GET
Copy link

Expand
Table 6.292. Parameters summary
NameTypeDirectionSummary

nic

HostNic

Out

 

6.92.2. updatevirtualfunctionsconfiguration POST
Copy link

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

  • allNetworksAllowed
  • numberOfVirtualFunctions

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

Expand
Table 6.293. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

In

 

6.93. HostNics
Copy link

A service to manage the network interfaces of a host.

Expand
Table 6.294. Methods summary
NameSummary

list

 

6.93.1. list GET
Copy link

Expand
Table 6.295. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

HostNic[]

Out

 

6.93.1.1. max
Copy link

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

6.94. HostNumaNode
Copy link

Expand
Table 6.296. Methods summary
NameSummary

get

 

6.94.1. get GET
Copy link

Expand
Table 6.297. Parameters summary
NameTypeDirectionSummary

node

NumaNode

Out

 

6.95. HostNumaNodes
Copy link

Expand
Table 6.298. Methods summary
NameSummary

list

 

6.95.1. list GET
Copy link

Expand
Table 6.299. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of nodes to return.

nodes

NumaNode[]

Out

 

6.95.1.1. max
Copy link

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

6.96. HostStorage
Copy link

A service to manage host storages.

Expand
Table 6.300. Methods summary
NameSummary

list

Get list of storages.

6.96.1. list GET
Copy link

Get list of storages. 

GET /ovirt-engine/api/hosts/123/storage
Copy to Clipboard Toggle word wrap

The XML response you get will be like this one: 

<host_storages>
  <host_storage id="123">
    ...
  </host_storage>
  ...
</host_storages>
Copy to Clipboard Toggle word wrap
Expand
Table 6.301. Parameters summary
NameTypeDirectionSummary

report_status

Boolean

In

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

storages

HostStorage[]

Out

Retrieved list of storages.

6.96.1.1. report_status
Copy link

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

The default is true for backward compatibility.

Here an example with the LUN status : 

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

Here an example without the LUN status : 

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

6.97. Hosts
Copy link

A service that manages hosts.

Expand
Table 6.302. Methods summary
NameSummary

add

Creates a new host.

list

Get a list of all available hosts.

6.97.1. add POST
Copy link

Creates a new host.

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

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

POST /ovirt-engine/api/hosts
Copy to Clipboard Toggle word wrap

With the following request body: 

<host>
  <name>myhost</name>
  <address>myhost.example.com</address>
  <root_password>myrootpassword</root_password>
</host>
Copy to Clipboard Toggle word wrap
Note

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

Important

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

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

POST /ovirt-engine/api/hosts?deploy_hosted_engine=true
Copy to Clipboard Toggle word wrap
Expand
Table 6.303. Parameters summary
NameTypeDirectionSummary

deploy_hosted_engine

Boolean

In

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

host

Host

In/Out

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

undeploy_hosted_engine

Boolean

In

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

6.97.1.1. deploy_hosted_engine
Copy link

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

6.97.1.2. undeploy_hosted_engine
Copy link

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

6.97.2. list GET
Copy link

Get a list of all available hosts.

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

GET /ovirt-engine/api/hosts
Copy to Clipboard Toggle word wrap

The response body will be something like this: 

<hosts>
  <host href="/ovirt-engine/api/hosts/123" id="123">
    ...
  </host>
  <host href="/ovirt-engine/api/hosts/456" id="456">
    ...
  </host>
  ...
</host>
Copy to Clipboard Toggle word wrap
Expand
Table 6.304. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

filter

Boolean

In

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

hosts

Host[]

Out

 

max

Integer

In

Sets the maximum number of hosts to return.

search

String

In

A query string used to restrict the returned hosts.

6.97.2.1. case_sensitive
Copy link

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

6.97.2.2. max
Copy link

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

6.98. Icon
Copy link

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

Expand
Table 6.305. Methods summary
NameSummary

get

Get an icon.

6.98.1. get GET
Copy link

Get an icon. 

GET /ovirt-engine/api/icons/123
Copy to Clipboard Toggle word wrap

You will get a XML response like this one: 

<icon id="123">
  <data>Some binary data here</data>
  <media_type>image/png</media_type>
</icon>
Copy to Clipboard Toggle word wrap
Expand
Table 6.306. Parameters summary
NameTypeDirectionSummary

icon

Icon

Out

Retrieved icon.

6.99. Icons
Copy link

A service to manage icons.

Expand
Table 6.307. Methods summary
NameSummary

list

Get a list of icons.

6.99.1. list GET
Copy link

Get a list of icons. 

GET /ovirt-engine/api/icons
Copy to Clipboard Toggle word wrap

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

<icons>
  <icon id="123">
    <data>...</data>
    <media_type>image/png</media_type>
  </icon>
  ...
</icons>
Copy to Clipboard Toggle word wrap
Expand
Table 6.308. Parameters summary
NameTypeDirectionSummary

icons

Icon[]

Out

Retrieved list of icons.

max

Integer

In

Sets the maximum number of icons to return.

6.99.1.1. max
Copy link

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

6.100. Image
Copy link

Expand
Table 6.309. Methods summary
NameSummary

get

 

import

Imports an image.

6.100.1. get GET
Copy link

Expand
Table 6.310. Parameters summary
NameTypeDirectionSummary

image

Image

Out

 

6.100.2. import POST
Copy link

Imports an image.

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

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

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

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

Expand
Table 6.311. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the import should be performed asynchronously.

cluster

Cluster

In

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

disk

Disk

In

The disk to import.

import_as_template

Boolean

In

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

storage_domain

StorageDomain

In

The storage domain to which the disk should be imported.

template

Template

In

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

6.101. ImageTransfer
Copy link

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

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

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

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

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

E.g: 

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

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

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

For example: 

transfer_service = transfers_service.image_transfer_service(transfer.id)
while transfer.phase == types.ImageTransferPhase.INITIALIZING:
   time.sleep(3)
   transfer = transfer_service.get()
Copy to Clipboard Toggle word wrap

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

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

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

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

transfer_headers = {
   'Authorization' :  transfer.signed_ticket,
}
Copy to Clipboard Toggle word wrap

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

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

# Create a new instance of the connection.
proxy_connection = HTTPSConnection(
   url.hostname,
   url.port,
   context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)
)
Copy to Clipboard Toggle word wrap

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

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

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

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

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

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

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

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

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

For example: 

transfer_service.finalize()
Copy to Clipboard Toggle word wrap

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

Expand
Table 6.312. Methods summary
NameSummary

extend

Extend the image transfer session.

finalize

After finishing to transfer the data, finalize the transfer.

get

Get the image transfer entity.

pause

Pause the image transfer session.

resume

Resume the image transfer session.

6.101.1. extend POST
Copy link

Extend the image transfer session.

6.101.2. finalize POST
Copy link

After finishing to transfer the data, finalize the transfer.

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

6.101.3. get GET
Copy link

Get the image transfer entity.

Expand
Table 6.313. Parameters summary
NameTypeDirectionSummary

image_transfer

ImageTransfer

Out

 

6.101.4. pause POST
Copy link

Pause the image transfer session.

6.101.5. resume POST
Copy link

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

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

while transfer.phase == types.ImageTransferPhase.RESUMING:
   time.sleep(1)
   transfer = transfer_service.get()
Copy to Clipboard Toggle word wrap

6.102. ImageTransfers
Copy link

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

Expand
Table 6.314. Methods summary
NameSummary

add

Add a new image transfer.

list

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

6.102.1. add POST
Copy link

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

Expand
Table 6.315. Parameters summary
NameTypeDirectionSummary

image_transfer

ImageTransfer

In/Out

 

6.102.2. list GET
Copy link

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

Expand
Table 6.316. Parameters summary
NameTypeDirectionSummary

image_transfer

ImageTransfer[]

Out

 

6.103. Images
Copy link

Expand
Table 6.317. Methods summary
NameSummary

list

 

6.103.1. list GET
Copy link

Expand
Table 6.318. Parameters summary
NameTypeDirectionSummary

images

Image[]

Out

 

max

Integer

In

Sets the maximum number of images to return.

6.103.1.1. max
Copy link

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

6.104. InstanceType
Copy link

Expand
Table 6.319. Methods summary
NameSummary

get

Get a specific instance type and it’s attributes.

remove

Removes a specific instance type from the system.

update

Update a specific instance type and it’s attributes.

6.104.1. get GET
Copy link

Get a specific instance type and it’s attributes. 

GET /ovirt-engine/api/instancetypes/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.320. Parameters summary
NameTypeDirectionSummary

instance_type

InstanceType

Out

 

6.104.2. remove DELETE
Copy link

Removes a specific instance type from the system.

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

DELETE /ovirt-engine/api/instancetypes/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.321. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.104.3. update PUT
Copy link

Update a specific instance type and it’s attributes.

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

PUT /ovirt-engine/api/instancetypes/123
Copy to Clipboard Toggle word wrap

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

<instance_type>
  <memory>1073741824</memory>
  <cpu>
    <topology>
      <cores>1</cores>
      <sockets>2</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
</instance_type>
Copy to Clipboard Toggle word wrap
Expand
Table 6.322. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

instance_type

InstanceType

In/Out

 

6.105. InstanceTypeGraphicsConsole
Copy link

Expand
Table 6.323. Methods summary
NameSummary

get

Gets graphics console configuration of the instance type.

remove

Remove the graphics console from the instance type.

6.105.1. get GET
Copy link

Gets graphics console configuration of the instance type.

Expand
Table 6.324. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

Out

The information about the graphics console of the instance type.

6.105.2. remove DELETE
Copy link

Remove the graphics console from the instance type.

Expand
Table 6.325. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.106. InstanceTypeGraphicsConsoles
Copy link

Expand
Table 6.326. Methods summary
NameSummary

add

Add new graphics console to the instance type.

list

Lists all the configured graphics consoles of the instance type.

6.106.1. add POST
Copy link

Add new graphics console to the instance type.

Expand
Table 6.327. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

In/Out

 

6.106.2. list GET
Copy link

Lists all the configured graphics consoles of the instance type.

Expand
Table 6.328. Parameters summary
NameTypeDirectionSummary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the instance type.

max

Integer

In

Sets the maximum number of consoles to return.

6.106.2.1. max
Copy link

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

6.107. InstanceTypeNic
Copy link

Expand
Table 6.329. Methods summary
NameSummary

get

Gets network interface configuration of the instance type.

remove

Remove the network interface from the instance type.

update

Updates the network interface configuration of the instance type.

6.107.1. get GET
Copy link

Gets network interface configuration of the instance type.

Expand
Table 6.330. Parameters summary
NameTypeDirectionSummary

nic

Nic

Out

 

6.107.2. remove DELETE
Copy link

Remove the network interface from the instance type.

Expand
Table 6.331. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.107.3. update PUT
Copy link

Updates the network interface configuration of the instance type.

Expand
Table 6.332. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

 

6.108. InstanceTypeNics
Copy link

Expand
Table 6.333. Methods summary
NameSummary

add

Add new network interface to the instance type.

list

Lists all the configured network interface of the instance type.

6.108.1. add POST
Copy link

Add new network interface to the instance type.

Expand
Table 6.334. Parameters summary
NameTypeDirectionSummary

nic

Nic

In/Out

 

6.108.2. list GET
Copy link

Lists all the configured network interface of the instance type.

Expand
Table 6.335. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

 

search

String

In

A query string used to restrict the returned templates.

6.108.2.1. max
Copy link

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

6.109. InstanceTypeWatchdog
Copy link

Expand
Table 6.336. Methods summary
NameSummary

get

Gets watchdog configuration of the instance type.

remove

Remove a watchdog from the instance type.

update

Updates the watchdog configuration of the instance type.

6.109.1. get GET
Copy link

Gets watchdog configuration of the instance type.

Expand
Table 6.337. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

Out

 

6.109.2. remove DELETE
Copy link

Remove a watchdog from the instance type.

Expand
Table 6.338. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.109.3. update PUT
Copy link

Updates the watchdog configuration of the instance type.

Expand
Table 6.339. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

 

6.110. InstanceTypeWatchdogs
Copy link

Expand
Table 6.340. Methods summary
NameSummary

add

Add new watchdog to the instance type.

list

Lists all the configured watchdogs of the instance type.

6.110.1. add POST
Copy link

Add new watchdog to the instance type.

Expand
Table 6.341. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

In/Out

 

6.110.2. list GET
Copy link

Lists all the configured watchdogs of the instance type.

Expand
Table 6.342. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of watchdogs to return.

search

String

In

A query string used to restrict the returned templates.

watchdogs

Watchdog[]

Out

 

6.110.2.1. max
Copy link

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

6.111. InstanceTypes
Copy link

Expand
Table 6.343. Methods summary
NameSummary

add

Creates a new instance type.

list

Lists all existing instance types in the system.

6.111.1. add POST
Copy link

Creates a new instance type.

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

POST /ovirt-engine/api/instancetypes
Copy to Clipboard Toggle word wrap

With a request body like this: 

<instance_type>
  <name>myinstancetype</name>
</template>
Copy to Clipboard Toggle word wrap

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

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

instance_type

InstanceType

In/Out

 

6.111.2. list GET
Copy link

Lists all existing instance types in the system.

Expand
Table 6.345. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

instance_type

InstanceType[]

Out

 

max

Integer

In

Sets the maximum number of instance types to return.

search

String

In

A query string used to restrict the returned templates.

6.111.2.1. case_sensitive
Copy link

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

6.111.2.2. max
Copy link

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

6.112. IscsiBond
Copy link

Expand
Table 6.346. Methods summary
NameSummary

get

 

remove

Removes of an existing iSCSI bond.

update

Updates an iSCSI bond.

6.112.1. get GET
Copy link

Expand
Table 6.347. Parameters summary
NameTypeDirectionSummary

bond

IscsiBond

Out

 

6.112.2. remove DELETE
Copy link

Removes of an existing iSCSI bond.

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

DELETE /ovirt-engine/api/datacenters/123/iscsibonds/456
Copy to Clipboard Toggle word wrap
Expand
Table 6.348. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.112.3. update PUT
Copy link

Updates an iSCSI bond.

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

PUT /ovirt-engine/api/datacenters/123/iscsibonds/1234
Copy to Clipboard Toggle word wrap

The request body should look like this: 

<iscsi_bond>
   <name>mybond</name>
   <description>My iSCSI bond</description>
</iscsi_bond>
Copy to Clipboard Toggle word wrap
Expand
Table 6.349. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

bond

IscsiBond

In/Out

 

6.113. IscsiBonds
Copy link

Expand
Table 6.350. Methods summary
NameSummary

add

Create a new iSCSI bond on a data center.

list

 

6.113.1. add POST
Copy link

Create a new iSCSI bond on a data center.

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

POST /ovirt-engine/api/datacenters/123/iscsibonds
Copy to Clipboard Toggle word wrap

The request body should look like this: 

<iscsi_bond>
  <name>mybond</name>
  <storage_connections>
    <storage_connection id="456"/>
    <storage_connection id="789"/>
  </storage_connections>
  <networks>
    <network id="abc"/>
  </networks>
</iscsi_bond>
Copy to Clipboard Toggle word wrap
Expand
Table 6.351. Parameters summary
NameTypeDirectionSummary

bond

IscsiBond

In/Out

 

6.113.2. list GET
Copy link

Expand
Table 6.352. Parameters summary
NameTypeDirectionSummary

bonds

IscsiBond[]

Out

 

max

Integer

In

Sets the maximum number of bonds to return.

6.113.2.1. max
Copy link

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

6.114. Job
Copy link

A service to manage a job.

Expand
Table 6.353. Methods summary
NameSummary

clear

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

end

Marks an external job execution as ended.

get

Retrieves a job.

6.114.1. clear POST
Copy link

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

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

POST /ovirt-engine/api/jobs/clear
Copy to Clipboard Toggle word wrap

With the following request body: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.354. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.114.2. end POST
Copy link

Marks an external job execution as ended.

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

POST /ovirt-engine/api/jobs/end
Copy to Clipboard Toggle word wrap

With the following request body: 

<action>
  <force>true</force>
  <status>finished</status>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.355. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

Indicates if the job should be forcibly terminated.

succeeded

Boolean

In

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

6.114.2.1. succeeded
Copy link

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

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

6.114.3. get GET
Copy link

Retrieves a job. 

GET /ovirt-engine/api/jobs/123
Copy to Clipboard Toggle word wrap

You will receive response in XML like this one: 

<job href="/ovirt-engine/api/jobs/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
    <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
  </actions>
  <description>Adding Disk</description>
  <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
  <auto_cleared>true</auto_cleared>
  <end_time>2016-12-12T23:07:29.758+02:00</end_time>
  <external>false</external>
  <last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
  <start_time>2016-12-12T23:07:26.593+02:00</start_time>
  <status>failed</status>
  <owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
Copy to Clipboard Toggle word wrap
Expand
Table 6.356. Parameters summary
NameTypeDirectionSummary

job

Job

Out

Retrieves the representation of the job.

6.115. Jobs
Copy link

A service to manage jobs.

Expand
Table 6.357. Methods summary
NameSummary

add

Add an external job.

list

Retrieves the representation of the jobs.

6.115.1. add POST
Copy link

Add an external job.

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

POST /ovirt-engine/api/jobs
Copy to Clipboard Toggle word wrap

With the following request body: 

<job>
  <description>Doing some work</description>
  <auto_cleared>true</auto_cleared>
</job>
Copy to Clipboard Toggle word wrap

The response should look like: 

<job href="/ovirt-engine/api/jobs/123" id="123">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
    <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
  </actions>
  <description>Doing some work</description>
  <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
  <auto_cleared>true</auto_cleared>
  <external>true</external>
  <last_updated>2016-12-13T02:15:42.130+02:00</last_updated>
  <start_time>2016-12-13T02:15:42.130+02:00</start_time>
  <status>started</status>
  <owner href="/ovirt-engine/api/users/456" id="456"/>
</job>
Copy to Clipboard Toggle word wrap
Expand
Table 6.358. Parameters summary
NameTypeDirectionSummary

job

Job

In/Out

Job that will be added.

6.115.2. list GET
Copy link

Retrieves the representation of the jobs. 

GET /ovirt-engine/api/jobs
Copy to Clipboard Toggle word wrap

You will receive response in XML like this one: 

<jobs>
  <job href="/ovirt-engine/api/jobs/123" id="123">
    <actions>
      <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/>
      <link href="/ovirt-engine/api/jobs/123/end" rel="end"/>
    </actions>
    <description>Adding Disk</description>
    <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/>
    <auto_cleared>true</auto_cleared>
    <end_time>2016-12-12T23:07:29.758+02:00</end_time>
    <external>false</external>
    <last_updated>2016-12-12T23:07:29.758+02:00</last_updated>
    <start_time>2016-12-12T23:07:26.593+02:00</start_time>
    <status>failed</status>
    <owner href="/ovirt-engine/api/users/456" id="456"/>
  </job>
  ...
</jobs>
Copy to Clipboard Toggle word wrap
Expand
Table 6.359. Parameters summary
NameTypeDirectionSummary

jobs

Job[]

Out

A representation of jobs.

max

Integer

In

Sets the maximum number of jobs to return.

6.115.2.1. max
Copy link

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

6.116. KatelloErrata
Copy link

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

Expand
Table 6.360. Methods summary
NameSummary

list

Retrieves the representation of the Katello errata.

6.116.1. list GET
Copy link

Retrieves the representation of the Katello errata. 

GET /ovirt-engine/api/katelloerrata
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.361. Parameters summary
NameTypeDirectionSummary

errata

KatelloErratum[]

Out

A representation of Katello errata.

max

Integer

In

Sets the maximum number of errata to return.

6.116.1.1. max
Copy link

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

6.117. KatelloErratum
Copy link

A service to manage a Katello erratum.

Expand
Table 6.362. Methods summary
NameSummary

get

Retrieves a Katello erratum.

6.117.1. get GET
Copy link

Retrieves a Katello erratum. 

GET /ovirt-engine/api/katelloerrata/123
Copy to Clipboard Toggle word wrap

You will receive response in XML like this one: 

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

erratum

KatelloErratum

Out

Retrieves the representation of the Katello erratum.

6.118. MacPool
Copy link

Expand
Table 6.364. Methods summary
NameSummary

get

 

remove

Removes a MAC address pool.

update

Updates a MAC address pool.

6.118.1. get GET
Copy link

Expand
Table 6.365. Parameters summary
NameTypeDirectionSummary

pool

MacPool

Out

 

6.118.2. remove DELETE
Copy link

Removes a MAC address pool.

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

DELETE /ovirt-engine/api/macpools/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.366. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.118.3. update PUT
Copy link

Updates a MAC address pool.

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

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

PUT /ovirt-engine/api/macpools/123
Copy to Clipboard Toggle word wrap

With a request body like this: 

<mac_pool>
  <name>UpdatedMACPool</name>
  <description>An updated MAC address pool</description>
  <allow_duplicates>false</allow_duplicates>
  <ranges>
    <range>
      <from>00:1A:4A:16:01:51</from>
      <to>00:1A:4A:16:01:e6</to>
    </range>
    <range>
      <from>02:1A:4A:01:00:00</from>
      <to>02:1A:4A:FF:FF:FF</to>
    </range>
  </ranges>
</mac_pool>
Copy to Clipboard Toggle word wrap
Expand
Table 6.367. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

pool

MacPool

In/Out

 

6.119. MacPools
Copy link

Expand
Table 6.368. Methods summary
NameSummary

add

Creates a new MAC address pool.

list

 

6.119.1. add POST
Copy link

Creates a new MAC address pool.

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

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

POST /ovirt-engine/api/macpools
Copy to Clipboard Toggle word wrap

With a request body like this: 

<mac_pool>
  <name>MACPool</name>
  <description>A MAC address pool</description>
  <allow_duplicates>true</allow_duplicates>
  <default_pool>false</default_pool>
  <ranges>
    <range>
      <from>00:1A:4A:16:01:51</from>
      <to>00:1A:4A:16:01:e6</to>
    </range>
  </ranges>
</mac_pool>
Copy to Clipboard Toggle word wrap
Expand
Table 6.369. Parameters summary
NameTypeDirectionSummary

pool

MacPool

In/Out

 

6.119.2. list GET
Copy link

Expand
Table 6.370. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of pools to return.

pools

MacPool[]

Out

 

6.119.2.1. max
Copy link

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

6.120. Measurable
Copy link

6.121. Moveable
Copy link

Expand
Table 6.371. Methods summary
NameSummary

move

 

6.121.1. move POST
Copy link

Expand
Table 6.372. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the move should be performed asynchronously.

6.122. Network
Copy link

A service managing a network

Expand
Table 6.373. Methods summary
NameSummary

get

Gets a logical network.

remove

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

update

Updates a logical network.

6.122.1. get GET
Copy link

Gets a logical network.

For example: 

GET /ovirt-engine/api/networks/123
Copy to Clipboard Toggle word wrap

Will respond: 

<network href="/ovirt-engine/api/networks/123" id="123">
  <name>ovirtmgmt</name>
  <description>Default Management Network</description>
  <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/>
  <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/>
  <mtu>0</mtu>
  <stp>false</stp>
  <usages>
    <usage>vm</usage>
  </usages>
  <data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
</network>
Copy to Clipboard Toggle word wrap
Expand
Table 6.374. Parameters summary
NameTypeDirectionSummary

network

Network

Out

 

6.122.2. remove DELETE
Copy link

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

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

DELETE /ovirt-engine/api/networks/123
Copy to Clipboard Toggle word wrap

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

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

DELETE /ovirt-engine/api/datacenters/123/networks/456
Copy to Clipboard Toggle word wrap
Expand
Table 6.375. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.122.3. update PUT
Copy link

Updates a logical network.

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

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

PUT /ovirt-engine/api/networks/123
Copy to Clipboard Toggle word wrap

With a request body like this: 

<network>
  <description>My updated description</description>
</network>
Copy to Clipboard Toggle word wrap

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

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

PUT /ovirt-engine/api/datacenters/123/networks/456
Copy to Clipboard Toggle word wrap

With a request body like this: 

<network>
  <mtu>1500</mtu>
</network>
Copy to Clipboard Toggle word wrap
Expand
Table 6.376. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

network

Network

In/Out

 

6.123. NetworkAttachment
Copy link

Expand
Table 6.377. Methods summary
NameSummary

get

 

remove

 

update

 

6.123.1. get GET
Copy link

Expand
Table 6.378. Parameters summary
NameTypeDirectionSummary

attachment

NetworkAttachment

Out

 

6.123.2. remove DELETE
Copy link

Expand
Table 6.379. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.123.3. update PUT
Copy link

Expand
Table 6.380. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

attachment

NetworkAttachment

In/Out

 

6.124. NetworkAttachments
Copy link

Expand
Table 6.381. Methods summary
NameSummary

add

 

list

 

6.124.1. add POST
Copy link

Expand
Table 6.382. Parameters summary
NameTypeDirectionSummary

attachment

NetworkAttachment

In/Out

 

6.124.2. list GET
Copy link

Expand
Table 6.383. Parameters summary
NameTypeDirectionSummary

attachments

NetworkAttachment[]

Out

 

max

Integer

In

Sets the maximum number of attachments to return.

6.124.2.1. max
Copy link

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

6.125. NetworkFilter
Copy link

Manages a network filter. 

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

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

Expand
Table 6.384. Methods summary
NameSummary

get

Retrieves a representation of the network filter.

6.125.1. get GET
Copy link

Retrieves a representation of the network filter.

Expand
Table 6.385. Parameters summary
NameTypeDirectionSummary

network_filter

NetworkFilter

Out

 

6.126. NetworkFilters
Copy link

Represents a readonly network filters sub-collection.

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

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

A network filter is defined for each vnic profile.

A vnic profile is defined for a specific network.

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

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

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

GET http://localhost:8080/ovirt-engine/api/clusters/{cluster:id}/networkfilters
Copy to Clipboard Toggle word wrap

Output: 

<network_filters>
  <network_filter id="00000019-0019-0019-0019-00000000026c">
    <name>example-network-filter-a</name>
    <version>
      <major>4</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
  <network_filter id="00000019-0019-0019-0019-00000000026b">
    <name>example-network-filter-b</name>
    <version>
      <major>4</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
  <network_filter id="00000019-0019-0019-0019-00000000026a">
    <name>example-network-filter-a</name>
    <version>
      <major>3</major>
      <minor>0</minor>
      <build>-1</build>
      <revision>-1</revision>
    </version>
  </network_filter>
</network_filters>
Copy to Clipboard Toggle word wrap
Expand
Table 6.386. Methods summary
NameSummary

list

Retrieves the representations of the network filters.

6.126.1. list GET
Copy link

Retrieves the representations of the network filters.

Expand
Table 6.387. Parameters summary
NameTypeDirectionSummary

filters

NetworkFilter[]

Out

 

6.127. NetworkLabel
Copy link

Expand
Table 6.388. Methods summary
NameSummary

get

 

remove

Removes a label from a logical network.

6.127.1. get GET
Copy link

Expand
Table 6.389. Parameters summary
NameTypeDirectionSummary

label

NetworkLabel

Out

 

6.127.2. remove DELETE
Copy link

Removes a label from a logical network.

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

DELETE /ovirt-engine/api/networks/123/labels/exemplary
Copy to Clipboard Toggle word wrap
Expand
Table 6.390. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.128. NetworkLabels
Copy link

Expand
Table 6.391. Methods summary
NameSummary

add

Attaches label to logical network.

list

 

6.128.1. add POST
Copy link

Attaches label to logical network.

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

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

POST /ovirt-engine/api/networks/123/labels
Copy to Clipboard Toggle word wrap

With a request body like this: 

<label id="mylabel"/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.392. Parameters summary
NameTypeDirectionSummary

label

NetworkLabel

In/Out

 

6.128.2. list GET
Copy link

Expand
Table 6.393. Parameters summary
NameTypeDirectionSummary

labels

NetworkLabel[]

Out

 

max

Integer

In

Sets the maximum number of labels to return.

6.128.2.1. max
Copy link

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

6.129. Networks
Copy link

Manages logical networks.

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

Expand
Table 6.394. Methods summary
NameSummary

add

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

list

List logical networks.

6.129.1. add POST
Copy link

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

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

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

POST /ovirt-engine/api/networks
Copy to Clipboard Toggle word wrap

With a request body like this: 

<network>
  <name>mynetwork</name>
  <data_center id="123"/>
</network>
Copy to Clipboard Toggle word wrap

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

POST /ovirt-engine/api/datacenters/123/networks
Copy to Clipboard Toggle word wrap

With a request body like this: 

<network>
  <name>ovirtmgmt</name>
</network>
Copy to Clipboard Toggle word wrap
Expand
Table 6.395. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

 

6.129.2. list GET
Copy link

List logical networks.

For example: 

GET /ovirt-engine/api/networks
Copy to Clipboard Toggle word wrap

Will respond: 

<networks>
  <network href="/ovirt-engine/api/networks/123" id="123">
    <name>ovirtmgmt</name>
    <description>Default Management Network</description>
    <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/>
    <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/>
    <mtu>0</mtu>
    <stp>false</stp>
    <usages>
      <usage>vm</usage>
    </usages>
    <data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
  </network>
  ...
</networks>
Copy to Clipboard Toggle word wrap
Expand
Table 6.396. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

 

search

String

In

A query string used to restrict the returned networks.

6.129.2.1. case_sensitive
Copy link

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

6.129.2.2. max
Copy link

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

6.130. OpenstackImage
Copy link

Expand
Table 6.397. Methods summary
NameSummary

get

 

import

Imports a virtual machine from a Glance image storage domain.

6.130.1. get GET
Copy link

Expand
Table 6.398. Parameters summary
NameTypeDirectionSummary

image

OpenStackImage

Out

 

6.130.2. import POST
Copy link

Imports a virtual machine from a Glance image storage domain.

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

POST /ovirt-engine/api/openstackimageproviders/123/images/456/import
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action>
  <storage_domain>
    <name>images0</name>
  </storage_domain>
  <cluster>
    <name>images0</name>
  </cluster>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.399. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the import should be performed asynchronously.

cluster

Cluster

In

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

disk

Disk

In

 

import_as_template

Boolean

In

Indicates whether the image should be imported as a template.

storage_domain

StorageDomain

In

 

template

Template

In

 

6.131. OpenstackImageProvider
Copy link

Expand
Table 6.400. Methods summary
NameSummary

get

 

importcertificates

 

remove

 

testconnectivity

 

update

 

6.131.1. get GET
Copy link

Expand
Table 6.401. Parameters summary
NameTypeDirectionSummary

provider

OpenStackImageProvider

Out

 

6.131.2. importcertificates POST
Copy link

Expand
Table 6.402. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.131.3. remove DELETE
Copy link

Expand
Table 6.403. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.131.4. testconnectivity POST
Copy link

Expand
Table 6.404. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.131.5. update PUT
Copy link

Expand
Table 6.405. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackImageProvider

In/Out

 

6.132. OpenstackImageProviders
Copy link

Expand
Table 6.406. Methods summary
NameSummary

add

 

list

 

6.132.1. add POST
Copy link

Expand
Table 6.407. Parameters summary
NameTypeDirectionSummary

provider

OpenStackImageProvider

In/Out

 

6.132.2. list GET
Copy link

Expand
Table 6.408. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

OpenStackImageProvider[]

Out

 

6.132.2.1. max
Copy link

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

6.133. OpenstackImages
Copy link

Expand
Table 6.409. Methods summary
NameSummary

list

Lists the images of a Glance image storage domain.

6.133.1. list GET
Copy link

Lists the images of a Glance image storage domain.

Expand
Table 6.410. Parameters summary
NameTypeDirectionSummary

images

OpenStackImage[]

Out

 

max

Integer

In

Sets the maximum number of images to return.

6.133.1.1. max
Copy link

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

6.134. OpenstackNetwork
Copy link

Expand
Table 6.411. Methods summary
NameSummary

get

 

import

This operation imports an external network into oVirt.

6.134.1. get GET
Copy link

Expand
Table 6.412. Parameters summary
NameTypeDirectionSummary

network

OpenStackNetwork

Out

 

6.134.2. import POST
Copy link

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

Expand
Table 6.413. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the import should be performed asynchronously.

data_center

DataCenter

In

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

6.134.2.1. data_center
Copy link

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

6.135. OpenstackNetworkProvider
Copy link

This service manages OpenStack network provider.

Expand
Table 6.414. Methods summary
NameSummary

get

Returns the representation of the object managed by this service.

importcertificates

 

remove

Removes the provider.

testconnectivity

 

update

Updates the provider.

6.135.1. get GET
Copy link

Returns the representation of the object managed by this service.

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

GET /ovirt-engine/api/openstacknetworkproviders/1234
Copy to Clipboard Toggle word wrap
Expand
Table 6.415. Parameters summary
NameTypeDirectionSummary

provider

OpenStackNetworkProvider

Out

 

6.135.2. importcertificates POST
Copy link

Expand
Table 6.416. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.135.3. remove DELETE
Copy link

Removes the provider.

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

DELETE /ovirt-engine/api/openstacknetworkproviders/1234
Copy to Clipboard Toggle word wrap
Expand
Table 6.417. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.135.4. testconnectivity POST
Copy link

Expand
Table 6.418. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.135.5. update PUT
Copy link

Updates the provider.

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

PUT /ovirt-engine/api/openstacknetworkproviders/1234
Copy to Clipboard Toggle word wrap

With a request body like this: 

<openstack_network_provider>
  <name>ovn-network-provider</name>
  <requires_authentication>false</requires_authentication>
  <url>http://some_server_url.domain.com:9696</url>
  <tenant_name>oVirt</tenant_name>
  <type>external</type>
</openstack_network_provider>
Copy to Clipboard Toggle word wrap
Expand
Table 6.419. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackNetworkProvider

In/Out

The provider to update.

6.136. OpenstackNetworkProviders
Copy link

This service manages OpenStack network providers.

Expand
Table 6.420. Methods summary
NameSummary

add

The operation adds a new network provider to the system.

list

 

6.136.1. add POST
Copy link

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

Expand
Table 6.421. Parameters summary
NameTypeDirectionSummary

provider

OpenStackNetworkProvider

In/Out

 

6.136.2. list GET
Copy link

Expand
Table 6.422. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

OpenStackNetworkProvider[]

Out

 

6.136.2.1. max
Copy link

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

6.137. OpenstackNetworks
Copy link

Expand
Table 6.423. Methods summary
NameSummary

list

 

6.137.1. list GET
Copy link

Expand
Table 6.424. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

OpenStackNetwork[]

Out

 

6.137.1.1. max
Copy link

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

6.138. OpenstackSubnet
Copy link

Expand
Table 6.425. Methods summary
NameSummary

get

 

remove

 

6.138.1. get GET
Copy link

Expand
Table 6.426. Parameters summary
NameTypeDirectionSummary

subnet

OpenStackSubnet

Out

 

6.138.2. remove DELETE
Copy link

Expand
Table 6.427. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.139. OpenstackSubnets
Copy link

Expand
Table 6.428. Methods summary
NameSummary

add

 

list

 

6.139.1. add POST
Copy link

Expand
Table 6.429. Parameters summary
NameTypeDirectionSummary

subnet

OpenStackSubnet

In/Out

 

6.139.2. list GET
Copy link

Expand
Table 6.430. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of sub-networks to return.

subnets

OpenStackSubnet[]

Out

 

6.139.2.1. max
Copy link

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

6.140. OpenstackVolumeAuthenticationKey
Copy link

Expand
Table 6.431. Methods summary
NameSummary

get

 

remove

 

update

 

6.140.1. get GET
Copy link

Expand
Table 6.432. Parameters summary
NameTypeDirectionSummary

key

OpenstackVolumeAuthenticationKey

Out

 

6.140.2. remove DELETE
Copy link

Expand
Table 6.433. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.140.3. update PUT
Copy link

Expand
Table 6.434. Parameters summary
NameTypeDirectionSummary

key

OpenstackVolumeAuthenticationKey

In/Out

 

6.141. OpenstackVolumeAuthenticationKeys
Copy link

Expand
Table 6.435. Methods summary
NameSummary

add

 

list

 

6.141.1. add POST
Copy link

Expand
Table 6.436. Parameters summary
NameTypeDirectionSummary

key

OpenstackVolumeAuthenticationKey

In/Out

 

6.141.2. list GET
Copy link

Expand
Table 6.437. Parameters summary
NameTypeDirectionSummary

keys

OpenstackVolumeAuthenticationKey[]

Out

 

max

Integer

In

Sets the maximum number of keys to return.

6.141.2.1. max
Copy link

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

6.142. OpenstackVolumeProvider
Copy link

Expand
Table 6.438. Methods summary
NameSummary

get

 

importcertificates

 

remove

 

testconnectivity

 

update

 

6.142.1. get GET
Copy link

Expand
Table 6.439. Parameters summary
NameTypeDirectionSummary

provider

OpenStackVolumeProvider

Out

 

6.142.2. importcertificates POST
Copy link

Expand
Table 6.440. Parameters summary
NameTypeDirectionSummary

certificates

Certificate[]

In

 

6.142.3. remove DELETE
Copy link

Expand
Table 6.441. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.142.4. testconnectivity POST
Copy link

Expand
Table 6.442. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the test should be performed asynchronously.

6.142.5. update PUT
Copy link

Expand
Table 6.443. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

provider

OpenStackVolumeProvider

In/Out

 

6.143. OpenstackVolumeProviders
Copy link

Expand
Table 6.444. Methods summary
NameSummary

add

Adds a new volume provider.

list

Retrieves the list of volume providers.

6.143.1. add POST
Copy link

Adds a new volume provider.

For example: 

POST /ovirt-engine/api/openstackvolumeproviders
Copy to Clipboard Toggle word wrap

With a request body like this: 

<openstack_volume_provider>
  <name>mycinder</name>
  <url>https://mycinder.example.com:8776</url>
  <data_center>
    <name>mydc</name>
  </data_center>
  <requires_authentication>true</requires_authentication>
  <username>admin</username>
  <password>mypassword</password>
  <tenant_name>mytenant</tenant_name>
</openstack_volume_provider>
Copy to Clipboard Toggle word wrap
Expand
Table 6.445. Parameters summary
NameTypeDirectionSummary

provider

OpenStackVolumeProvider

In/Out

 

6.143.2. list GET
Copy link

Retrieves the list of volume providers.

Expand
Table 6.446. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of providers to return.

providers

OpenStackVolumeProvider[]

Out

 

6.143.2.1. max
Copy link

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

6.144. OpenstackVolumeType
Copy link

Expand
Table 6.447. Methods summary
NameSummary

get

 

6.144.1. get GET
Copy link

Expand
Table 6.448. Parameters summary
NameTypeDirectionSummary

type

OpenStackVolumeType

Out

 

6.145. OpenstackVolumeTypes
Copy link

Expand
Table 6.449. Methods summary
NameSummary

list

 

6.145.1. list GET
Copy link

Expand
Table 6.450. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of volume types to return.

types

OpenStackVolumeType[]

Out

 

6.145.1.1. max
Copy link

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

6.146. OperatingSystem
Copy link

Expand
Table 6.451. Methods summary
NameSummary

get

 

6.146.1. get GET
Copy link

Expand
Table 6.452. Parameters summary
NameTypeDirectionSummary

operating_system

OperatingSystemInfo

Out

 

6.147. OperatingSystems
Copy link

Expand
Table 6.453. Methods summary
NameSummary

list

 

6.147.1. list GET
Copy link

Expand
Table 6.454. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

operating_system

OperatingSystemInfo[]

Out

 

6.147.1.1. max
Copy link

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

6.148. Permission
Copy link

Expand
Table 6.455. Methods summary
NameSummary

get

 

remove

 

6.148.1. get GET
Copy link

Expand
Table 6.456. Parameters summary
NameTypeDirectionSummary

permission

Permission

Out

 

6.148.2. remove DELETE
Copy link

Expand
Table 6.457. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.149. Permit
Copy link

A service to manage a specific permit of the role.

Expand
Table 6.458. Methods summary
NameSummary

get

Gets the information about the permit of the role.

remove

Removes the permit from the role.

6.149.1. get GET
Copy link

Gets the information about the permit of the role.

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

GET /ovirt-engine/api/roles/123/permits/456
Copy to Clipboard Toggle word wrap 
<permit href="/ovirt-engine/api/roles/123/permits/456" id="456">
  <name>change_vm_cd</name>
  <administrative>false</administrative>
  <role href="/ovirt-engine/api/roles/123" id="123"/>
</permit>
Copy to Clipboard Toggle word wrap
Expand
Table 6.459. Parameters summary
NameTypeDirectionSummary

permit

Permit

Out

The permit of the role.

6.149.2. remove DELETE
Copy link

Removes the permit from the role.

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

DELETE /ovirt-engine/api/roles/123/permits/456
Copy to Clipboard Toggle word wrap
Expand
Table 6.460. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.150. Permits
Copy link

Represents a permits sub-collection of the specific role.

Expand
Table 6.461. Methods summary
NameSummary

add

Adds a permit to the role.

list

List the permits of the role.

6.150.1. add POST
Copy link

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

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

POST /ovirt-engine/api/roles/123/permits
Copy to Clipboard Toggle word wrap

With a request body like this: 

<permit>
  <name>create_vm</name>
</permit>
Copy to Clipboard Toggle word wrap
Expand
Table 6.462. Parameters summary
NameTypeDirectionSummary

permit

Permit

In/Out

The permit to add.

6.150.2. list GET
Copy link

List the permits of the role.

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

GET /ovirt-engine/api/roles/123/permits
Copy to Clipboard Toggle word wrap 
<permits>
  <permit href="/ovirt-engine/api/roles/123/permits/5" id="5">
    <name>change_vm_cd</name>
    <administrative>false</administrative>
    <role href="/ovirt-engine/api/roles/123" id="123"/>
  </permit>
  <permit href="/ovirt-engine/api/roles/123/permits/7" id="7">
    <name>connect_to_vm</name>
    <administrative>false</administrative>
    <role href="/ovirt-engine/api/roles/123" id="123"/>
  </permit>
</permits>
Copy to Clipboard Toggle word wrap
Expand
Table 6.463. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of permits to return.

permits

Permit[]

Out

List of permits.

6.150.2.1. max
Copy link

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

6.151. Qos
Copy link

Expand
Table 6.464. Methods summary
NameSummary

get

 

remove

 

update

 

6.151.1. get GET
Copy link

Expand
Table 6.465. Parameters summary
NameTypeDirectionSummary

qos

Qos

Out

 

6.151.2. remove DELETE
Copy link

Expand
Table 6.466. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.151.3. update PUT
Copy link

Expand
Table 6.467. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

qos

Qos

In/Out

 

6.152. Qoss
Copy link

Expand
Table 6.468. Methods summary
NameSummary

add

 

list

 

6.152.1. add POST
Copy link

Expand
Table 6.469. Parameters summary
NameTypeDirectionSummary

qos

Qos

In/Out

 

6.152.2. list GET
Copy link

Expand
Table 6.470. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of QoS descriptors to return.

qoss

Qos[]

Out

 

6.152.2.1. max
Copy link

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

6.153. Quota
Copy link

Expand
Table 6.471. Methods summary
NameSummary

get

Retrieves a quota.

remove

Delete a quota.

update

Updates a quota.

6.153.1. get GET
Copy link

Retrieves a quota.

An example of retrieving a quota: 

GET /ovirt-engine/api/datacenters/123/quotas/456
Copy to Clipboard Toggle word wrap 
<quota id="456">
  <name>myquota</name>
  <description>My new quota for virtual machines</description>
  <cluster_hard_limit_pct>20</cluster_hard_limit_pct>
  <cluster_soft_limit_pct>80</cluster_soft_limit_pct>
  <storage_hard_limit_pct>20</storage_hard_limit_pct>
  <storage_soft_limit_pct>80</storage_soft_limit_pct>
</quota>
Copy to Clipboard Toggle word wrap
Expand
Table 6.472. Parameters summary
NameTypeDirectionSummary

quota

Quota

Out

 

6.153.2. remove DELETE
Copy link

Delete a quota.

An example of deleting a quota: 

DELETE /ovirt-engine/api/datacenters/123-456/quotas/654-321
-0472718ab224 HTTP/1.1
Accept: application/xml
Content-type: application/xml
Copy to Clipboard Toggle word wrap
Expand
Table 6.473. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.153.3. update PUT
Copy link

Updates a quota.

An example of updating a quota: 

PUT /ovirt-engine/api/datacenters/123/quotas/456
Copy to Clipboard Toggle word wrap 
<quota>
  <cluster_hard_limit_pct>30</cluster_hard_limit_pct>
  <cluster_soft_limit_pct>70</cluster_soft_limit_pct>
  <storage_hard_limit_pct>20</storage_hard_limit_pct>
  <storage_soft_limit_pct>80</storage_soft_limit_pct>
</quota>
Copy to Clipboard Toggle word wrap
Expand
Table 6.474. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

quota

Quota

In/Out

 

6.154. QuotaClusterLimit
Copy link

Expand
Table 6.475. Methods summary
NameSummary

get

 

remove

 

6.154.1. get GET
Copy link

Expand
Table 6.476. Parameters summary
NameTypeDirectionSummary

limit

QuotaClusterLimit

Out

 

6.154.2. remove DELETE
Copy link

Expand
Table 6.477. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.155. QuotaClusterLimits
Copy link

Expand
Table 6.478. Methods summary
NameSummary

add

 

list

 

6.155.1. add POST
Copy link

Expand
Table 6.479. Parameters summary
NameTypeDirectionSummary

limit

QuotaClusterLimit

In/Out

 

6.155.2. list GET
Copy link

Expand
Table 6.480. Parameters summary
NameTypeDirectionSummary

limits

QuotaClusterLimit[]

Out

 

max

Integer

In

Sets the maximum number of limits to return.

6.155.2.1. max
Copy link

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

6.156. QuotaStorageLimit
Copy link

Expand
Table 6.481. Methods summary
NameSummary

get

 

remove

 

6.156.1. get GET
Copy link

Expand
Table 6.482. Parameters summary
NameTypeDirectionSummary

limit

QuotaStorageLimit

Out

 

6.156.2. remove DELETE
Copy link

Expand
Table 6.483. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

6.157. QuotaStorageLimits
Copy link

Expand
Table 6.484. Methods summary
NameSummary

add

 

list

 

6.157.1. add POST
Copy link

Expand
Table 6.485. Parameters summary
NameTypeDirectionSummary

limit

QuotaStorageLimit

In/Out

 

6.157.2. list GET
Copy link

Expand
Table 6.486. Parameters summary
NameTypeDirectionSummary

limits

QuotaStorageLimit[]

Out

 

max

Integer

In

Sets the maximum number of limits to return.

6.157.2.1. max
Copy link

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

6.158. Quotas
Copy link

Expand
Table 6.487. Methods summary
NameSummary

add

Creates a new quota.

list

Lists quotas of a data center

6.158.1. add POST
Copy link

Creates a new quota.

An example of creating a new quota: 

POST /ovirt-engine/api/datacenters/123/quotas
Copy to Clipboard Toggle word wrap 
<quota>
  <name>myquota</name>
  <description>My new quota for virtual machines</description>
</quota>
Copy to Clipboard Toggle word wrap
Expand
Table 6.488. Parameters summary
NameTypeDirectionSummary

quota

Quota

In/Out

 

6.158.2. list GET
Copy link

Lists quotas of a data center

Expand
Table 6.489. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of quota descriptors to return.

quotas

Quota[]

Out

 

6.158.2.1. max
Copy link

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

6.159. Role
Copy link

Expand
Table 6.490. Methods summary
NameSummary

get

Get the role.

remove

Removes the role.

update

Updates a role.

6.159.1. get GET
Copy link

Get the role. 

GET /ovirt-engine/api/roles/123
Copy to Clipboard Toggle word wrap

You will receive XML response like this one: 

<role id="123">
  <name>MyRole</name>
  <description>MyRole description</description>
  <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/>
  <administrative>true</administrative>
  <mutable>false</mutable>
</role>
Copy to Clipboard Toggle word wrap
Expand
Table 6.491. Parameters summary
NameTypeDirectionSummary

role

Role

Out

Retrieved role.

6.159.2. remove DELETE
Copy link

Removes the role.

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

DELETE /ovirt-engine/api/roles/{role_id}
Copy to Clipboard Toggle word wrap
Expand
Table 6.492. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.159.3. update PUT
Copy link

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

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

PUT /ovirt-engine/api/roles/123
Copy to Clipboard Toggle word wrap

With a request body like this: 

<role>
  <name>MyNewRoleName</name>
  <description>My new description of the role</description>
  <administrative>true</administrative>
</group>
Copy to Clipboard Toggle word wrap
Expand
Table 6.493. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

role

Role

In/Out

Updated role.

6.160. Roles
Copy link

Provides read-only access to the global set of roles

Expand
Table 6.494. Methods summary
NameSummary

add

Create a new role.

list

List roles.

6.160.1. add POST
Copy link

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

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

POST /ovirt-engine/api/roles
Copy to Clipboard Toggle word wrap

With a request body like this: 

<role>
  <name>MyRole</name>
  <description>My custom role to create virtual machines</description>
  <administrative>false</administrative>
  <permits>
    <permit id="1"/>
    <permit id="1300"/>
  </permits>
</group>
Copy to Clipboard Toggle word wrap
Expand
Table 6.495. Parameters summary
NameTypeDirectionSummary

role

Role

In/Out

Role that will be added.

6.160.2. list GET
Copy link

List roles. 

GET /ovirt-engine/api/roles
Copy to Clipboard Toggle word wrap

You will receive response in XML like this one: 

<roles>
  <role id="123">
     <name>SuperUser</name>
     <description>Roles management administrator</description>
     <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/>
     <administrative>true</administrative>
     <mutable>false</mutable>
  </role>
  ...
</roles>
Copy to Clipboard Toggle word wrap
Expand
Table 6.496. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of roles to return.

roles

Role[]

Out

Retrieved list of roles.

6.160.2.1. max
Copy link

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

6.161. SchedulingPolicies
Copy link

Expand
Table 6.497. Methods summary
NameSummary

add

 

list

 

6.161.1. add POST
Copy link

Expand
Table 6.498. Parameters summary
NameTypeDirectionSummary

policy

SchedulingPolicy

In/Out

 

6.161.2. list GET
Copy link

Expand
Table 6.499. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of policies to return.

policies

SchedulingPolicy[]

Out

 

6.161.2.1. max
Copy link

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

6.162. SchedulingPolicy
Copy link

Expand
Table 6.500. Methods summary
NameSummary

get

 

remove

 

update

 

6.162.1. get GET
Copy link

Expand
Table 6.501. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

policy

SchedulingPolicy

Out

 

6.162.2. remove DELETE
Copy link

Expand
Table 6.502. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.162.3. update PUT
Copy link

Expand
Table 6.503. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

policy

SchedulingPolicy

In/Out

 

6.163. SchedulingPolicyUnit
Copy link

Expand
Table 6.504. Methods summary
NameSummary

get

 

remove

 

6.163.1. get GET
Copy link

Expand
Table 6.505. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

unit

SchedulingPolicyUnit

Out

 

6.163.2. remove DELETE
Copy link

Expand
Table 6.506. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.164. SchedulingPolicyUnits
Copy link

Expand
Table 6.507. Methods summary
NameSummary

list

 

6.164.1. list GET
Copy link

Expand
Table 6.508. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of policy units to return.

units

SchedulingPolicyUnit[]

Out

 

6.164.1.1. max
Copy link

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

6.165. Snapshot
Copy link

Expand
Table 6.509. Methods summary
NameSummary

get

 

remove

 

restore

Restores a virtual machine snapshot.

6.165.1. get GET
Copy link

Expand
Table 6.510. Parameters summary
NameTypeDirectionSummary

snapshot

Snapshot

Out

 

6.165.2. remove DELETE
Copy link

Expand
Table 6.511. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.165.3. restore POST
Copy link

Restores a virtual machine snapshot.

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

POST /ovirt-engine/api/vms/123/snapshots/456/restore
Copy to Clipboard Toggle word wrap

With an empty action in the body: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.512. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the restore should be performed asynchronously.

disks

Disk[]

In

 

restore_memory

Boolean

In

 

6.166. SnapshotCdrom
Copy link

Expand
Table 6.513. Methods summary
NameSummary

get

 

6.166.1. get GET
Copy link

Expand
Table 6.514. Parameters summary
NameTypeDirectionSummary

cdrom

Cdrom

Out

 

6.167. SnapshotCdroms
Copy link

Expand
Table 6.515. Methods summary
NameSummary

list

 

6.167.1. list GET
Copy link

Expand
Table 6.516. Parameters summary
NameTypeDirectionSummary

cdroms

Cdrom[]

Out

 

max

Integer

In

Sets the maximum number of CDROMS to return.

6.167.1.1. max
Copy link

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

6.168. SnapshotDisk
Copy link

Expand
Table 6.517. Methods summary
NameSummary

get

 

6.168.1. get GET
Copy link

Expand
Table 6.518. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.169. SnapshotDisks
Copy link

Expand
Table 6.519. Methods summary
NameSummary

list

 

6.169.1. list GET
Copy link

Expand
Table 6.520. Parameters summary
NameTypeDirectionSummary

disks

Disk[]

Out

 

max

Integer

In

Sets the maximum number of disks to return.

6.169.1.1. max
Copy link

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

6.170. SnapshotNic
Copy link

Expand
Table 6.521. Methods summary
NameSummary

get

 

6.170.1. get GET
Copy link

Expand
Table 6.522. Parameters summary
NameTypeDirectionSummary

nic

Nic

Out

 

6.171. SnapshotNics
Copy link

Expand
Table 6.523. Methods summary
NameSummary

list

 

6.171.1. list GET
Copy link

Expand
Table 6.524. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

 

6.171.1.1. max
Copy link

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

6.172. Snapshots
Copy link

Expand
Table 6.525. Methods summary
NameSummary

add

Creates a virtual machine snapshot.

list

 

6.172.1. add POST
Copy link

Creates a virtual machine snapshot.

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

POST /ovirt-engine/api/vms/123/snapshots
Copy to Clipboard Toggle word wrap

With a request body like this: 

<snapshot>
  <description>My snapshot</description>
</snapshot>
Copy to Clipboard Toggle word wrap
Important

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

<snapshot>
  <description>My snapshot</description>
  <persist_memorystate>false</persist_memorystate>
</snapshot>
Copy to Clipboard Toggle word wrap
Expand
Table 6.526. Parameters summary
NameTypeDirectionSummary

snapshot

Snapshot

In/Out

 

6.172.2. list GET
Copy link

Expand
Table 6.527. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of snapshots to return.

snapshots

Snapshot[]

Out

 

6.172.2.1. max
Copy link

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

6.173. SshPublicKey
Copy link

Expand
Table 6.528. Methods summary
NameSummary

get

 

remove

 

update

 

6.173.1. get GET
Copy link

Expand
Table 6.529. Parameters summary
NameTypeDirectionSummary

key

SshPublicKey

Out

 

6.173.2. remove DELETE
Copy link

Expand
Table 6.530. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.173.3. update PUT
Copy link

Expand
Table 6.531. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

key

SshPublicKey

In/Out

 

6.174. SshPublicKeys
Copy link

Expand
Table 6.532. Methods summary
NameSummary

add

 

list

 

6.174.1. add POST
Copy link

Expand
Table 6.533. Parameters summary
NameTypeDirectionSummary

key

SshPublicKey

In/Out

 

6.174.2. list GET
Copy link

Expand
Table 6.534. Parameters summary
NameTypeDirectionSummary

keys

SshPublicKey[]

Out

 

max

Integer

In

Sets the maximum number of keys to return.

6.174.2.1. max
Copy link

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

6.175. Statistic
Copy link

Expand
Table 6.535. Methods summary
NameSummary

get

 

6.175.1. get GET
Copy link

Expand
Table 6.536. Parameters summary
NameTypeDirectionSummary

statistic

Statistic

Out

 

6.176. Statistics
Copy link

Expand
Table 6.537. Methods summary
NameSummary

list

Retrieves a list of statistics.

6.176.1. list GET
Copy link

Retrieves a list of statistics.

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

GET /ovirt-engine/api/vms/123/statistics
Copy to Clipboard Toggle word wrap

The result will be like this: 

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

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

GET /ovirt-engine/api/vms/123/statistics/456
Copy to Clipboard Toggle word wrap

Outputs: 

<statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456">
  <name>memory.installed</name>
  <description>Total memory configured</description>
  <kind>gauge</kind>
  <type>integer</type>
  <unit>bytes</unit>
  <values>
    <value>
      <datum>1073741824</datum>
    </value>
  </values>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</statistic>
Copy to Clipboard Toggle word wrap
Expand
Table 6.538. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of statistics to return.

statistics

Statistic[]

Out

 

6.176.1.1. max
Copy link

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

6.177. Step
Copy link

A service to manage a step.

Expand
Table 6.539. Methods summary
NameSummary

end

Marks an external step execution as ended.

get

Retrieves a step.

6.177.1. end POST
Copy link

Marks an external step execution as ended.

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

POST /ovirt-engine/api/jobs/123/steps/456/end
Copy to Clipboard Toggle word wrap

With the following request body: 

<action>
  <force>true</force>
  <succeeded>true</succeeded>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.540. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

force

Boolean

In

Indicates if the step should be forcibly terminated.

succeeded

Boolean

In

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

6.177.1.1. succeeded
Copy link

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

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

6.177.2. get GET
Copy link

Retrieves a step. 

GET /ovirt-engine/api/jobs/123/steps/456
Copy to Clipboard Toggle word wrap

You will receive response in XML like this one: 

<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
  </actions>
  <description>Validating</description>
  <end_time>2016-12-12T23:07:26.627+02:00</end_time>
  <external>false</external>
  <number>0</number>
  <start_time>2016-12-12T23:07:26.605+02:00</start_time>
  <status>finished</status>
  <type>validating</type>
  <job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>
Copy to Clipboard Toggle word wrap
Expand
Table 6.541. Parameters summary
NameTypeDirectionSummary

step

Step

Out

Retrieves the representation of the step.

6.178. Steps
Copy link

A service to manage steps.

Expand
Table 6.542. Methods summary
NameSummary

add

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

list

Retrieves the representation of the steps.

6.178.1. add POST
Copy link

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

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

POST /ovirt-engine/api/jobs/123/steps
Copy to Clipboard Toggle word wrap

With the following request body: 

<step>
  <description>Validating</description>
  <start_time>2016-12-12T23:07:26.605+02:00</start_time>
  <status>started</status>
  <type>validating</type>
</step>
Copy to Clipboard Toggle word wrap

The response should look like: 

<step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
  <actions>
    <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
  </actions>
  <description>Validating</description>
  <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/>
  <external>true</external>
  <number>2</number>
  <start_time>2016-12-13T01:06:15.380+02:00</start_time>
  <status>started</status>
  <type>validating</type>
  <job href="/ovirt-engine/api/jobs/123" id="123"/>
</step>
Copy to Clipboard Toggle word wrap
Expand
Table 6.543. Parameters summary
NameTypeDirectionSummary

step

Step

In/Out

Step that will be added.

6.178.2. list GET
Copy link

Retrieves the representation of the steps. 

GET /ovirt-engine/api/job/123/steps
Copy to Clipboard Toggle word wrap

You will receive response in XML like this one: 

<steps>
  <step href="/ovirt-engine/api/jobs/123/steps/456" id="456">
    <actions>
      <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/>
    </actions>
    <description>Validating</description>
    <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/>
    <external>true</external>
    <number>2</number>
    <start_time>2016-12-13T01:06:15.380+02:00</start_time>
    <status>started</status>
    <type>validating</type>
    <job href="/ovirt-engine/api/jobs/123" id="123"/>
  </step>
  ...
</steps>
Copy to Clipboard Toggle word wrap
Expand
Table 6.544. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of steps to return.

steps

Step[]

Out

A representation of steps.

6.178.2.1. max
Copy link

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

6.179. Storage
Copy link

Expand
Table 6.545. Methods summary
NameSummary

get

 

6.179.1. get GET
Copy link

Expand
Table 6.546. Parameters summary
NameTypeDirectionSummary

report_status

Boolean

In

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

storage

HostStorage

Out

 

6.179.1.1. report_status
Copy link

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

The default is true for backward compatibility.

Here an example with the LUN status : 

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

Here an example without the LUN status : 

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

6.180. StorageDomain
Copy link

Expand
Table 6.547. Methods summary
NameSummary

get

 

isattached

 

reduceluns

This operation reduces logical units from the storage domain.

refreshluns

This operation refreshes the LUN size.

remove

Removes the storage domain.

update

Updates a storage domain.

updateovfstore

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

6.180.1. get GET
Copy link

Expand
Table 6.548. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

storage_domain

StorageDomain

Out

 

6.180.2. isattached POST
Copy link

Expand
Table 6.549. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

host

Host

In

 

is_attached

Boolean

Out

 

6.180.3. reduceluns POST
Copy link

This operation reduces logical units from the storage domain.

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

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

POST /ovirt-engine/api/storagedomains/123/reduceluns
Copy to Clipboard Toggle word wrap

With a request body like this: 

 <action>
   <logical_units>
     <logical_unit id="1IET_00010001"/>
     <logical_unit id="1IET_00010002"/>
   </logical_units>
 </action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.550. Parameters summary
NameTypeDirectionSummary

logical_units

LogicalUnit[]

In

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

6.180.4. refreshluns POST
Copy link

This operation refreshes the LUN size.

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

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

POST /ovirt-engine/api/storagedomains/262b056b-aede-40f1-9666-b883eff59d40/refreshluns
Copy to Clipboard Toggle word wrap

With a request body like this: 

 <action>
   <logical_units>
     <logical_unit id="1IET_00010001"/>
     <logical_unit id="1IET_00010002"/>
   </logical_units>
 </action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.551. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the refresh should be performed asynchronously.

logical_units

LogicalUnit[]

In

The LUNs that need to be refreshed.

6.180.5. remove DELETE
Copy link

Removes the storage domain.

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

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

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

Expand
Table 6.552. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

destroy

Boolean

In

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

format

Boolean

In

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

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

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

host

String

In

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

6.180.5.1. destroy
Copy link

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

DELETE /ovirt-engine/api/storagedomains/123?destroy=true
Copy to Clipboard Toggle word wrap

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

6.180.5.2. host
Copy link

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

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

DELETE /ovirt-engine/api/storagedomains/123?host=myhost
Copy to Clipboard Toggle word wrap

6.180.6. update PUT
Copy link

Updates a storage domain.

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

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

PUT /ovirt-engine/api/storagedomains/123
Copy to Clipboard Toggle word wrap

With a request body as follows: 

<storage_domain>
  <name>data2</name>
  <wipe_after_delete>true</wipe_after_delete>
</storage_domain>
Copy to Clipboard Toggle word wrap
Expand
Table 6.553. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

storage_domain

StorageDomain

In/Out

 

6.180.7. updateovfstore POST
Copy link

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

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

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

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

Expand
Table 6.554. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the OVF_STORE update should be performed asynchronously.

6.181. StorageDomainContentDisk
Copy link

Expand
Table 6.555. Methods summary
NameSummary

get

 

6.181.1. get GET
Copy link

Expand
Table 6.556. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

filter

Boolean

In

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

6.182. StorageDomainContentDisks
Copy link

Expand
Table 6.557. Methods summary
NameSummary

list

 

6.182.1. list GET
Copy link

Expand
Table 6.558. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

disks

Disk[]

Out

 

max

Integer

In

Sets the maximum number of disks to return.

search

String

In

A query string used to restrict the returned disks.

6.182.1.1. case_sensitive
Copy link

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

6.182.1.2. max
Copy link

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

6.183. StorageDomainServerConnection
Copy link

Expand
Table 6.559. Methods summary
NameSummary

get

 

remove

Detaches a storage connection from storage.

6.183.1. get GET
Copy link

Expand
Table 6.560. Parameters summary
NameTypeDirectionSummary

connection

StorageConnection

Out

 

6.183.2. remove DELETE
Copy link

Detaches a storage connection from storage.

Expand
Table 6.561. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.184. StorageDomainServerConnections
Copy link

Expand
Table 6.562. Methods summary
NameSummary

add

 

list

 

6.184.1. add POST
Copy link

Expand
Table 6.563. Parameters summary
NameTypeDirectionSummary

connection

StorageConnection

In/Out

 

6.184.2. list GET
Copy link

Expand
Table 6.564. Parameters summary
NameTypeDirectionSummary

connections

StorageConnection[]

Out

 

max

Integer

In

Sets the maximum number of connections to return.

6.184.2.1. max
Copy link

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

6.185. StorageDomainTemplate
Copy link

Expand
Table 6.565. Methods summary
NameSummary

get

 

import

Action to import a template from an export storage domain.

register

 

remove

 

6.185.1. get GET
Copy link

Expand
Table 6.566. Parameters summary
NameTypeDirectionSummary

template

Template

Out

 

6.185.2. import POST
Copy link

Action to import a template from an export storage domain.

For example, to import the template 456 from the storage domain 123 send the following request: 

POST /ovirt-engine/api/storagedomains/123/templates/456/import
Copy to Clipboard Toggle word wrap

With the following request body: 

<action>
  <storage_domain>
    <name>myexport</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.567. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the import should be performed asynchronously.

clone

Boolean

In

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

cluster

Cluster

In

 

exclusive

Boolean

In

 

storage_domain

StorageDomain

In

 

template

Template

In

 

vm

Vm

In

 

6.185.2.1. clone
Copy link

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

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

6.185.3. register POST
Copy link

Expand
Table 6.568. Parameters summary
NameTypeDirectionSummary

allow_partial_import

Boolean

In

Indicates whether a template is allowed to be registered with only some of its disks.

async

Boolean

In

Indicates if the registration should be performed asynchronously.

clone

Boolean

In

 

cluster

Cluster

In

 

exclusive

Boolean

In

 

template

Template

In

 

6.185.3.1. allow_partial_import
Copy link

Indicates whether a template is allowed to be registered with only some of its disks.

If this flag is true, the engine will not fail in the validation process if an image is not found, but instead it will allow the template to be registered without the missing disks. This is mainly used during registration of a template when some of the storage domains are not available. The default value is false.

6.185.4. remove DELETE
Copy link

Expand
Table 6.569. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.186. StorageDomainTemplates
Copy link

Expand
Table 6.570. Methods summary
NameSummary

list

 

6.186.1. list GET
Copy link

Expand
Table 6.571. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of templates to return.

templates

Template[]

Out

 

unregistered

Boolean

In

Indicates whether to retrieve a list of registered or unregistered templates which contain disks on the storage domain.

6.186.1.1. max
Copy link

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

6.186.1.2. unregistered
Copy link

Indicates whether to retrieve a list of registered or unregistered templates which contain disks on the storage domain. To get a list of unregistered templates the call should indicate the unregistered flag. For example, to get a list of unregistered templates the REST API call should look like this: 

GET /ovirt-engine/api/storagedomains/123/templates?unregistered=true
Copy to Clipboard Toggle word wrap

The default value of the unregisterd flag is false. The request only apply to storage domains that are attached.

6.187. StorageDomainVm
Copy link

Expand
Table 6.572. Methods summary
NameSummary

get

 

import

Imports a virtual machine from an export storage domain.

register

 

remove

Deletes a virtual machine from an export storage domain.

6.187.1. get GET
Copy link

Expand
Table 6.573. Parameters summary
NameTypeDirectionSummary

vm

Vm

Out

 

6.187.2. import POST
Copy link

Imports a virtual machine from an export storage domain.

For example, send a request like this: 

POST /ovirt-engine/api/storagedomains/123/vms/456/import
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action>
  <storage_domain>
    <name>mydata</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
</action>
Copy to Clipboard Toggle word wrap

To import a virtual machine as a new entity add the clone parameter: 

<action>
  <storage_domain>
    <name>mydata</name>
  </storage_domain>
  <cluster>
    <name>mycluster</name>
  </cluster>
  <clone>true</clone>
  <vm>
    <name>myvm</name>
  </vm>
</action>
Copy to Clipboard Toggle word wrap

Include an optional disks parameter to choose which disks to import. For example, to import the disks of the template that have the identifiers 123 and 456 send the following request body: 

<action>
  <cluster>
    <name>mycluster</name>
  </cluster>
  <vm>
    <name>myvm</name>
  </vm>
  <disks>
    <disk id="123"/>
    <disk id="456"/>
  </disks>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.574. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the import should be performed asynchronously.

clone

Boolean

In

Indicates if the identifiers of the imported virtual machine should be regenerated.

cluster

Cluster

In

 

collapse_snapshots

Boolean

In

Indicates of the snapshots of the virtual machine that is imported should be collapsed, so that the result will be a virtual machine without snapshots.

storage_domain

StorageDomain

In

 

vm

Vm

In

 

6.187.2.1. clone
Copy link

Indicates if the identifiers of the imported virtual machine should be regenerated.

By default when a virtual machine is imported the identifiers are preserved. This means that the same virtual machine can’t be imported multiple times, as that identifiers needs to be unique. To allow importing the same machine multiple times set this parameter to true, as the default is false.

6.187.2.2. collapse_snapshots
Copy link

Indicates of the snapshots of the virtual machine that is imported should be collapsed, so that the result will be a virtual machine without snapshots.

This parameter is optional, and if it isn’t explicitly specified the default value is false.

6.187.3. register POST
Copy link

Expand
Table 6.575. Parameters summary
NameTypeDirectionSummary

allow_partial_import

Boolean

In

Indicates whether a virtual machine is allowed to be registered with only some of its disks.

async

Boolean

In

Indicates if the registration should be performed asynchronously.

clone

Boolean

In

 

cluster

Cluster

In

 

reassign_bad_macs

Boolean

In

Indicates if the problematic MAC addresses should be re-assigned during the import process by the engine.

vm

Vm

In

 

vnic_profile_mappings

VnicProfileMapping[]

In

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

6.187.3.1. allow_partial_import
Copy link

Indicates whether a virtual machine is allowed to be registered with only some of its disks.

If this flag is true, the engine will not fail in the validation process if an image is not found, but instead it will allow the virtual machine to be registered without the missing disks. This is mainly used during registration of a virtual machine when some of the storage domains are not available. The default value is false.

6.187.3.2. reassign_bad_macs
Copy link

Indicates if the problematic MAC addresses should be re-assigned during the import process by the engine.

A MAC address would be considered as a problematic one if one of the following is true:

  • It conflicts with a MAC address that is already allocated to a virtual machine in the target environment.
  • It’s out of the range of the target MAC address pool.

6.187.4. remove DELETE
Copy link

Deletes a virtual machine from an export storage domain.

For example, to delete the virtual machine 456 from the storage domain 123, send a request like this: 

DELETE /ovirt-engine/api/storagedomains/123/vms/456
Copy to Clipboard Toggle word wrap
Expand
Table 6.576. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.188. StorageDomainVmDiskAttachment
Copy link

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

Expand
Table 6.577. Methods summary
NameSummary

get

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

6.188.1. get GET
Copy link

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

Expand
Table 6.578. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

Out

The disk attachment.

6.189. StorageDomainVmDiskAttachments
Copy link

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

Expand
Table 6.579. Methods summary
NameSummary

list

List the disks that are attached to the virtual machine.

6.189.1. list GET
Copy link

List the disks that are attached to the virtual machine.

Expand
Table 6.580. Parameters summary
NameTypeDirectionSummary

attachments

DiskAttachment[]

Out

 

6.190. StorageDomainVms
Copy link

Lists the virtual machines of an export storage domain.

For example, to retrieve the virtual machines that are available in the storage domain with identifier 123 send the following request: 

GET /ovirt-engine/api/storagedomains/123/vms
Copy to Clipboard Toggle word wrap

This will return the following response body: 

<vms>
  <vm id="456" href="/api/storagedomains/123/vms/456">
    <name>vm1</name>
    ...
    <storage_domain id="123" href="/api/storagedomains/123"/>
    <actions>
      <link rel="import" href="/api/storagedomains/123/vms/456/import"/>
    </actions>
  </vm>
</vms>
Copy to Clipboard Toggle word wrap

Virtual machines and templates in these collections have a similar representation to their counterparts in the top-level Vm and Template collections, except they also contain a StorageDomain reference and an import action.

Expand
Table 6.581. Methods summary
NameSummary

list

 

6.190.1. list GET
Copy link

Expand
Table 6.582. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of virtual machines to return.

unregistered

Boolean

In

Indicates whether to retrieve a list of registered or unregistered virtual machines which contain disks on the storage domain.

vm

Vm[]

Out

 

6.190.1.1. max
Copy link

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

6.190.1.2. unregistered
Copy link

Indicates whether to retrieve a list of registered or unregistered virtual machines which contain disks on the storage domain. To get a list of unregistered virtual machines the call should indicate the unregistered flag. For example, to get a list of unregistered virtual machines the REST API call should look like this: 

GET /ovirt-engine/api/storagedomains/123/vms?unregistered=true
Copy to Clipboard Toggle word wrap

The default value of the unregisterd flag is false. The request only apply to storage domains that are attached.

6.191. StorageDomains
Copy link

Expand
Table 6.583. Methods summary
NameSummary

add

Adds a new storage domain.

list

 

6.191.1. add POST
Copy link

Adds a new storage domain.

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

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

POST /ovirt-engine/api/storagedomains
Copy to Clipboard Toggle word wrap

With a request body as follows: 

<storage_domain>
  <name>mydata</name>
  <type>data</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
Copy to Clipboard Toggle word wrap

To create a new NFS ISO storage domain send a request like this: 

<storage_domain>
  <name>myisos</name>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/export/myisos</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
Copy to Clipboard Toggle word wrap

To create a new iSCSI storage domain send a request like this: 

<storage_domain>
  <name>myiscsi</name>
  <type>data</type>
  <storage>
    <type>iscsi</type>
    <logical_units>
      <logical_unit id="3600144f09dbd050000004eedbd340001"/>
      <logical_unit id="3600144f09dbd050000004eedbd340002"/>
    </logical_units>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
Copy to Clipboard Toggle word wrap
Expand
Table 6.584. Parameters summary
NameTypeDirectionSummary

storage_domain

StorageDomain

In/Out

 

6.191.2. list GET
Copy link

Expand
Table 6.585. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of storage domains to return.

search

String

In

A query string used to restrict the returned storage domains.

storage_domains

StorageDomain[]

Out

 

6.191.2.1. case_sensitive
Copy link

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

6.191.2.2. max
Copy link

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

6.192. StorageServerConnection
Copy link

Expand
Table 6.586. Methods summary
NameSummary

get

 

remove

Removes a storage connection.

update

Updates the storage connection.

6.192.1. get GET
Copy link

Expand
Table 6.587. Parameters summary
NameTypeDirectionSummary

conection

StorageConnection

Out

 

6.192.2. remove DELETE
Copy link

Removes a storage connection.

A storage connection can only be deleted if neither storage domain nor LUN disks reference it. The host name or id is optional; providing it disconnects (unmounts) the connection from that host.

Expand
Table 6.588. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

host

String

In

The name or identifier of the host from which the connection would be unmounted (disconnected).

6.192.2.1. host
Copy link

The name or identifier of the host from which the connection would be unmounted (disconnected). If not provided, no host will be disconnected.

For example, to use the host with identifier 456 to delete the storage connection with identifier 123 send a request like this: 

DELETE /ovirt-engine/api/storageconnections/123?host=456
Copy to Clipboard Toggle word wrap

6.192.3. update PUT
Copy link

Updates the storage connection.

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

PUT /ovirt-engine/api/storageconnections/123
Copy to Clipboard Toggle word wrap

With a request body like this: 

<storage_connection>
  <address>mynewnfs.example.com</address>
  <host>
    <name>myhost</name>
  </host>
</storage_connection>
Copy to Clipboard Toggle word wrap
Expand
Table 6.589. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

connection

StorageConnection

In/Out

 

force

Boolean

In

Indicates if the operation should succeed regardless to the relevant storage domain’s status (i.

6.192.3.1. force
Copy link

Indicates if the operation should succeed regardless to the relevant storage domain’s status (i.e. updating is also applicable when storage domain’s status is not maintenance).

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

6.193. StorageServerConnectionExtension
Copy link

Expand
Table 6.590. Methods summary
NameSummary

get

 

remove

 

update

Update a storage server connection extension for the given host.

6.193.1. get GET
Copy link

Expand
Table 6.591. Parameters summary
NameTypeDirectionSummary

extension

StorageConnectionExtension

Out

 

6.193.2. remove DELETE
Copy link

Expand
Table 6.592. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.193.3. update PUT
Copy link

Update a storage server connection extension for the given host.

To update the storage connection 456 of host 123 send a request like this: 

PUT /ovirt-engine/api/hosts/123/storageconnectionextensions/456
Copy to Clipboard Toggle word wrap

With a request body like this: 

<storage_connection_extension>
  <target>iqn.2016-01.com.example:mytarget</target>
  <username>myuser</username>
  <password>mypassword</password>
</storage_connection_extension>
Copy to Clipboard Toggle word wrap
Expand
Table 6.593. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

extension

StorageConnectionExtension

In/Out

 

6.194. StorageServerConnectionExtensions
Copy link

Expand
Table 6.594. Methods summary
NameSummary

add

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

list

 

6.194.1. add POST
Copy link

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

The extension lets the user define credentials for an iSCSI target for a specific host. For example to use myuser and mypassword as the credentials when connecting to the iSCSI target from host 123 send a request like this: 

POST /ovirt-engine/api/hosts/123/storageconnectionextensions
Copy to Clipboard Toggle word wrap

With a request body like this: 

<storage_connection_extension>
  <target>iqn.2016-01.com.example:mytarget</target>
  <username>myuser</username>
  <password>mypassword</password>
</storage_connection_extension>
Copy to Clipboard Toggle word wrap
Expand
Table 6.595. Parameters summary
NameTypeDirectionSummary

extension

StorageConnectionExtension

In/Out

 

6.194.2. list GET
Copy link

Expand
Table 6.596. Parameters summary
NameTypeDirectionSummary

extensions

StorageConnectionExtension[]

Out

 

max

Integer

In

Sets the maximum number of extensions to return.

6.194.2.1. max
Copy link

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

6.195. StorageServerConnections
Copy link

Expand
Table 6.597. Methods summary
NameSummary

add

Creates a new storage connection.

list

 

6.195.1. add POST
Copy link

Creates a new storage connection.

For example, to create a new storage connection for the NFS server mynfs.example.com and NFS share /export/mydata send a request like this: 

POST /ovirt-engine/api/storageconnections
Copy to Clipboard Toggle word wrap

With a request body like this: 

<storage_connection>
  <type>nfs</type>
  <address>mynfs.example.com</address>
  <path>/export/mydata</path>
  <host>
    <name>myhost</name>
  </host>
</storage_connection>
Copy to Clipboard Toggle word wrap
Expand
Table 6.598. Parameters summary
NameTypeDirectionSummary

connection

StorageConnection

In/Out

 

6.195.2. list GET
Copy link

Expand
Table 6.599. Parameters summary
NameTypeDirectionSummary

connections

StorageConnection[]

Out

 

max

Integer

In

Sets the maximum number of connections to return.

6.195.2.1. max
Copy link

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

6.196. System
Copy link

Expand
Table 6.600. Methods summary
NameSummary

get

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

reloadconfigurations

 

6.196.1. get GET
Copy link

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

GET /ovirt-engine/api
Copy to Clipboard Toggle word wrap

We get following response: 

<api>
  <link rel="capabilities" href="/api/capabilities"/>
  <link rel="clusters" href="/api/clusters"/>
  <link rel="clusters/search" href="/api/clusters?search={query}"/>
  <link rel="datacenters" href="/api/datacenters"/>
  <link rel="datacenters/search" href="/api/datacenters?search={query}"/>
  <link rel="events" href="/api/events"/>
  <link rel="events/search" href="/api/events?search={query}"/>
  <link rel="hosts" href="/api/hosts"/>
  <link rel="hosts/search" href="/api/hosts?search={query}"/>
  <link rel="networks" href="/api/networks"/>
  <link rel="roles" href="/api/roles"/>
  <link rel="storagedomains" href="/api/storagedomains"/>
  <link rel="storagedomains/search" href="/api/storagedomains?search={query}"/>
  <link rel="tags" href="/api/tags"/>
  <link rel="templates" href="/api/templates"/>
  <link rel="templates/search" href="/api/templates?search={query}"/>
  <link rel="users" href="/api/users"/>
  <link rel="groups" href="/api/groups"/>
  <link rel="domains" href="/api/domains"/>
  <link rel="vmpools" href="/api/vmpools"/>
  <link rel="vmpools/search" href="/api/vmpools?search={query}"/>
  <link rel="vms" href="/api/vms"/>
  <link rel="vms/search" href="/api/vms?search={query}"/>
  <product_info>
    <name>oVirt Engine</name>
    <vendor>ovirt.org</vendor>
    <version>
      <build>4</build>
      <full_version>4.0.4</full_version>
      <major>4</major>
      <minor>0</minor>
      <revision>0</revision>
    </version>
  </product_info>
  <special_objects>
    <blank_template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <root_tag href="/ovirt-engine/api/tags/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
  </special_objects>
  <summary>
    <hosts>
      <active>0</active>
      <total>0</total>
    </hosts>
    <storage_domains>
      <active>0</active>
      <total>1</total>
    </storage_domains>
    <users>
      <active>1</active>
      <total>1</total>
    </users>
    <vms>
      <active>0</active>
      <total>0</total>
    </vms>
  </summary>
  <time>2016-09-14T12:00:48.132+02:00</time>
</api>
Copy to Clipboard Toggle word wrap

The entry point provides a user with links to the collections in a virtualization environment. The rel attribute of each collection link provides a reference point for each link.

The entry point also contains other data such as product_info, special_objects and summary.

Expand
Table 6.601. Parameters summary
NameTypeDirectionSummary

api

Api

Out

 

6.196.2. reloadconfigurations POST
Copy link

Expand
Table 6.602. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reload should be performed asynchronously.

6.197. SystemPermissions
Copy link

This service doesn’t add any new methods, it is just a placeholder for the annotation that specifies the path of the resource that manages the permissions assigned to the system object.

Expand
Table 6.603. Methods summary
NameSummary

add

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

list

List all the permissions of the specific entity.

6.197.1. add POST
Copy link

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<permission>
  <role>
    <name>UserVmManager</name>
  </role>
  <user id="456"/>
</permission>
Copy to Clipboard Toggle word wrap

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

POST /ovirt-engine/api/permissions
Copy to Clipboard Toggle word wrap

With a request body like this: 

<permission>
  <role>
    <name>SuperUser</name>
  </role>
  <user id="456"/>
</permission>
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

With a request body like this: 

<permission>
  <role>
    <name>UserRole</name>
  </role>
  <group id="789"/>
</permission>
Copy to Clipboard Toggle word wrap
Expand
Table 6.604. Parameters summary
NameTypeDirectionSummary

permission

Permission

In/Out

The permission.

6.197.2. list GET
Copy link

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
Copy to Clipboard Toggle word wrap 
<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>
Copy to Clipboard Toggle word wrap
Expand
Table 6.605. Parameters summary
NameTypeDirectionSummary

permissions

Permission[]

Out

The list of permissions.

6.198. Tag
Copy link

A service to manage a specific tag in the system.

Expand
Table 6.606. Methods summary
NameSummary

get

Gets the information about the tag.

remove

Removes the tag from the system.

update

Updates the tag entity.

6.198.1. get GET
Copy link

Gets the information about the tag.

For example to retrieve the information about the tag with the id 123 send a request like this: 

GET /ovirt-engine/api/tags/123
Copy to Clipboard Toggle word wrap 
<tag href="/ovirt-engine/api/tags/123" id="123">
  <name>root</name>
  <description>root</description>
</tag>
Copy to Clipboard Toggle word wrap
Expand
Table 6.607. Parameters summary
NameTypeDirectionSummary

tag

Tag

Out

The tag.

6.198.2. remove DELETE
Copy link

Removes the tag from the system.

For example to remove the tag with id 123 send a request like this: 

DELETE /ovirt-engine/api/tags/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.608. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.198.3. update PUT
Copy link

Updates the tag entity.

For example to update parent tag to tag with id 456 of the tag with id 123 send a request like this: 

PUT /ovirt-engine/api/tags/123
Copy to Clipboard Toggle word wrap

With request body like: 

<tag>
  <parent id="456"/>
</tag>
Copy to Clipboard Toggle word wrap

You may also specify a tag name instead of id. For example to update parent tag to tag with name mytag of the tag with id 123 send a request like this: 

<tag>
  <parent>
    <name>mytag</name>
  </parent>
</tag>
Copy to Clipboard Toggle word wrap
Expand
Table 6.609. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

tag

Tag

In/Out

The updated tag.

6.199. Tags
Copy link

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

Expand
Table 6.610. Methods summary
NameSummary

add

Add a new tag to the system.

list

List the tags in the system.

6.199.1. add POST
Copy link

Add a new tag to the system.

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

POST /ovirt-engine/api/tags
Copy to Clipboard Toggle word wrap

With a request body like this: 

<tag>
  <name>mytag</name>
</tag>
Copy to Clipboard Toggle word wrap
Note

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

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

<tag>
  <name>mytag</name>
  <parent>
    <name>myparenttag</name>
  </parent>
</tag>
Copy to Clipboard Toggle word wrap
Expand
Table 6.611. Parameters summary
NameTypeDirectionSummary

tag

Tag

In/Out

The added tag.

6.199.2. list GET
Copy link

List the tags in the system.

For example to list the full hierarchy of the tags in the system send a request like this: 

GET /ovirt-engine/api/tags
Copy to Clipboard Toggle word wrap 
<tags>
  <tag href="/ovirt-engine/api/tags/222" id="222">
    <name>root2</name>
    <description>root2</description>
    <parent href="/ovirt-engine/api/tags/111" id="111"/>
  </tag>
  <tag href="/ovirt-engine/api/tags/333" id="333">
    <name>root3</name>
    <description>root3</description>
    <parent href="/ovirt-engine/api/tags/222" id="222"/>
  </tag>
  <tag href="/ovirt-engine/api/tags/111" id="111">
    <name>root</name>
    <description>root</description>
  </tag>
</tags>
Copy to Clipboard Toggle word wrap

In the previous XML output you can see the following hierarchy of the tags: 

root:        (id: 111)
  - root2    (id: 222)
    - root3  (id: 333)
Copy to Clipboard Toggle word wrap
Expand
Table 6.612. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of tags to return.

tags

Tag[]

Out

List of all tags in the system.

6.199.2.1. max
Copy link

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

6.200. Template
Copy link

Manages the virtual machine template and template versions.

Expand
Table 6.613. Methods summary
NameSummary

export

Exports a template to the data center export domain.

get

Returns the information about this template or template version.

remove

Removes a virtual machine template.

update

Updates the template.

6.200.1. export POST
Copy link

Exports a template to the data center export domain.

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

POST /ovirt-engine/api/templates/123/export
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action>
  <storage_domain id="456"/>
  <exclusive>true<exclusive/>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.614. Parameters summary
NameTypeDirectionSummary

exclusive

Boolean

In

Indicates if the existing templates with the same name should be overwritten.

storage_domain

StorageDomain

In

Specifies the destination export storage domain.

6.200.1.1. exclusive
Copy link

Indicates if the existing templates with the same name should be overwritten.

The export action reports a failed action if a template of the same name exists in the destination domain. Set this parameter to true to change this behavior and overwrite any existing template.

6.200.2. get GET
Copy link

Returns the information about this template or template version.

Expand
Table 6.615. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

template

Template

Out

The information about the template or template version.

6.200.3. remove DELETE
Copy link

Removes a virtual machine template. 

DELETE /ovirt-engine/api/templates/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.616. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.200.4. update PUT
Copy link

Updates the template.

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

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

PUT /ovirt-engine/api/templates/123
Copy to Clipboard Toggle word wrap

With the following request body: 

<template>
  <memory>1073741824</memory>
</template>
Copy to Clipboard Toggle word wrap

The version_name name attribute is the only one that can be updated within the version attribute used for template versions: 

<template>
  <version>
    <version_name>mytemplate_2</version_name>
  </version>
</template>
Copy to Clipboard Toggle word wrap
Expand
Table 6.617. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

template

Template

In/Out

 

6.201. TemplateCdrom
Copy link

A service managing a CD-ROM device on templates.

Expand
Table 6.618. Methods summary
NameSummary

get

Returns the information about this CD-ROM device.

6.201.1. get GET
Copy link

Returns the information about this CD-ROM device.

For example, to get information about the CD-ROM device of template 123 send a request like: 

GET /ovirt-engine/api/templates/123/cdroms/
Copy to Clipboard Toggle word wrap
Expand
Table 6.619. Parameters summary
NameTypeDirectionSummary

cdrom

Cdrom

Out

The information about the CD-ROM device.

6.201.1.1. cdrom
Copy link

The information about the CD-ROM device.

The information consists of cdrom attribute containing reference to the CD-ROM device, the template, and optionally the inserted disk.

If there is a disk inserted then the file attribute will contain a reference to the ISO image: 

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <template href="/ovirt-engine/api/templates/123" id="123"/>
  <file id="mycd.iso"/>
</cdrom>
Copy to Clipboard Toggle word wrap

If there is no disk inserted then the file attribute won’t be reported: 

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <template href="/ovirt-engine/api/templates/123" id="123"/>
</cdrom>
Copy to Clipboard Toggle word wrap

6.202. TemplateCdroms
Copy link

Lists the CD-ROM devices of a template.

Expand
Table 6.620. Methods summary
NameSummary

list

 

6.202.1. list GET
Copy link

Expand
Table 6.621. Parameters summary
NameTypeDirectionSummary

cdroms

Cdrom[]

Out

The list of CD-ROM devices of the template.

max

Integer

In

Sets the maximum number of CD-ROMs to return.

6.202.1.1. max
Copy link

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

6.203. TemplateDisk
Copy link

Expand
Table 6.622. Methods summary
NameSummary

copy

 

export

 

get

 

remove

 

6.203.1. copy POST
Copy link

Expand
Table 6.623. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the copy should be performed asynchronously.

filter

Boolean

In

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

6.203.2. export POST
Copy link

Expand
Table 6.624. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the export should be performed asynchronously.

filter

Boolean

In

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

6.203.3. get GET
Copy link

Expand
Table 6.625. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.203.4. remove DELETE
Copy link

Expand
Table 6.626. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.204. TemplateDiskAttachment
Copy link

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

Expand
Table 6.627. Methods summary
NameSummary

get

Returns the details of the attachment.

remove

Removes the disk from the template.

6.204.1. get GET
Copy link

Returns the details of the attachment.

Expand
Table 6.628. Parameters summary
NameTypeDirectionSummary

attachment

DiskAttachment

Out

 

6.204.2. remove DELETE
Copy link

Removes the disk from the template. The disk will only be removed if there are other existing copies of the disk on other storage domains.

A storage domain has to be specified to determine which of the copies should be removed (template disks can have copies on multiple storage domains). 

DELETE /ovirt-engine/api/templates/{template:id}/diskattachments/{attachment:id}?storage_domain=072fbaa1-08f3-4a40-9f34-a5ca22dd1d74
Copy to Clipboard Toggle word wrap
Expand
Table 6.629. Parameters summary
NameTypeDirectionSummary

force

Boolean

In

 

storage_domain

String

In

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

6.205. TemplateDiskAttachments
Copy link

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

Expand
Table 6.630. Methods summary
NameSummary

list

List the disks that are attached to the template.

6.205.1. list GET
Copy link

List the disks that are attached to the template.

Expand
Table 6.631. Parameters summary
NameTypeDirectionSummary

attachments

DiskAttachment[]

Out

 

6.206. TemplateDisks
Copy link

Expand
Table 6.632. Methods summary
NameSummary

list

 

6.206.1. list GET
Copy link

Expand
Table 6.633. Parameters summary
NameTypeDirectionSummary

disks

Disk[]

Out

 

max

Integer

In

Sets the maximum number of disks to return.

6.206.1.1. max
Copy link

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

6.207. TemplateGraphicsConsole
Copy link

Expand
Table 6.634. Methods summary
NameSummary

get

Gets graphics console configuration of the template.

remove

Remove the graphics console from the template.

6.207.1. get GET
Copy link

Gets graphics console configuration of the template.

Expand
Table 6.635. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

Out

The information about the graphics console of the template.

6.207.2. remove DELETE
Copy link

Remove the graphics console from the template.

Expand
Table 6.636. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.208. TemplateGraphicsConsoles
Copy link

Expand
Table 6.637. Methods summary
NameSummary

add

Add new graphics console to the template.

list

Lists all the configured graphics consoles of the template.

6.208.1. add POST
Copy link

Add new graphics console to the template.

Expand
Table 6.638. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

In/Out

 

6.208.2. list GET
Copy link

Lists all the configured graphics consoles of the template.

Expand
Table 6.639. Parameters summary
NameTypeDirectionSummary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the template.

max

Integer

In

Sets the maximum number of consoles to return.

6.208.2.1. max
Copy link

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

6.209. TemplateNic
Copy link

Expand
Table 6.640. Methods summary
NameSummary

get

 

remove

 

update

 

6.209.1. get GET
Copy link

Expand
Table 6.641. Parameters summary
NameTypeDirectionSummary

nic

Nic

Out

 

6.209.2. remove DELETE
Copy link

Expand
Table 6.642. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.209.3. update PUT
Copy link

Expand
Table 6.643. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

 

6.210. TemplateNics
Copy link

Expand
Table 6.644. Methods summary
NameSummary

add

 

list

 

6.210.1. add POST
Copy link

Expand
Table 6.645. Parameters summary
NameTypeDirectionSummary

nic

Nic

In/Out

 

6.210.2. list GET
Copy link

Expand
Table 6.646. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

 

6.210.2.1. max
Copy link

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

6.211. TemplateWatchdog
Copy link

Expand
Table 6.647. Methods summary
NameSummary

get

 

remove

 

update

 

6.211.1. get GET
Copy link

Expand
Table 6.648. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

Out

 

6.211.2. remove DELETE
Copy link

Expand
Table 6.649. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.211.3. update PUT
Copy link

Expand
Table 6.650. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

 

6.212. TemplateWatchdogs
Copy link

Expand
Table 6.651. Methods summary
NameSummary

add

 

list

 

6.212.1. add POST
Copy link

Expand
Table 6.652. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

In/Out

 

6.212.2. list GET
Copy link

Expand
Table 6.653. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of watchdogs to return.

watchdogs

Watchdog[]

Out

 

6.212.2.1. max
Copy link

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

6.213. Templates
Copy link

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

Expand
Table 6.654. Methods summary
NameSummary

add

Creates a new template.

list

Returns the list of virtual machine templates.

6.213.1. add POST
Copy link

Creates a new template.

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

POST /ovirt-engine/api/templates
Copy to Clipboard Toggle word wrap

With a request body like this: 

<template>
  <name>mytemplate</name>
  <vm id="123"/>
</template>
Copy to Clipboard Toggle word wrap

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

<template>
  <name>mytemplate</name>
  <vm id="123"/>
  <version>
    <base_template id="456"/>
    <version_name>mytemplate_001</version_name>
  </version>
</template>
Copy to Clipboard Toggle word wrap
Expand
Table 6.655. Parameters summary
NameTypeDirectionSummary

clone_permissions

Boolean

In

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

seal

Boolean

In

Seal the template.

template

Template

In/Out

The information about the template or template version.

6.213.1.1. clone_permissions
Copy link

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

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

POST /ovirt-engine/api/templates?clone_permissions=true
Copy to Clipboard Toggle word wrap

With a request body like this: 

<template>
  <name>mytemplate<name>
  <vm>
    <name>myvm<name>
  </vm>
</template>
Copy to Clipboard Toggle word wrap

6.213.1.2. seal
Copy link

Seal the template.

If this optional parameter is provided and its value is true, then the template is sealed after creation.

Sealing erases all host-specific configuration from the filesystem: SSH keys, UDEV rules, MAC addresses, system ID, hostname etc., thus making easy to use the template to create multiple virtual machines without manual intervention.

Currently sealing is supported only for Linux OS.

6.213.2. list GET
Copy link

Returns the list of virtual machine templates.

For example: 

GET /ovirt-engine/api/templates
Copy to Clipboard Toggle word wrap

Will return the list of virtual machines and virtual machine templates.

Expand
Table 6.656. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of templates to return.

search

String

In

A query string used to restrict the returned templates.

templates

Template[]

Out

The list of virtual machine templates.

6.213.2.1. case_sensitive
Copy link

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

6.213.2.2. max
Copy link

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

6.214. UnmanagedNetwork
Copy link

Expand
Table 6.657. Methods summary
NameSummary

get

 

remove

 

6.214.1. get GET
Copy link

Expand
Table 6.658. Parameters summary
NameTypeDirectionSummary

network

UnmanagedNetwork

Out

 

6.214.2. remove DELETE
Copy link

Expand
Table 6.659. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.215. UnmanagedNetworks
Copy link

Expand
Table 6.660. Methods summary
NameSummary

list

 

6.215.1. list GET
Copy link

Expand
Table 6.661. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

UnmanagedNetwork[]

Out

 

6.215.1.1. max
Copy link

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

6.216. User
Copy link

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

Expand
Table 6.662. Methods summary
NameSummary

get

Gets the system user information.

remove

Removes the system user.

6.216.1. get GET
Copy link

Gets the system user information.

Usage: 

GET /ovirt-engine/api/users/1234
Copy to Clipboard Toggle word wrap

Will return the user information: 

<user href="/ovirt-engine/api/users/1234" id="1234">
  <name>admin</name>
  <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/>
  <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/>
  <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/>
  <department></department>
  <domain_entry_id>23456</domain_entry_id>
  <email>user1@domain.com</email>
  <last_name>Lastname</last_name>
  <namespace>*</namespace>
  <principal>user1</principal>
  <user_name>user1@domain-authz</user_name>
  <domain href="/ovirt-engine/api/domains/45678" id="45678">
    <name>domain-authz</name>
  </domain>
</user>
Copy to Clipboard Toggle word wrap
Expand
Table 6.663. Parameters summary
NameTypeDirectionSummary

user

User

Out

The system user.

6.216.2. remove DELETE
Copy link

Removes the system user.

Usage: 

DELETE /ovirt-engine/api/users/1234
Copy to Clipboard Toggle word wrap
Expand
Table 6.664. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.217. Users
Copy link

A service to manage the users in the system.

Expand
Table 6.665. Methods summary
NameSummary

add

Add user from a directory service.

list

List all the users in the system.

6.217.1. add POST
Copy link

Add user from a directory service.

For example, to add the myuser user from the myextension-authz authorization provider send a request like this: 

POST /ovirt-engine/api/users
Copy to Clipboard Toggle word wrap

With a request body like this: 

<user>
  <user_name>myuser@myextension-authz</user_name>
  <domain>
    <name>myextension-authz</name>
  </domain>
</user>
Copy to Clipboard Toggle word wrap

In case you are working with Active Directory you have to pass user principal name (UPN) as username, followed by authorization provider name. Due to bug 1147900 you need to provide also principal parameter set to UPN of the user.

For example, to add the user with UPN myuser@mysubdomain.mydomain.com from the myextension-authz authorization provider send a request body like this: 

<user>
  <principal>myuser@mysubdomain.mydomain.com</principal>
  <user_name>myuser@mysubdomain.mydomain.com@myextension-authz</user_name>
  <domain>
    <name>myextension-authz</name>
  </domain>
</user>
Copy to Clipboard Toggle word wrap
Expand
Table 6.666. Parameters summary
NameTypeDirectionSummary

user

User

In/Out

 

6.217.2. list GET
Copy link

List all the users in the system.

Usage: 

GET /ovirt-engine/api/users
Copy to Clipboard Toggle word wrap

Will return the list of users: 

<users>
  <user href="/ovirt-engine/api/users/1234" id="1234">
    <name>admin</name>
    <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/>
    <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/>
    <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/>
    <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/>
    <domain_entry_id>23456</domain_entry_id>
    <namespace>*</namespace>
    <principal>user1</principal>
    <user_name>user1@domain-authz</user_name>
    <domain href="/ovirt-engine/api/domains/45678" id="45678">
      <name>domain-authz</name>
    </domain>
  </user>
</users>
Copy to Clipboard Toggle word wrap
Expand
Table 6.667. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

max

Integer

In

Sets the maximum number of users to return.

search

String

In

A query string used to restrict the returned users.

users

User[]

Out

The list of users.

6.217.2.1. case_sensitive
Copy link

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

6.217.2.2. max
Copy link

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

6.218. VirtualFunctionAllowedNetwork
Copy link

Expand
Table 6.668. Methods summary
NameSummary

get

 

remove

 

6.218.1. get GET
Copy link

Expand
Table 6.669. Parameters summary
NameTypeDirectionSummary

network

Network

Out

 

6.218.2. remove DELETE
Copy link

Expand
Table 6.670. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.219. VirtualFunctionAllowedNetworks
Copy link

Expand
Table 6.671. Methods summary
NameSummary

add

 

list

 

6.219.1. add POST
Copy link

Expand
Table 6.672. Parameters summary
NameTypeDirectionSummary

network

Network

In/Out

 

6.219.2. list GET
Copy link

Expand
Table 6.673. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of networks to return.

networks

Network[]

Out

 

6.219.2.1. max
Copy link

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

6.220. Vm
Copy link

Expand
Table 6.674. Methods summary
NameSummary

cancelmigration

This operation stops any migration of a virtual machine to another physical host.

clone

 

commitsnapshot

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

detach

Detaches a virtual machine from a pool.

export

Exports a virtual machine to an export domain.

freezefilesystems

Freezes virtual machine file systems.

get

Retrieves the description of the virtual machine.

logon

Initiates the automatic user logon to access a virtual machine from an external console.

maintenance

Sets the global maintenance mode on the hosted engine virtual machine.

migrate

Migrates a virtual machine to another physical host.

previewsnapshot

Temporarily restores the virtual machine to the state of a snapshot.

reboot

Sends a reboot request to a virtual machine.

remove

Removes the virtual machine, including the virtual disks attached to it.

reordermacaddresses

 

shutdown

This operation sends a shutdown request to a virtual machine.

start

Starts the virtual machine.

stop

This operation forces a virtual machine to power-off.

suspend

This operation saves the virtual machine state to disk and stops it.

thawfilesystems

Thaws virtual machine file systems.

ticket

Generates a time-sensitive authentication token for accessing a virtual machine’s display.

undosnapshot

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

update

 

6.220.1. cancelmigration POST
Copy link

This operation stops any migration of a virtual machine to another physical host. 

POST /ovirt-engine/api/vms/123/cancelmigration
Copy to Clipboard Toggle word wrap

The cancel migration action does not take any action specific parameters; therefore, the request body should contain an empty action: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.675. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the migration should cancelled asynchronously.

6.220.2. clone POST
Copy link

Expand
Table 6.676. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the clone should be performed asynchronously.

vm

Vm

In

 

6.220.3. commitsnapshot POST
Copy link

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

See the preview_snapshot operation for details.

Expand
Table 6.677. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the snapshots should be committed asynchronously.

6.220.4. detach POST
Copy link

Detaches a virtual machine from a pool. 

POST /ovirt-engine/api/vms/123/detach
Copy to Clipboard Toggle word wrap

The detach action does not take any action specific parameters; therefore, the request body should contain an empty action: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.678. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the detach action should be performed asynchronously.

6.220.5. export POST
Copy link

Exports a virtual machine to an export domain.

For example, to export virtual machine 123 to the export domain myexport: 

POST /ovirt-engine/api/vms/123/export
Copy to Clipboard Toggle word wrap

With a request body like this: 

<action>
  <storage_domain>
    <name>myexport</name>
  </storage_domain>
  <exclusive>true</exclusive>
  <discard_snapshots>true</discard_snapshots>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.679. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the export should be performed asynchronously.

discard_snapshots

Boolean

In

Use the discard_snapshots parameter when the virtual machine should be exported with all of its snapshots collapsed.

exclusive

Boolean

In

Use the exclusive parameter when the virtual machine should be exported even if another copy of it already exists in the export domain (override).

storage_domain

StorageDomain

In

 

6.220.6. freezefilesystems POST
Copy link

Freezes virtual machine file systems.

This operation freezes a virtual machine’s file systems using the QEMU guest agent when taking a live snapshot of a running virtual machine. Normally, this is done automatically by the manager, but this must be executed manually with the API for virtual machines using OpenStack Volume (Cinder) disks.

Example: 

POST /ovirt-engine/api/vms/123/freezefilesystems
Copy to Clipboard Toggle word wrap 
<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.680. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the freeze should be performed asynchronously.

6.220.7. get GET
Copy link

Retrieves the description of the virtual machine.

Expand
Table 6.681. Parameters summary
NameTypeDirectionSummary

all_content

Boolean

In

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

filter

Boolean

In

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

next_run

Boolean

In

Indicates if the returned result describes the virtual machine as it is currently running or if describes the virtual machine with the modifications that have already been performed but that will only come into effect when the virtual machine is restarted.

vm

Vm

Out

Description of the virtual machine.

6.220.7.1. all_content
Copy link

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

By default the following attributes are excluded:

  • console
  • initialization.configuration.data - The OVF document describing the virtual machine.
  • rng_source
  • soundcard
  • virtio_scsi

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

GET /ovirt-engine/api/vms/123?all_content=true
Copy to Clipboard Toggle word wrap
Note

These attributes are not included by default as they reduce performance. These attributes are seldom used and require additional queries to the database. Only use this parameter when required as it will reduce performance.

6.220.7.2. next_run
Copy link

Indicates if the returned result describes the virtual machine as it is currently running or if describes the virtual machine with the modifications that have already been performed but that will only come into effect when the virtual machine is restarted. By default the value is false.

If the parameter is included in the request, but without a value, it is assumed that the value is true. The the following request: 

GET /vms/{vm:id};next_run
Copy to Clipboard Toggle word wrap

Is equivalent to using the value true: 

GET /vms/{vm:id};next_run=true
Copy to Clipboard Toggle word wrap

6.220.8. logon POST
Copy link

Initiates the automatic user logon to access a virtual machine from an external console.

This action requires the ovirt-guest-agent-gdm-plugin and the ovirt-guest-agent-pam-module packages to be installed and the ovirt-guest-agent service to be running on the virtual machine.

Users require the appropriate user permissions for the virtual machine in order to access the virtual machine from an external console.

For example: 

POST /ovirt-engine/api/vms/123/logon
Copy to Clipboard Toggle word wrap

Request body: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.682. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the logon should be performed asynchronously.

6.220.9. maintenance POST
Copy link

Sets the global maintenance mode on the hosted engine virtual machine.

This action has no effect on other virtual machines.

Example: 

POST /ovirt-engine/api/vms/123/maintenance
Copy to Clipboard Toggle word wrap 
<action>
  <maintenance_enabled>true<maintenance_enabled/>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.683. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the global maintenance action should be performed asynchronously.

maintenance_enabled

Boolean

In

Indicates if global maintenance should be enabled or disabled.

6.220.10. migrate POST
Copy link

Migrates a virtual machine to another physical host.

Example: 

POST /ovirt-engine/api/vms/123/migrate
Copy to Clipboard Toggle word wrap

To specify a specific host to migrate the virtual machine to: 

<action>
  <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.684. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the migration should be performed asynchronously.

cluster

Cluster

In

Specifies the cluster the virtual machine should migrate to.

force

Boolean

In

Specifies that the virtual machine should migrate even if the virtual machine is defined as non-migratable.

host

Host

In

Specifies a specific host that the virtual machine should migrate to.

6.220.10.1. cluster
Copy link

Specifies the cluster the virtual machine should migrate to. This is an optional parameter. By default, the virtual machine is migrated to another host within the same cluster.

6.220.10.2. force
Copy link

Specifies that the virtual machine should migrate even if the virtual machine is defined as non-migratable. This is an optional parameter. By default, it is set to false.

6.220.10.3. host
Copy link

Specifies a specific host that the virtual machine should migrate to. This is an optional parameter. By default, the Red Hat Virtualization Manager automatically selects a default host for migration within the same cluster. If an API user requires a specific host, the user can specify the host with either an id or name parameter.

6.220.11. previewsnapshot POST
Copy link

Temporarily restores the virtual machine to the state of a snapshot.

The snapshot is indicated with the snapshot.id parameter. It is restored temporarily, so that the content can be inspected. Once that inspection is finished, the state of the virtual machine can be made permanent, using the commit_snapshot method, or discarded using the undo_snapshot method.

Expand
Table 6.685. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the preview should be performed asynchronously.

disks

Disk[]

In

 

restore_memory

Boolean

In

 

snapshot

Snapshot

In

 

vm

Vm

In

 

6.220.12. reboot POST
Copy link

Sends a reboot request to a virtual machine.

For example: 

POST /ovirt-engine/api/vms/123/reboot
Copy to Clipboard Toggle word wrap

The reboot action does not take any action specific parameters; therefore, the request body should contain an empty action: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.686. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the reboot should be performed asynchronously.

6.220.13. remove DELETE
Copy link

Removes the virtual machine, including the virtual disks attached to it.

For example, to remove the virtual machine with identifier 123: 

DELETE /ovirt-engine/api/vms/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.687. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

detach_only

Boolean

In

Indicates if the attached virtual disks should be detached first and preserved instead of being removed.

force

Boolean

In

Indicates if the virtual machine should be forcibly removed.

6.220.13.1. force
Copy link

Indicates if the virtual machine should be forcibly removed.

Locked virtual machines and virtual machines with locked disk images cannot be removed without this flag set to true.

6.220.14. reordermacaddresses POST
Copy link

Expand
Table 6.688. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the action should be performed asynchronously.

6.220.15. shutdown POST
Copy link

This operation sends a shutdown request to a virtual machine.

For example: 

POST /ovirt-engine/api/vms/123/shutdown
Copy to Clipboard Toggle word wrap

The shutdown action does not take any action specific parameters; therefore, the request body should contain an empty action: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.689. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the shutdown should be performed asynchronously.

6.220.16. start POST
Copy link

Starts the virtual machine.

If the virtual environment is complete and the virtual machine contains all necessary components to function, it can be started.

This example starts the virtual machine: 

POST /ovirt-engine/api/vms/123/start
Copy to Clipboard Toggle word wrap

With a request body: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.690. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the start action should be performed asynchronously.

filter

Boolean

In

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

pause

Boolean

In

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

use_cloud_init

Boolean

In

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

use_sysprep

Boolean

In

If set to true, the initialization type is set to Sysprep.

vm

Vm

In

The definition of the virtual machine for this specific run.

6.220.16.1. pause
Copy link

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

6.220.16.2. use_cloud_init
Copy link

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

6.220.16.3. use_sysprep
Copy link

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

6.220.16.4. vm
Copy link

The definition of the virtual machine for this specific run.

For example: 

<action>
  <vm>
    <os>
      <boot>
        <devices>
          <device>cdrom</device>
        </devices>
      </boot>
    </os>
  </vm>
</action>
Copy to Clipboard Toggle word wrap

This will set the boot device to the CDROM only for this specific start. After the virtual machine is powered off, this definition will be reverted.

6.220.17. stop POST
Copy link

This operation forces a virtual machine to power-off.

For example: 

POST /ovirt-engine/api/vms/123/stop
Copy to Clipboard Toggle word wrap

The stop action does not take any action specific parameters; therefore, the request body should contain an empty action: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.691. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the stop action should be performed asynchronously.

6.220.18. suspend POST
Copy link

This operation saves the virtual machine state to disk and stops it. Start a suspended virtual machine and restore the virtual machine state with the start action.

For example: 

POST /ovirt-engine/api/vms/123/suspend
Copy to Clipboard Toggle word wrap

The suspend action does not take any action specific parameters; therefore, the request body should contain an empty action: 

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.692. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the suspend action should be performed asynchronously.

6.220.19. thawfilesystems POST
Copy link

Thaws virtual machine file systems.

This operation thaws a virtual machine’s file systems using the QEMU guest agent when taking a live snapshot of a running virtual machine. Normally, this is done automatically by the manager, but this must be executed manually with the API for virtual machines using OpenStack Volume (Cinder) disks.

Example: 

POST /api/vms/123/thawfilesystems
Copy to Clipboard Toggle word wrap 
<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.693. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

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

6.220.20. ticket POST
Copy link

Generates a time-sensitive authentication token for accessing a virtual machine’s display.

For example: 

POST /ovirt-engine/api/vms/123/ticket
Copy to Clipboard Toggle word wrap

The client-provided action optionally includes a desired ticket value and/or an expiry time in seconds.

The response specifies the actual ticket value and expiry used. 

<action>
  <ticket>
    <value>abcd12345</value>
    <expiry>120</expiry>
  </ticket>
</action>
Copy to Clipboard Toggle word wrap
Important

If the virtual machine is configured to support only one graphics protocol then the generated authentication token will be valid for that protocol. But if the virtual machine is configured to support multiple protocols, VNC and SPICE, then the authentication token will only be valid for the SPICE protocol.

In order to obtain an authentication token for a specific protocol, for example for VNC, use the ticket method of the service, which manages the graphics consoles of the virtual machine, by sending a request: 

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/ticket
Copy to Clipboard Toggle word wrap
Expand
Table 6.694. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

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

ticket

Ticket

In/Out

 

6.220.21. undosnapshot POST
Copy link

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

See the preview_snapshot operation for details.

Expand
Table 6.695. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the undo snapshot action should be performed asynchronously.

6.220.22. update PUT
Copy link

Expand
Table 6.696. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

next_run

Boolean

In

Indicates if the update should be applied to the virtual machine immediately or if it should be applied only when the virtual machine is restarted.

vm

Vm

In/Out

 

6.220.22.1. next_run
Copy link

Indicates if the update should be applied to the virtual machine immediately or if it should be applied only when the virtual machine is restarted. The default value is false, so by default changes are applied immediately.

6.221. VmApplication
Copy link

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

Expand
Table 6.697. Methods summary
NameSummary

get

Returns the information about the application.

6.221.1. get GET
Copy link

Returns the information about the application.

Expand
Table 6.698. Parameters summary
NameTypeDirectionSummary

application

Application

Out

The information about the application.

filter

Boolean

In

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

6.221.1.1. application
Copy link

The information about the application.

The information consists of name attribute containing the name of the application (which is an arbitrary string that may also contain additional information such as version) and vm attribute identifying the virtual machine.

For example, a request like this: 

GET /ovirt-engine/api/vms/123/applications/789
Copy to Clipboard Toggle word wrap

May return information like this: 

<application href="/ovirt-engine/api/vms/123/applications/789" id="789">
  <name>ovirt-guest-agent-common-1.0.12-3.el7</name>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</application>
Copy to Clipboard Toggle word wrap

6.222. VmApplications
Copy link

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

Expand
Table 6.699. Methods summary
NameSummary

list

Returns a list of applications installed in the virtual machine.

6.222.1. list GET
Copy link

Returns a list of applications installed in the virtual machine.

Expand
Table 6.700. Parameters summary
NameTypeDirectionSummary

applications

Application[]

Out

A list of applications installed in the virtual machine.

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of applications to return.

6.222.1.1. applications
Copy link

A list of applications installed in the virtual machine.

For example, a request like this: 

GET /ovirt-engine/api/vms/123/applications/
Copy to Clipboard Toggle word wrap

May return a list like this: 

<applications>
  <application href="/ovirt-engine/api/vms/123/applications/456" id="456">
    <name>kernel-3.10.0-327.36.1.el7</name>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </application>
  <application href="/ovirt-engine/api/vms/123/applications/789" id="789">
    <name>ovirt-guest-agent-common-1.0.12-3.el7</name>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </application>
</applications>
Copy to Clipboard Toggle word wrap

6.222.1.2. max
Copy link

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

6.223. VmCdrom
Copy link

Manages a CDROM device of a virtual machine.

Changing and ejecting the disk is done using always the update method, to change the value of the file attribute.

Expand
Table 6.701. Methods summary
NameSummary

get

Returns the information about this CDROM device.

update

Updates the information about this CDROM device.

6.223.1. get GET
Copy link

Returns the information about this CDROM device.

The information consists of cdrom attribute containing reference to the CDROM device, the virtual machine, and optionally the inserted disk.

If there is a disk inserted then the file attribute will contain a reference to the ISO image: 

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <file id="mycd.iso"/>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</cdrom>
Copy to Clipboard Toggle word wrap

If there is no disk inserted then the file attribute won’t be reported: 

<cdrom href="..." id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</cdrom>
Copy to Clipboard Toggle word wrap
Expand
Table 6.702. Parameters summary
NameTypeDirectionSummary

cdrom

Cdrom

Out

The information about the CDROM device.

current

Boolean

In

Indicates if the operation should return the information for the currently running virtual machine.

6.223.1.1. current
Copy link

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

6.223.2. update PUT
Copy link

Updates the information about this CDROM device.

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

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000
Copy to Clipboard Toggle word wrap

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

<cdrom>
  <file id="mycd.iso"/>
</cdrom>
Copy to Clipboard Toggle word wrap

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

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

<cdrom>
  <file id=""/>
</cdrom>
Copy to Clipboard Toggle word wrap

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

PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000?current=true
Copy to Clipboard Toggle word wrap

With a request body like this: 

<cdrom>
  <file id=""/>
</cdrom>
Copy to Clipboard Toggle word wrap
Important

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

Expand
Table 6.703. Parameters summary
NameTypeDirectionSummary

cdrom

Cdrom

In/Out

The information about the CDROM device.

current

Boolean

In

Indicates if the update should apply to the currently running virtual machine, or to the virtual machine after the next boot.

6.223.2.1. current
Copy link

Indicates if the update should apply to the currently running virtual machine, or to the virtual machine after the next boot. This parameter is optional, and the default value is false, which means that by default the update will have effect only after the next boot.

6.224. VmCdroms
Copy link

Manages the CDROM devices of a virtual machine.

Currently virtual machines have exactly one CDROM device. No new devices can be added, and the existing one can’t be removed, thus there are no add or remove methods. Changing and ejecting CDROM disks is done with the update method of the service that manages the CDROM device.

Expand
Table 6.704. Methods summary
NameSummary

list

Returns the list of CDROM devices of the virtual machine.

6.224.1. list GET
Copy link

Returns the list of CDROM devices of the virtual machine.

Expand
Table 6.705. Parameters summary
NameTypeDirectionSummary

cdroms

Cdrom[]

Out

The list of CDROM devices of the virtual machine.

max

Integer

In

Sets the maximum number of CDROMs to return.

6.224.1.1. max
Copy link

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

6.225. VmDisk
Copy link

Expand
Table 6.706. Methods summary
NameSummary

activate

 

deactivate

 

export

 

get

 

move

 

remove

Detach the disk from the virtual machine.

update

 

6.225.1. activate POST
Copy link

Expand
Table 6.707. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.225.2. deactivate POST
Copy link

Expand
Table 6.708. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

6.225.3. export POST
Copy link

Expand
Table 6.709. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the export should be performed asynchronously.

filter

Boolean

In

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

6.225.4. get GET
Copy link

Expand
Table 6.710. Parameters summary
NameTypeDirectionSummary

disk

Disk

Out

 

6.225.5. move POST
Copy link

Expand
Table 6.711. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the move should be performed asynchronously.

filter

Boolean

In

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

6.225.6. remove DELETE
Copy link

Detach the disk from the virtual machine.

Note

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

Expand
Table 6.712. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.225.7. update PUT
Copy link

Expand
Table 6.713. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

disk

Disk

In/Out

 

6.226. VmDisks
Copy link

Expand
Table 6.714. Methods summary
NameSummary

add

 

list

 

6.226.1. add POST
Copy link

Expand
Table 6.715. Parameters summary
NameTypeDirectionSummary

disk

Disk

In/Out

 

6.226.2. list GET
Copy link

Expand
Table 6.716. Parameters summary
NameTypeDirectionSummary

disks

Disk[]

Out

 

max

Integer

In

Sets the maximum number of disks to return.

6.226.2.1. max
Copy link

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

6.227. VmGraphicsConsole
Copy link

Expand
Table 6.717. Methods summary
NameSummary

get

Gets graphics console configuration of the virtual machine.

proxyticket

 

remoteviewerconnectionfile

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

remove

Remove the graphics console from the virtual machine.

ticket

Generates a time-sensitive authentication token for accessing this virtual machine’s console.

6.227.1. get GET
Copy link

Gets graphics console configuration of the virtual machine.

Expand
Table 6.718. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

Out

The information about the graphics console of the virtual machine.

current

Boolean

In

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

6.227.1.1. current
Copy link

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

GET /ovit-engine/api/vms/123/graphicsconsoles/456?current=true
Copy to Clipboard Toggle word wrap

The default value is false.

6.227.2. proxyticket POST
Copy link

Expand
Table 6.719. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

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

proxy_ticket

ProxyTicket

Out

 

6.227.3. remoteviewerconnectionfile POST
Copy link

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

Use the following request to generate remote viewer connection file of the graphics console. Note that this action generates the file only if virtual machine is running. 

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/remoteviewerconnectionfile
Copy to Clipboard Toggle word wrap

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

<action/>
Copy to Clipboard Toggle word wrap

The response contains the file, which can be used with remote-viewer client. 

<action>
  <remote_viewer_connection_file>
    [virt-viewer]
    type=spice
    host=192.168.1.101
    port=-1
    password=123456789
    delete-this-file=1
    fullscreen=0
    toggle-fullscreen=shift+f11
    release-cursor=shift+f12
    secure-attention=ctrl+alt+end
    tls-port=5900
    enable-smartcard=0
    enable-usb-autoshare=0
    usb-filter=null
    tls-ciphers=DEFAULT
    host-subject=O=local,CN=example.com
    ca=...
  </remote_viewer_connection_file>
</action>
Copy to Clipboard Toggle word wrap

E.g., to fetch the content of remote viewer connection file and save it into temporary file, user can use oVirt Python SDK as follows: 

# Find the virtual machine:
vm = vms_service.list(search='name=myvm')[0]

# Locate the service that manages the virtual machine, as that is where
# the locators are defined:
vm_service = vms_service.vm_service(vm.id)

# Find the graphic console of the virtual machine:
graphics_consoles_service = vm_service.graphics_consoles_service()
graphics_console = graphics_consoles_service.list()[0]

# Generate the remote viewer connection file:
console_service = graphics_consoles_service.console_service(graphics_console.id)
remote_viewer_connection_file = console_service.remote_viewer_connection_file()

# Write the content to file "/tmp/remote_viewer_connection_file.vv"
path = "/tmp/remote_viewer_connection_file.vv"
with open(path, "w") as f:
    f.write(remote_viewer_connection_file)
Copy to Clipboard Toggle word wrap

When you create the remote viewer connection file, then you can connect to virtual machine graphic console, as follows: 

#!/bin/sh -ex

remote-viewer --ovirt-ca-file=/etc/pki/ovirt-engine/ca.pem /tmp/remote_viewer_connection_file.vv
Copy to Clipboard Toggle word wrap
Expand
Table 6.720. Parameters summary
NameTypeDirectionSummary

remote_viewer_connection_file

String

Out

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

6.227.3.1. remote_viewer_connection_file
Copy link

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

User can use the content of this attribute to create a file, which can be passed to remote-viewer client to connect to virtual machine graphic console.

6.227.4. remove DELETE
Copy link

Remove the graphics console from the virtual machine.

Expand
Table 6.721. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.227.5. ticket POST
Copy link

Generates a time-sensitive authentication token for accessing this virtual machine’s console. 

POST /ovirt-engine/api/vms/123/graphicsconsoles/456/ticket
Copy to Clipboard Toggle word wrap

The client-provided action optionally includes a desired ticket value and/or an expiry time in seconds.

In any case, the response specifies the actual ticket value and expiry used. 

<action>
  <ticket>
    <value>abcd12345</value>
    <expiry>120</expiry>
  </ticket>
</action>
Copy to Clipboard Toggle word wrap
Expand
Table 6.722. Parameters summary
NameTypeDirectionSummary

ticket

Ticket

In/Out

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

6.228. VmGraphicsConsoles
Copy link

Expand
Table 6.723. Methods summary
NameSummary

add

Add new graphics console to the virtual machine.

list

Lists all the configured graphics consoles of the virtual machine.

6.228.1. add POST
Copy link

Add new graphics console to the virtual machine.

Expand
Table 6.724. Parameters summary
NameTypeDirectionSummary

console

GraphicsConsole

In/Out

 

6.228.2. list GET
Copy link

Lists all the configured graphics consoles of the virtual machine.

Expand
Table 6.725. Parameters summary
NameTypeDirectionSummary

consoles

GraphicsConsole[]

Out

The list of graphics consoles of the virtual machine.

current

Boolean

In

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

max

Integer

In

Sets the maximum number of consoles to return.

6.228.2.1. current
Copy link

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

GET /ovirt-engine/api/vms/123/graphicsconsoles?current=true
Copy to Clipboard Toggle word wrap

The default value is false.

6.228.2.2. max
Copy link

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

6.229. VmHostDevice
Copy link

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

Expand
Table 6.726. Methods summary
NameSummary

get

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

remove

Remove the attachment of this host device from given virtual machine.

6.229.1. get GET
Copy link

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

Example: 

GET /ovirt-engine/api/vms/123/hostdevices/456
Copy to Clipboard Toggle word wrap 
<host_device href="/ovirt-engine/api/hosts/543/devices/456" id="456">
  <name>pci_0000_04_00_0</name>
  <capability>pci</capability>
  <iommu_group>30</iommu_group>
  <placeholder>true</placeholder>
  <product id="0x13ba">
    <name>GM107GL [Quadro K2200]</name>
  </product>
  <vendor id="0x10de">
    <name>NVIDIA Corporation</name>
  </vendor>
  <host href="/ovirt-engine/api/hosts/543" id="543"/>
  <parent_device href="/ovirt-engine/api/hosts/543/devices/456" id="456">
    <name>pci_0000_00_03_0</name>
  </parent_device>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</host_device>
Copy to Clipboard Toggle word wrap
Expand
Table 6.727. Parameters summary
NameTypeDirectionSummary

device

HostDevice

Out

Retrieved information about the host device attached to given virtual machine.

6.229.2. remove DELETE
Copy link

Remove the attachment of this host device from given virtual machine.

Note

In case this device serves as an IOMMU placeholder, it cannot be removed (remove will result only in setting its placeholder flag to true). Note that all IOMMU placeholder devices will be removed automatically as soon as there will be no more non-placeholder devices (all devices from given IOMMU group are detached). 

DELETE /ovirt-engine/api/vms/123/hostdevices/456
Copy to Clipboard Toggle word wrap
Expand
Table 6.728. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.230. VmHostDevices
Copy link

A service to manage host devices attached to a virtual machine.

Expand
Table 6.729. Methods summary
NameSummary

add

Attach target device to given virtual machine.

list

List the host devices assigned to given virtual machine.

6.230.1. add POST
Copy link

Attach target device to given virtual machine.

Example: 

POST /ovirt-engine/api/vms/123/hostdevices
Copy to Clipboard Toggle word wrap

With request body of type HostDevice, for example 

<host_device id="123" />
Copy to Clipboard Toggle word wrap
Note

A necessary precondition for a successful host device attachment is that the virtual machine must be pinned to exactly one host. The device ID is then taken relative to this host.

Note

Attachment of a PCI device that is part of a bigger IOMMU group will result in attachment of the remaining devices from that IOMMU group as "placeholders". These devices are then identified using the placeholder attribute of the HostDevice type set to true.

In case you want attach a device that already serves as an IOMMU placeholder, simply issue an explicit Add operation for it, and its placeholder flag will be cleared, and the device will be accessible to the virtual machine.

Expand
Table 6.730. Parameters summary
NameTypeDirectionSummary

device

HostDevice

In/Out

The host device to be attached to given virtual machine.

6.230.2. list GET
Copy link

List the host devices assigned to given virtual machine.

Expand
Table 6.731. Parameters summary
NameTypeDirectionSummary

device

HostDevice[]

Out

Retrieved list of host devices attached to given virtual machine.

max

Integer

In

Sets the maximum number of devices to return.

6.230.2.1. max
Copy link

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

6.231. VmNic
Copy link

Expand
Table 6.732. Methods summary
NameSummary

activate

 

deactivate

 

get

 

remove

Removes the NIC.

update

Updates the NIC.

6.231.1. activate POST
Copy link

Expand
Table 6.733. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the activation should be performed asynchronously.

6.231.2. deactivate POST
Copy link

Expand
Table 6.734. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the deactivation should be performed asynchronously.

6.231.3. get GET
Copy link

Expand
Table 6.735. Parameters summary
NameTypeDirectionSummary

nic

Nic

Out

 

6.231.4. remove DELETE
Copy link

Removes the NIC.

For example, to remove the NIC with id 456 from the virtual machine with id 123 send a request like this: 

DELETE /ovirt-engine/api/vms/123/nics/456
Copy to Clipboard Toggle word wrap
Important

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Windows Server 2008 and
  • Windows Server 2003
Expand
Table 6.736. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.231.5. update PUT
Copy link

Updates the NIC.

For example, to update the NIC having with 456 belonging to virtual the machine with id 123 send a request like this: 

PUT /ovirt-engine/api/vms/123/nics/456
Copy to Clipboard Toggle word wrap

With a request body like this: 

<nic>
  <name>mynic</name>
  <interface>e1000</interface>
  <vnic_profile id='789'/>
</nic>
Copy to Clipboard Toggle word wrap
Important

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Windows Server 2008 and
  • Windows Server 2003
Expand
Table 6.737. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

nic

Nic

In/Out

 

6.232. VmNics
Copy link

Expand
Table 6.738. Methods summary
NameSummary

add

Adds a NIC to the virtual machine.

list

 

6.232.1. add POST
Copy link

Adds a NIC to the virtual machine.

The following example adds a network interface named mynic using virtio and the ovirtmgmt network to the virtual machine. 

POST /ovirt-engine/api/vms/123/nics
Copy to Clipboard Toggle word wrap 
<nic>
  <interface>virtio</interface>
  <name>mynic</name>
  <network>
    <name>ovirtmgmt</name>
  </network>
</nic>
Copy to Clipboard Toggle word wrap

The following example sends that request using curl: 

curl \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \
--cacert /etc/pki/ovirt-engine/ca.pem \
--data '
<nic>
  <name>mynic</name>
  <network>
    <name>ovirtmgmt</name>
  </network>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/123/nics
Copy to Clipboard Toggle word wrap
Important

The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include:

  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Windows Server 2008 and
  • Windows Server 2003
Expand
Table 6.739. Parameters summary
NameTypeDirectionSummary

nic

Nic

In/Out

 

6.232.2. list GET
Copy link

Expand
Table 6.740. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of NICs to return.

nics

Nic[]

Out

 

6.232.2.1. max
Copy link

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

6.233. VmNumaNode
Copy link

Expand
Table 6.741. Methods summary
NameSummary

get

 

remove

Removes a virtual NUMA node.

update

Updates a virtual NUMA node.

6.233.1. get GET
Copy link

Expand
Table 6.742. Parameters summary
NameTypeDirectionSummary

node

VirtualNumaNode

Out

 

6.233.2. remove DELETE
Copy link

Removes a virtual NUMA node.

An example of removing a virtual NUMA node: 

DELETE /ovirt-engine/api/vms/123/numanodes/456
Copy to Clipboard Toggle word wrap
Expand
Table 6.743. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.233.3. update PUT
Copy link

Updates a virtual NUMA node.

An example of pinning a virtual NUMA node to a physical NUMA node on the host: 

PUT /ovirt-engine/api/vms/123/numanodes/456
Copy to Clipboard Toggle word wrap

The request body should contain the following: 

<vm_numa_node>
  <numa_node_pins>
    <numa_node_pin>
      <index>0</index>
    </numa_node_pin>
  </numa_node_pins>
</vm_numa_node>
Copy to Clipboard Toggle word wrap
Expand
Table 6.744. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

node

VirtualNumaNode

In/Out

 

6.234. VmNumaNodes
Copy link

Expand
Table 6.745. Methods summary
NameSummary

add

Creates a new virtual NUMA node for the virtual machine.

list

Lists virtual NUMA nodes of a virtual machine.

6.234.1. add POST
Copy link

Creates a new virtual NUMA node for the virtual machine.

An example of creating a NUMA node: 

POST /ovirt-engine/api/vms/c7ecd2dc/numanodes
Accept: application/xml
Content-type: application/xml
Copy to Clipboard Toggle word wrap

The request body can contain the following: 

<vm_numa_node>
  <cpu>
    <cores>
      <core>
        <index>0</index>
      </core>
    </cores>
  </cpu>
  <index>0</index>
  <memory>1024</memory>
</vm_numa_node>
Copy to Clipboard Toggle word wrap
Expand
Table 6.746. Parameters summary
NameTypeDirectionSummary

node

VirtualNumaNode

In/Out

 

6.234.2. list GET
Copy link

Lists virtual NUMA nodes of a virtual machine.

Expand
Table 6.747. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of nodes to return.

nodes

VirtualNumaNode[]

Out

 

6.234.2.1. max
Copy link

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

6.235. VmPool
Copy link

A service to manage a virtual machines pool.

Expand
Table 6.748. Methods summary
NameSummary

allocatevm

This operation allocates a virtual machine in the virtual machine pool.

get

Get the virtual machine pool.

remove

Removes a virtual machine pool.

update

Update the virtual machine pool.

6.235.1. allocatevm POST
Copy link

This operation allocates a virtual machine in the virtual machine pool. 

POST /ovirt-engine/api/vmpools/123/allocatevm
Copy to Clipboard Toggle word wrap

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

<action/>
Copy to Clipboard Toggle word wrap
Expand
Table 6.749. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the allocation should be performed asynchronously.

6.235.2. get GET
Copy link

Get the virtual machine pool. 

GET /ovirt-engine/api/vmpools/123
Copy to Clipboard Toggle word wrap

You will get a XML response like that one: 

<vm_pool id="123">
  <actions>...</actions>
  <name>MyVmPool</name>
  <description>MyVmPool description</description>
  <link href="/ovirt-engine/api/vmpools/123/permissions" rel="permissions"/>
  <max_user_vms>1</max_user_vms>
  <prestarted_vms>0</prestarted_vms>
  <size>100</size>
  <stateful>false</stateful>
  <type>automatic</type>
  <use_latest_template_version>false</use_latest_template_version>
  <cluster id="123"/>
  <template id="123"/>
  <vm id="123">...</vm>
  ...
</vm_pool>
Copy to Clipboard Toggle word wrap
Expand
Table 6.750. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

pool

VmPool

Out

Retrieved virtual machines pool.

6.235.3. remove DELETE
Copy link

Removes a virtual machine pool. 

DELETE /ovirt-engine/api/vmpools/123
Copy to Clipboard Toggle word wrap
Expand
Table 6.751. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.235.4. update PUT
Copy link

Update the virtual machine pool. 

PUT /ovirt-engine/api/vmpools/123
Copy to Clipboard Toggle word wrap

The name, description, size, prestarted_vms and max_user_vms attributes can be updated after the virtual machine pool has been created. 

<vmpool>
  <name>VM_Pool_B</name>
  <description>Virtual Machine Pool B</description>
  <size>3</size>
  <prestarted_vms>1</size>
  <max_user_vms>2</size>
</vmpool>
Copy to Clipboard Toggle word wrap
Expand
Table 6.752. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

pool

VmPool

In/Out

The virtual machine pool that is being updated.

6.236. VmPools
Copy link

Provides read-write access to virtual machines pools.

Expand
Table 6.753. Methods summary
NameSummary

add

Creates a new virtual machine pool.

list

Get a list of available virtual machines pools.

6.236.1. add POST
Copy link

Creates a new virtual machine pool.

A new pool requires the name, cluster and template attributes. Identify the cluster and template with the id or name nested attributes: 

POST /ovirt-engine/api/vmpools
Copy to Clipboard Toggle word wrap

With the following body: 

<vmpool>
  <name>mypool</name>
  <cluster id="123"/>
  <template id="456"/>
</vmpool>
Copy to Clipboard Toggle word wrap
Expand
Table 6.754. Parameters summary
NameTypeDirectionSummary

pool

VmPool

In/Out

Pool to add.

6.236.2. list GET
Copy link

Get a list of available virtual machines pools. 

GET /ovirt-engine/api/vmpools
Copy to Clipboard Toggle word wrap

You will receive the following response: 

<vm_pools>
  <vm_pool id="123">
    ...
  </vm_pool>
  ...
</vm_pools>
Copy to Clipboard Toggle word wrap
Expand
Table 6.755. Parameters summary
NameTypeDirectionSummary

case_sensitive

Boolean

In

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

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of pools to return.

pools

VmPool[]

Out

Retrieved pools.

search

String

In

A query string used to restrict the returned pools.

6.236.2.1. case_sensitive
Copy link

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

6.236.2.2. max
Copy link

Sets the maximum number of pools to return. If this value is not specified, all of the pools are returned.

6.237. VmReportedDevice
Copy link

Expand
Table 6.756. Methods summary
NameSummary

get

 

6.237.1. get GET
Copy link

Expand
Table 6.757. Parameters summary
NameTypeDirectionSummary

reported_device

ReportedDevice

Out

 

6.238. VmReportedDevices
Copy link

Expand
Table 6.758. Methods summary
NameSummary

list

 

6.238.1. list GET
Copy link

Expand
Table 6.759. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of devices to return.

reported_device

ReportedDevice[]

Out

 

6.238.1.1. max
Copy link

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

6.239. VmSession
Copy link

Expand
Table 6.760. Methods summary
NameSummary

get

 

6.239.1. get GET
Copy link

Expand
Table 6.761. Parameters summary
NameTypeDirectionSummary

session

Session

Out

 

6.240. VmSessions
Copy link

Provides information about virtual machine user sessions.

Expand
Table 6.762. Methods summary
NameSummary

list

Lists all user sessions for this virtual machine.

6.240.1. list GET
Copy link

Lists all user sessions for this virtual machine.

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

GET /ovirt-engine/api/vms/123/sessions
Copy to Clipboard Toggle word wrap

The response body will contain something like this: 

<sessions>
  <session href="/ovirt-engine/api/vms/123/sessions/456" id="456">
    <console_user>true</console_user>
    <ip>
      <address>192.168.122.1</address>
    </ip>
    <user href="/ovirt-engine/api/users/789" id="789"/>
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
  </session>
  ...
</sessions>
Copy to Clipboard Toggle word wrap
Expand
Table 6.763. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of sessions to return.

sessions

Session[]

Out

 

6.240.1.1. max
Copy link

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

6.241. VmWatchdog
Copy link

A service managing a watchdog on virtual machines.

Expand
Table 6.764. Methods summary
NameSummary

get

Returns the information about the watchdog.

remove

Removes the watchdog from the virtual machine.

update

Updates the information about the watchdog.

6.241.1. get GET
Copy link

Returns the information about the watchdog.

Expand
Table 6.765. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

Out

The information about the watchdog.

6.241.1.1. watchdog
Copy link

The information about the watchdog.

The information consists of model element, action element and the reference to the virtual machine. It may look like this: 

<watchdogs>
  <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
    <action>poweroff</action>
    <model>i6300esb</model>
  </watchdog>
</watchdogs>
Copy to Clipboard Toggle word wrap

6.241.2. remove DELETE
Copy link

Removes the watchdog from the virtual machine.

For example, to remove a watchdog from a virtual machine, send a request like this: 

DELETE /ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000
Copy to Clipboard Toggle word wrap
Expand
Table 6.766. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.241.3. update PUT
Copy link

Updates the information about the watchdog.

You can update the information using action and model elements.

For example, to update a watchdog, send a request like this: 

PUT /ovirt-engine/api/vms/123/watchdogs
<watchdog>
  <action>reset</action>
</watchdog>
Copy to Clipboard Toggle word wrap

with response body: 

<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
  <action>reset</action>
  <model>i6300esb</model>
</watchdog>
Copy to Clipboard Toggle word wrap
Expand
Table 6.767. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

watchdog

Watchdog

In/Out

The information about the watchdog.

6.241.3.1. watchdog
Copy link

The information about the watchdog.

The request data must contain at least one of model and action elements. The response data contains complete information about the updated watchdog.

6.242. VmWatchdogs
Copy link

Lists the watchdogs of a virtual machine.

Expand
Table 6.768. Methods summary
NameSummary

add

Adds new watchdog to the virtual machine.

list

The list of watchdogs of the virtual machine.

6.242.1. add POST
Copy link

Adds new watchdog to the virtual machine.

For example, to add a watchdog to a virtual machine, send a request like this: 

POST /ovirt-engine/api/vms/123/watchdogs
<watchdog>
  <action>poweroff</action>
  <model>i6300esb</model>
</watchdog>
Copy to Clipboard Toggle word wrap

with response body: 

<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
  <action>poweroff</action>
  <model>i6300esb</model>
</watchdog>
Copy to Clipboard Toggle word wrap
Expand
Table 6.769. Parameters summary
NameTypeDirectionSummary

watchdog

Watchdog

In/Out

The information about the watchdog.

6.242.1.1. watchdog
Copy link

The information about the watchdog.

The request data must contain model element (such as i6300esb) and action element (one of none, reset, poweroff, dump, pause). The response data additionally contains references to the added watchdog and to the virtual machine.

6.242.2. list GET
Copy link

The list of watchdogs of the virtual machine.

Expand
Table 6.770. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of watchdogs to return.

watchdogs

Watchdog[]

Out

The information about the watchdog.

6.242.2.1. max
Copy link

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

6.242.2.2. watchdogs
Copy link

The information about the watchdog.

The information consists of model element, action element and the reference to the virtual machine. It may look like this: 

<watchdogs>
  <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <vm href="/ovirt-engine/api/vms/123" id="123"/>
    <action>poweroff</action>
    <model>i6300esb</model>
  </watchdog>
</watchdogs>
Copy to Clipboard Toggle word wrap

6.243. Vms
Copy link

Expand
Table 6.771. Methods summary
NameSummary

add

Creates a new virtual machine.

list

 

6.243.1. add POST
Copy link

Creates a new virtual machine.

The virtual machine can be created in different ways:

  • From a template. In this case the identifier or name of the template must be provided. For example, using a plain shell script and XML: 
#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
  <name>myvm</name>
  <template>
    <name>Blank</name>
  </template>
  <cluster>
    <name>mycluster</name>
  </cluster>
</vm>
' \
"${url}/vms"
Copy to Clipboard Toggle word wrap
  • From a snapshot. In this case the identifier of the snapshot has to be provided. For example, using a plain shel script and XML: 
#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
  <name>myvm</name>
  <snapshots>
    <snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/>
  </snapshots>
  <cluster>
    <name>mycluster</name>
  </cluster>
</vm>
' \
"${url}/vms"
Copy to Clipboard Toggle word wrap

When creating a virtual machine from a template or from a snapshot it is usually useful to explicitly indicate in what storage domain to create the disks for the virtual machine. If the virtual machine is created from a template then this is achieved passing a set of disk_attachment elements that indicate the mapping: 

<vm>
  ...
  <disk_attachments>
    <disk_attachment>
      <disk id="8d4bd566-6c86-4592-a4a7-912dbf93c298">
        <storage_domains>
          <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
        </storage_domains>
      </disk>
    <disk_attachment>
  </disk_attachments>
</vm>
Copy to Clipboard Toggle word wrap

When the virtual machine is created from a snapshot this set of disks is slightly different, it uses the image_id attribute instead of id. 

<vm>
  ...
  <disk_attachments>
    <disk_attachment>
      <disk>
        <image_id>8d4bd566-6c86-4592-a4a7-912dbf93c298</image_id>
        <storage_domains>
          <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
        </storage_domains>
      </disk>
    <disk_attachment>
  </disk_attachments>
</vm>
Copy to Clipboard Toggle word wrap

It is possible to specify additional virtual machine parameters in the XML description, e.g. a virtual machine of desktop type, with 2 GiB of RAM and additional description can be added sending a request body like the following: 

<vm>
  <name>myvm</name>
  <description>My Desktop Virtual Machine</description>
  <type>desktop</type>
  <memory>2147483648</memory>
  ...
</vm>
Copy to Clipboard Toggle word wrap

A bootable CDROM device can be set like this: 

<vm>
  ...
  <os>
    <boot dev="cdrom"/>
  </os>
</vm>
Copy to Clipboard Toggle word wrap

In order to boot from CDROM, you first need to insert a disk, as described in the CDROM service. Then booting from that CDROM can be specified using the os.boot.devices attribute: 

<vm>
  ...
  <os>
    <boot>
      <devices>
        <device>cdrom</device>
      </devices>
    </boot>
  </os>
</vm>
Copy to Clipboard Toggle word wrap

In all cases the name or identifier of the cluster where the virtual machine will be created is mandatory.

Expand
Table 6.772. Parameters summary
NameTypeDirectionSummary

clone

Boolean

In

Specifies if the virtual machine should be independent of the template.

clone_permissions

Boolean

In

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

vm

Vm

In/Out

 

6.243.1.1. clone
Copy link

Specifies if the virtual machine should be independent of the template.

When a virtual machine is created from a template by default the disks of the virtual machine depend on the disks of the template, they are using the copy on write mechanism so that only the differences from the template take up real storage space. If this parameter is specified and the value is true then the disks of the created virtual machine will be cloned, and independent of the template. For example, to create an independent virtual machine, send a request like this: 

POST /ovirt-engine/vms?clone=true
Copy to Clipboard Toggle word wrap

With a request body like this: 

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
Copy to Clipboard Toggle word wrap
Note

When this parameter is true the permissions of the template will also be copied, as when using clone_permissions=true.

6.243.1.2. clone_permissions
Copy link

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

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

POST /ovirt-engine/api/vms?clone_permissions=true
Copy to Clipboard Toggle word wrap

With a request body like this: 

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
Copy to Clipboard Toggle word wrap

6.243.2. list GET
Copy link

Expand
Table 6.773. Parameters summary
NameTypeDirectionSummary

all_content

Boolean

In

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

case_sensitive

Boolean

In

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

filter

Boolean

In

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

max

Integer

In

The maximum number of results to return.

search

String

In

A query string used to restrict the returned virtual machines.

vms

Vm[]

Out

 

6.243.2.1. all_content
Copy link

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

By default the following attributes are excluded:

  • console
  • initialization.configuration.data - The OVF document describing the virtual machine.
  • rng_source
  • soundcard
  • virtio_scsi

For example, to retrieve the complete representation of the virtual machines send a request like this: 

GET /ovirt-engine/api/vms?all_content=true
Copy to Clipboard Toggle word wrap
Note

The reason for not including these attributes is performance: they are seldom used and they require additional queries to the database. So try to use the this parameter only when it is really needed.

6.243.2.2. case_sensitive
Copy link

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

6.244. VnicProfile
Copy link

This service manages a vNIC profile.

Expand
Table 6.774. Methods summary
NameSummary

get

Retrieves details about a vNIC profile.

remove

Removes the vNIC profile.

update

Updates details of a vNIC profile.

6.244.1. get GET
Copy link

Retrieves details about a vNIC profile.

Expand
Table 6.775. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

Out

 

6.244.2. remove DELETE
Copy link

Removes the vNIC profile.

Expand
Table 6.776. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.244.3. update PUT
Copy link

Updates details of a vNIC profile.

Expand
Table 6.777. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the update should be performed asynchronously.

profile

VnicProfile

In/Out

The vNIC profile that is being updated.

6.245. VnicProfiles
Copy link

This service manages the collection of all vNIC profiles.

Expand
Table 6.778. Methods summary
NameSummary

add

Add a vNIC profile.

list

List all vNIC profiles.

6.245.1. add POST
Copy link

Add a vNIC profile.

For example to add vNIC profile 123 to network 456 send a request to: 

POST /ovirt-engine/api/networks/456/vnicprofiles
Copy to Clipboard Toggle word wrap

With the following body: 

<vnic_profile id="123">
  <name>new_vNIC_name</name>
  <pass_through>
    <mode>disabled</mode>
  </pass_through>
  <port_mirroring>false</port_mirroring>
</vnic_profile>
Copy to Clipboard Toggle word wrap

Please note that there is a default network filter to each VNIC profile. For more details of how the default network filter is calculated please refer to the documentation in NetworkFilters.

The output of creating a new VNIC profile depends in the body arguments that were given. In case no network filter was given, the default network filter will be configured. For example: 

<vnic_profile href="/ovirt-engine/api/vnicprofiles/123" id="123">
  <name>new_vNIC_name</name>
  <link href="/ovirt-engine/api/vnicprofiles/123/permissions" rel="permissions"/>
  <pass_through>
    <mode>disabled</mode>
  </pass_through>
  <port_mirroring>false</port_mirroring>
  <network href="/ovirt-engine/api/networks/456" id="456"/>
  <network_filter href="/ovirt-engine/api/networkfilters/789" id="789"/>
</vnic_profile>
Copy to Clipboard Toggle word wrap

In case an empty network filter was given, no network filter will be configured for the specific VNIC profile regardless of the VNIC profile’s default network filter. For example: 

<vnic_profile>
  <name>no_network_filter</name>
  <network_filter/>
</vnic_profile>
Copy to Clipboard Toggle word wrap

In case that a specific valid network filter id was given, the VNIC profile will be configured with the given network filter regardless of the VNIC profiles’s default network filter. For example: 

<vnic_profile>
  <name>user_choice_network_filter</name>
  <network_filter id= "0000001b-001b-001b-001b-0000000001d5"/>
</vnic_profile>
Copy to Clipboard Toggle word wrap
Expand
Table 6.779. Parameters summary
NameTypeDirectionSummary

profile

VnicProfile

In/Out

The vNIC profile that is being added.

6.245.2. list GET
Copy link

List all vNIC profiles.

Expand
Table 6.780. Parameters summary
NameTypeDirectionSummary

max

Integer

In

Sets the maximum number of profiles to return.

profiles

VnicProfile[]

Out

The list of all vNIC profiles.

6.245.2.1. max
Copy link

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

6.246. Weight
Copy link

Expand
Table 6.781. Methods summary
NameSummary

get

 

remove

 

6.246.1. get GET
Copy link

Expand
Table 6.782. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

weight

Weight

Out

 

6.246.2. remove DELETE
Copy link

Expand
Table 6.783. Parameters summary
NameTypeDirectionSummary

async

Boolean

In

Indicates if the remove should be performed asynchronously.

6.247. Weights
Copy link

Expand
Table 6.784. Methods summary
NameSummary

add

 

list

 

6.247.1. add POST
Copy link

Expand
Table 6.785. Parameters summary
NameTypeDirectionSummary

weight

Weight

In/Out

 

6.247.2. list GET
Copy link

Expand
Table 6.786. Parameters summary
NameTypeDirectionSummary

filter

Boolean

In

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

max

Integer

In

Sets the maximum number of weights to return.

weights

Weight[]

Out

 

6.247.2.1. max
Copy link

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

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat