Chapter 6. Services Red Hat Virtualization 4.4

6.1. AffinityGroup

This service manages a single affinity group.

Table 6.1. Methods summary

Name	Summary
`get`	Retrieve the affinity group details.
`remove`	Remove the affinity group.
`update`	Update the affinity group.

6.1.1. get GET

Retrieve the affinity group details.

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

Table 6.2. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`group`	AffinityGroup	Out	The affinity group.

6.1.1.1. follow

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

6.1.2. remove DELETE

Remove the affinity group.

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

Table 6.3. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the removal should be performed asynchronously.

6.1.3. update PUT

Update the affinity group.

Table 6.4. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the update should be performed asynchronously.
`group`	AffinityGroup	In/Out	The affinity group.

6.2. AffinityGroupHost

This service manages a single host to affinity group assignment.

Table 6.5. Methods summary

Name	Summary
`remove`	Remove host from the affinity group.

6.2.1. remove DELETE

Remove host from the affinity group.

Table 6.6. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the removal should be performed asynchronously.

6.3. AffinityGroupHostLabel

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

Table 6.7. Methods summary

Name	Summary
`remove`	Remove this label from the affinity group.

6.3.1. remove DELETE

Remove this label from the affinity group.

Table 6.8. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the removal should be performed asynchronously.

6.4. AffinityGroupHostLabels

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

Table 6.9. Methods summary

Name	Summary
`add`	Adds a host label to the affinity group.
`list`	List all host labels assigned to this affinity group.

6.4.1. add POST

Adds a host label to the affinity group.

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

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

With the following body:

<affinity_label id="789"/>

Table 6.10. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	In/Out	The AffinityLabel object to add to the affinity group.

6.4.2. list GET

List all host labels assigned to this affinity group.

The order of the returned labels isn’t guaranteed.

Table 6.11. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`labels`	AffinityLabel[]	Out	Host labels assigned to the affinity group.
`max`	Integer	In	Sets the maximum number of host labels to return.

6.4.2.1. follow

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

6.4.2.2. max

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

6.5. AffinityGroupHosts

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

Table 6.12. Methods summary

Name	Summary
`add`	Adds a host to the affinity group.
`list`	List all hosts assigned to this affinity group.

6.5.1. add POST

Adds a host to the affinity group.

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

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

With the following body:

<host id="789"/>

Table 6.13. Parameters summary

Name	Type	Direction	Summary
`host`	Host	In/Out	The host to be added to the affinity group.

6.5.2. list GET

List all hosts assigned to this affinity group.

The order of the returned hosts isn’t guaranteed.

Table 6.14. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`hosts`	Host[]	Out	The list of hosts assigned to this affinity group.
`max`	Integer	In	Sets the maximum number of hosts to return.

6.5.2.1. follow

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

6.5.2.2. max

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

6.6. AffinityGroupVm

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

Table 6.15. Methods summary

Name	Summary
`remove`	Remove this virtual machine from the affinity group.

6.6.1. remove DELETE

Remove this virtual machine from the affinity group.

Table 6.16. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the removal should be performed asynchronously.

6.7. AffinityGroupVmLabel

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

Table 6.17. Methods summary

Name	Summary
`remove`	Remove this label from the affinity group.

6.7.1. remove DELETE

Remove this label from the affinity group.

Table 6.18. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the removal should be performed asynchronously.

6.8. AffinityGroupVmLabels

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

Table 6.19. Methods summary

Name	Summary
`add`	Adds a virtual machine label to the affinity group.
`list`	List all virtual machine labels assigned to this affinity group.

6.8.1. add POST

Adds a virtual machine label to the affinity group.

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

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

With the following body:

<affinity_label id="789"/>

Table 6.20. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	In/Out	The AffinityLabel object to add to the affinity group.

6.8.2. list GET

List all virtual machine labels assigned to this affinity group.

The order of the returned labels isn’t guaranteed.

Table 6.21. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`labels`	AffinityLabel[]	Out	Virtual machine labels assigned to the affinity group.
`max`	Integer	In	Sets the maximum number of virtual machine labels to return.

6.8.2.1. follow

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

6.8.2.2. max

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

6.9. AffinityGroupVms

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

Table 6.22. Methods summary

Name	Summary
`add`	Adds a virtual machine to the affinity group.
`list`	List all virtual machines assigned to this affinity group.

6.9.1. add POST

Adds a virtual machine to the affinity group.

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

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

With the following body:

<vm id="789"/>

Table 6.23. Parameters summary

Name	Type	Direction	Summary
`vm`	Vm	In/Out

6.9.2. list GET

List all virtual machines assigned to this affinity group.

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

Table 6.24. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of virtual machines to return.
`vms`	Vm[]	Out

6.9.2.1. follow

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

6.9.2.2. max

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

6.10. AffinityGroups

The affinity groups service manages virtual machine relationships and dependencies.

Table 6.25. Methods summary

Name	Summary
`add`	Create a new affinity group.
`list`	List existing affinity groups.

6.10.1. add POST

Create a new affinity group.

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

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

And use the following example in its body:

<affinity_group>
  <name>AF_GROUP_001</name>
  <hosts_rule>
    <enforcing>true</enforcing>
    <positive>true</positive>
  </hosts_rule>
  <vms_rule>
    <enabled>false</enabled>
  </vms_rule>
</affinity_group>

Table 6.26. Parameters summary

Name	Type	Direction	Summary
`group`	AffinityGroup	In/Out	The affinity group object to create.

6.10.2. list GET

List existing affinity groups.

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

Table 6.27. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`groups`	AffinityGroup[]	Out	The list of existing affinity groups.
`max`	Integer	In	Sets the maximum number of affinity groups to return.

6.10.2.1. follow

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

6.10.2.2. max

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

6.11. AffinityLabel

The details of a single affinity label.

Table 6.28. Methods summary

Name	Summary
`get`	Retrieves the details of a label.
`remove`	Removes a label from the system and clears all assignments of the removed label.
`update`	Updates a label.

6.11.1. get GET

Retrieves the details of a label.

Table 6.29. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`label`	AffinityLabel	Out

6.11.1.1. follow

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

6.11.2. remove DELETE

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

6.11.3. update PUT

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

Table 6.30. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	In/Out

6.12. AffinityLabelHost

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

Table 6.31. Methods summary

Name	Summary
`get`	Retrieves details about a host that has this label assigned.
`remove`	Remove a label from a host.

6.12.1. get GET

Retrieves details about a host that has this label assigned.

Table 6.32. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`host`	Host	Out

6.12.1.1. follow

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

6.12.2. remove DELETE

Remove a label from a host.

6.13. AffinityLabelHosts

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

Table 6.33. Methods summary

Name	Summary
`add`	Add a label to a host.
`list`	List all hosts with the label.

6.13.1. add POST

Add a label to a host.

Table 6.34. Parameters summary

Name	Type	Direction	Summary
`host`	Host	In/Out

6.13.2. list GET

List all hosts with the label.

The order of the returned hosts isn’t guaranteed.

Table 6.35. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`hosts`	Host[]	Out

6.13.2.1. follow

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

6.14. AffinityLabelVm

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

Table 6.36. Methods summary

Name	Summary
`get`	Retrieves details about a vm that has this label assigned.
`remove`	Remove a label from a vm.

6.14.1. get GET

Retrieves details about a vm that has this label assigned.

Table 6.37. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`vm`	Vm	Out

6.14.1.1. follow

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

6.14.2. remove DELETE

Remove a label from a vm.

6.15. AffinityLabelVms

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

Table 6.38. Methods summary

Name	Summary
`add`	Add a label to a vm.
`list`	List all virtual machines with the label.

6.15.1. add POST

Add a label to a vm.

Table 6.39. Parameters summary

Name	Type	Direction	Summary
`vm`	Vm	In/Out

6.15.2. list GET

List all virtual machines with the label.

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

Table 6.40. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`vms`	Vm[]	Out

6.15.2.1. follow

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

6.16. AffinityLabels

Manages the affinity labels available in the system.

Table 6.41. Methods summary

Name	Summary
`add`	Creates a new label.
`list`	Lists all labels present in the system.

6.16.1. add POST

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

Table 6.42. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	In/Out

6.16.2. list GET

Lists all labels present in the system.

The order of the returned labels isn’t guaranteed.

Table 6.43. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`labels`	AffinityLabel[]	Out
`max`	Integer	In	Sets the maximum number of labels to return.

6.16.2.1. follow

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

6.16.2.2. max

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

6.17. Area

This annotation is intended to specify what oVirt area is the annotated concept related to. Currently the following areas are in use, and they are closely related to the oVirt teams, but not necessarily the same:

Infrastructure
Network
SLA
Storage
Virtualization

A concept may be associated to more than one area, or to no area.

The value of this annotation is intended for reporting only, and it doesn’t affect at all the generated code or the validity of the model

6.18. AssignedAffinityLabel

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

Table 6.44. Methods summary

Name	Summary
`get`	Retrieves details about the attached label.
`remove`	Removes the label from an entity.

6.18.1. get GET

Retrieves details about the attached label.

Table 6.45. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`label`	AffinityLabel	Out

6.18.1.1. follow

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

6.18.2. remove DELETE

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

6.19. AssignedAffinityLabels

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

Table 6.46. Methods summary

Name	Summary
`add`	Attaches a label to an entity.
`list`	Lists all labels that are attached to an entity.

6.19.1. add POST

Attaches a label to an entity.

Table 6.47. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	In/Out

6.19.2. list GET

Lists all labels that are attached to an entity.

The order of the returned entities isn’t guaranteed.

Table 6.48. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`label`	AffinityLabel[]	Out

6.19.2.1. follow

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

6.20. AssignedCpuProfile

Table 6.49. Methods summary

Name	Summary
`get`
`remove`

6.20.1. get GET

Table 6.50. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`profile`	CpuProfile	Out

6.20.1.1. follow

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

6.20.2. remove DELETE

Table 6.51. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.21. AssignedCpuProfiles

Table 6.52. Methods summary

Name	Summary
`add`	Add a new cpu profile for the cluster.
`list`	List the CPU profiles assigned to the cluster.

6.21.1. add POST

Add a new cpu profile for the cluster.

Table 6.53. Parameters summary

Name	Type	Direction	Summary
`profile`	CpuProfile	In/Out

6.21.2. list GET

List the CPU profiles assigned to the cluster.

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

Table 6.54. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of profiles to return.
`profiles`	CpuProfile[]	Out

6.21.2.1. follow

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

6.21.2.2. max

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

6.22. AssignedDiskProfile

Table 6.55. Methods summary

Name	Summary
`get`
`remove`

6.22.1. get GET

Table 6.56. Parameters summary

Name	Type	Direction	Summary
`disk_profile`	DiskProfile	Out
`follow`	String	In	Indicates which inner links should be followed.

6.22.1.1. follow

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

6.22.2. remove DELETE

Table 6.57. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.23. AssignedDiskProfiles

Table 6.58. Methods summary

Name	Summary
`add`	Add a new disk profile for the storage domain.
`list`	Returns the list of disk profiles assigned to the storage domain.

6.23.1. add POST

Add a new disk profile for the storage domain.

Table 6.59. Parameters summary

Name	Type	Direction	Summary
`profile`	DiskProfile	In/Out

6.23.2. list GET

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

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

Table 6.60. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of profiles to return.
`profiles`	DiskProfile[]	Out

6.23.2.1. follow

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

6.23.2.2. max

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

6.24. AssignedPermissions

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

Table 6.61. Methods summary

Name	Summary
`add`	Assign a new permission to a user or group for specific entity.
`list`	List all the permissions of the specific entity.

6.24.1. add POST

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

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

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

With a request body like this:

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

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

POST /ovirt-engine/api/permissions

With a request body like this:

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

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

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

With a request body like this:

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

Table 6.62. Parameters summary

Name	Type	Direction	Summary
`permission`	Permission	In/Out	The permission.

6.24.2. list GET

List all the permissions of the specific entity.

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

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

<permissions>
  <permission id="456">
    <cluster id="123"/>
    <role id="789"/>
    <user id="451"/>
  </permission>
  <permission id="654">
    <cluster id="123"/>
    <role id="789"/>
    <group id="127"/>
  </permission>
</permissions>

The order of the returned permissions isn’t guaranteed.

Table 6.63. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`permissions`	Permission[]	Out	The list of permissions.

6.24.2.1. follow

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

6.25. AssignedRoles

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

Table 6.64. Methods summary

Name	Summary
`list`	Returns the roles assigned to the permission.

6.25.1. list GET

Returns the roles assigned to the permission.

The order of the returned roles isn’t guaranteed.

Table 6.65. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of roles to return.
`roles`	Role[]	Out

6.25.1.1. follow

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

6.25.1.2. max

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

6.26. AssignedTag

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

Table 6.66. Methods summary

Name	Summary
`get`	Gets the information about the assigned tag.
`remove`	Unassign tag from specific entity in the system.

6.26.1. get GET

Gets the information about the assigned tag.

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

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

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

Table 6.67. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`tag`	Tag	Out	The assigned tag.

6.26.1.1. follow

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

6.26.2. remove DELETE

Unassign tag from specific entity in the system.

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

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

Table 6.68. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.27. AssignedTags

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

Table 6.69. Methods summary

Name	Summary
`add`	Assign tag to specific entity in the system.
`list`	List all tags assigned to the specific entity.

6.27.1. add POST

Assign tag to specific entity in the system.

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

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

With a request body like this:

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

Table 6.70. Parameters summary

Name	Type	Direction	Summary
`tag`	Tag	In/Out	The assigned tag.

6.27.2. list GET

List all tags assigned to the specific entity.

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

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

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

The order of the returned tags isn’t guaranteed.

Table 6.71. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of tags to return.
`tags`	Tag[]	Out	The list of assigned tags.

6.27.2.1. follow

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

6.27.2.2. max

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

6.28. AssignedVnicProfile

Table 6.72. Methods summary

Name	Summary
`get`
`remove`

6.28.1. get GET

Table 6.73. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`profile`	VnicProfile	Out

6.28.1.1. follow

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

6.28.2. remove DELETE

Table 6.74. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.29. AssignedVnicProfiles

Table 6.75. Methods summary

Name	Summary
`add`	Add a new virtual network interface card profile for the network.
`list`	Returns the list of VNIC profiles assifned to the network.

6.29.1. add POST

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

Table 6.76. Parameters summary

Name	Type	Direction	Summary
`profile`	VnicProfile	In/Out

6.29.2. list GET

Returns the list of VNIC profiles assifned to the network.

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

Table 6.77. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of profiles to return.
`profiles`	VnicProfile[]	Out

6.29.2.1. follow

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

6.29.2.2. max

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

6.30. AttachedStorageDomain

Table 6.78. Methods summary

Name	Summary
`activate`	This operation activates an attached storage domain.
`deactivate`	This operation deactivates an attached storage domain.
`get`
`remove`

6.30.1. activate POST

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

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

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

<action/>

Table 6.79. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the activation should be performed asynchronously.

6.30.2. deactivate POST

This operation deactivates an attached storage domain. Once the storage domain is deactivated it will not be used with the data center. For example, to deactivate storage domain 456, send the following request:

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

With a request body like this:

<action/>

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

Table 6.80. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the deactivation should be performed asynchronously.
`force`	Boolean	In	Indicates if the operation should succeed and the storage domain should be moved to a deactivated state, even if the OVF update for the storage domain failed.

6.30.2.1. force

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

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

With a request body like this:

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

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

6.30.3. get GET

Table 6.81. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`storage_domain`	StorageDomain	Out

6.30.3.1. follow

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

6.30.4. remove DELETE

Table 6.82. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.31. AttachedStorageDomainDisk

Manages a single disk available in a storage domain attached to a data center.

Important

Since version 4.2 of the engine this service is intended only to list disks available in the storage domain, and to register unregistered disks. All the other operations, like copying a disk, moving a disk, etc, have been deprecated and will be removed in the future. To perform those operations use the service that manages all the disks of the system, or the service that manages an specific disk.

Table 6.83. Methods summary

Name	Summary
`copy`	Copies a disk to the specified storage domain.
`export`	Exports a disk to an export storage domain.
`get`	Retrieves the description of the disk.
`move`	Moves a disk to another storage domain.
`register`	Registers an unregistered disk.
`remove`	Removes a disk.
`sparsify`	Sparsify the disk.
`update`	Updates the disk.

6.31.1. copy POST

Copies a disk to the specified storage domain.

Important

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To copy a disk use the copy operation of the service that manages that disk.

Table 6.84. Parameters summary

Name	Type	Direction	Summary
`disk`	Disk	In	Description of the resulting disk.
`storage_domain`	StorageDomain	In	The storage domain where the new disk will be created.

6.31.2. export POST

Exports a disk to an export storage domain.

Important

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To export a disk use the export operation of the service that manages that disk.

Table 6.85. Parameters summary

Name	Type	Direction	Summary
`storage_domain`	StorageDomain	In	The export storage domain where the disk should be exported to.

6.31.3. get GET

Retrieves the description of the disk.

Table 6.86. Parameters summary

Name	Type	Direction	Summary
`disk`	Disk	Out	The description of the disk.
`follow`	String	In	Indicates which inner links should be followed.

6.31.3.1. follow

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

6.31.4. move POST

Moves a disk to another storage domain.

Important

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To move a disk use the move operation of the service that manages that disk.

Table 6.87. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the move should be performed asynchronously.
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`storage_domain`	StorageDomain	In	The storage domain where the disk will be moved to.

6.31.5. register POST

Registers an unregistered disk.

6.31.6. remove DELETE

Removes a disk.

Important

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk.

6.31.7. sparsify POST

Sparsify the disk.

Important

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk.

6.31.8. update PUT

Updates the disk.

Important

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To update a disk use the update operation of the service that manages that disk.

Table 6.88. Parameters summary

Name	Type	Direction	Summary
`disk`	Disk	In/Out	The update to apply to the disk.

6.32. AttachedStorageDomainDisks

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

Table 6.89. Methods summary

Name	Summary
`add`	Adds or registers a disk.
`list`	Retrieve the list of disks that are available in the storage domain.

6.32.1. add POST

Adds or registers a disk.

Important

Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To add a new disk use the add operation of the service that manages the disks of the system. To register an unregistered disk use the register operation of the service that manages that disk.

Table 6.90. Parameters summary

Name	Type	Direction	Summary
`disk`	Disk	In/Out	The disk to add or register.
`unregistered`	Boolean	In	Indicates if a new disk should be added or if an existing unregistered disk should be registered.

6.32.1.1. unregistered

Indicates if a new disk should be added or if an existing unregistered disk should be registered. If the value is true then the identifier of the disk to register needs to be provided. For example, to register the disk with id 456 send a request like this:

POST /ovirt-engine/api/storagedomains/123/disks?unregistered=true

With a request body like this:

<disk id="456"/>

If the value is false then a new disk will be created in the storage domain. In that case the provisioned_size, format and name attributes are mandatory. For example, to create a new copy on write disk of 1 GiB, send a request like this:

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

With a request body like this:

<disk>
  <name>mydisk</name>
  <format>cow</format>
  <provisioned_size>1073741824</provisioned_size>
</disk>

The default value is false.

6.32.2. list GET

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

Table 6.91. Parameters summary

Name	Type	Direction	Summary
`disks`	Disk[]	Out	List of retrieved disks.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of disks to return.

6.32.2.1. disks

List of retrieved disks.

The order of the returned disks isn’t guaranteed.

6.32.2.2. follow

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

6.32.2.3. max

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

6.33. AttachedStorageDomains

Manages the storage domains attached to a data center.

Table 6.92. Methods summary

Name	Summary
`add`	Attaches an existing storage domain to the data center.
`list`	Returns the list of storage domains attached to the data center.

6.33.1. add POST

Attaches an existing storage domain to the data center.

Table 6.93. Parameters summary

Name	Type	Direction	Summary
`storage_domain`	StorageDomain	In/Out	The storage domain to attach to the data center.

6.33.2. list GET

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

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

Table 6.94. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of storage domains to return.
`storage_domains`	StorageDomain[]	Out	A list of storage domains that are attached to the data center.

6.33.2.1. follow

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

6.33.2.2. max

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

6.34. Balance

Table 6.95. Methods summary

Name	Summary
`get`
`remove`

6.34.1. get GET

Table 6.96. Parameters summary

Name	Type	Direction	Summary
`balance`	Balance	Out
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`follow`	String	In	Indicates which inner links should be followed.

6.34.1.1. follow

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

6.34.2. remove DELETE

Table 6.97. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.35. Balances

Table 6.98. Methods summary

Name	Summary
`add`	Add a balance module to a specified user defined scheduling policy.
`list`	Returns the list of balance modules used by the scheduling policy.

6.35.1. add POST

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

Table 6.99. Parameters summary

Name	Type	Direction	Summary
`balance`	Balance	In/Out

6.35.2. list GET

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

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

Table 6.100. Parameters summary

Name	Type	Direction	Summary
`balances`	Balance[]	Out
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of balances to return.

6.35.2.1. follow

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

6.35.2.2. max

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

6.36. Bookmark

A service to manage a bookmark.

Table 6.101. Methods summary

Name	Summary
`get`	Get a bookmark.
`remove`	Remove a bookmark.
`update`	Update a bookmark.

6.36.1. get GET

Get a bookmark.

An example for getting a bookmark:

GET /ovirt-engine/api/bookmarks/123

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

Table 6.102. Parameters summary

Name	Type	Direction	Summary
`bookmark`	Bookmark	Out	The requested bookmark.
`follow`	String	In	Indicates which inner links should be followed.

6.36.1.1. follow

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

6.36.2. remove DELETE

Remove a bookmark.

An example for removing a bookmark:

DELETE /ovirt-engine/api/bookmarks/123

Table 6.103. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.36.3. update PUT

Update a bookmark.

An example for updating a bookmark:

PUT /ovirt-engine/api/bookmarks/123

With the request body:

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

Table 6.104. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the update should be performed asynchronously.
`bookmark`	Bookmark	In/Out	The updated bookmark.

6.37. Bookmarks

A service to manage bookmarks.

Table 6.105. Methods summary

Name	Summary
`add`	Adding a new bookmark.
`list`	Listing all the available bookmarks.

6.37.1. add POST

Adding a new bookmark.

Example of adding a bookmark:

POST /ovirt-engine/api/bookmarks

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

Table 6.106. Parameters summary

Name	Type	Direction	Summary
`bookmark`	Bookmark	In/Out	The added bookmark.

6.37.2. list GET

Listing all the available bookmarks.

Example of listing bookmarks:

GET /ovirt-engine/api/bookmarks

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

The order of the returned bookmarks isn’t guaranteed.

Table 6.107. Parameters summary

Name	Type	Direction	Summary
`bookmarks`	Bookmark[]	Out	The list of available bookmarks.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of bookmarks to return.

6.37.2.1. follow

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

6.37.2.2. max

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

6.38. Cluster

A service to manage a specific cluster.

Table 6.108. Methods summary

Name	Summary
`get`	Gets information about the cluster.
`refreshglusterhealstatus`	Refresh the Gluster heal info for all volumes in cluster.
`remove`	Removes the cluster from the system.
`resetemulatedmachine`
`syncallnetworks`	Synchronizes all networks on the cluster.
`update`	Updates information about the cluster.
`upgrade`	Start or finish upgrade process for the cluster based on the action value.

6.38.1. get GET

Gets information about the cluster.

An example of getting a cluster:

GET /ovirt-engine/api/clusters/123

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

Table 6.109. Parameters summary

Name	Type	Direction	Summary
`cluster`	Cluster	Out
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`follow`	String	In	Indicates which inner links should be followed.

6.38.1.1. follow

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

6.38.2. refreshglusterhealstatus POST

Refresh the Gluster heal info for all volumes in cluster.

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

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

6.38.3. remove DELETE

Removes the cluster from the system.

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

Table 6.110. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.38.4. resetemulatedmachine POST

Table 6.111. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the reset should be performed asynchronously.

6.38.5. syncallnetworks POST

Synchronizes all networks on the cluster.

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

With a request body like this:

<action/>

Table 6.112. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the action should be performed asynchronously.

6.38.6. update PUT

Updates information about the cluster.

Only the specified fields are updated; others remain unchanged.

For example, to update the cluster’s CPU:

PUT /ovirt-engine/api/clusters/123

With a request body like this:

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

Table 6.113. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the update should be performed asynchronously.
`cluster`	Cluster	In/Out

6.38.7. upgrade POST

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

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

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

<action>
    <upgrade_action>
        start
    </upgrade_action>
</action>

Table 6.114. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the action should be performed asynchronously.
`upgrade_action`	ClusterUpgradeAction	In	The action to be performed.

6.39. ClusterEnabledFeature

Represents a feature enabled for the cluster.

Table 6.115. Methods summary

Name	Summary
`get`	Provides the information about the cluster feature enabled.
`remove`	Disables a cluster feature.

6.39.1. get GET

Provides the information about the cluster feature enabled.

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

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

That will return a ClusterFeature object containing the name:

<cluster_feature id="456">
  <name>libgfapi_supported</name>
</cluster_feature>

Table 6.116. Parameters summary

Name	Type	Direction	Summary
`feature`	ClusterFeature	Out	Retrieved cluster feature that’s enabled.
`follow`	String	In	Indicates which inner links should be followed.

6.39.1.1. follow

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

6.39.2. remove DELETE

Disables a cluster feature.

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

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

6.40. ClusterEnabledFeatures

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

Table 6.117. Methods summary

Name	Summary
`add`	Enable an additional feature for a cluster.
`list`	Lists the additional features enabled for the cluster.

6.40.1. add POST

Enable an additional feature for a cluster.

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

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

The request body should look like this:

<cluster_feature id="456"/>

Table 6.118. Parameters summary

Name	Type	Direction	Summary
`feature`	ClusterFeature	In/Out

6.40.2. list GET

Lists the additional features enabled for the cluster.

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

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

This will return a list of features:

<enabled_features>
  <cluster_feature id="123">
     <name>test_feature</name>
  </cluster_feature>
  ...
</enabled_features>

Table 6.119. Parameters summary

Name	Type	Direction	Summary
`features`	ClusterFeature[]	Out	Retrieved features.
`follow`	String	In	Indicates which inner links should be followed.

6.40.2.1. follow

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

6.41. ClusterExternalProviders

This service lists external providers.

Table 6.120. Methods summary

Name	Summary
`list`	Returns the list of external providers.

6.41.1. list GET

Returns the list of external providers.

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

Table 6.121. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`providers`	ExternalProvider[]	Out

6.41.1.1. follow

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

6.42. ClusterFeature

Represents a feature enabled for the cluster level

Table 6.122. Methods summary

Name	Summary
`get`	Provides the information about the a cluster feature supported by a cluster level.

6.42.1. get GET

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

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

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

That will return a ClusterFeature object containing the name:

<cluster_feature id="456">
  <name>libgfapi_supported</name>
</cluster_feature>

Table 6.123. Parameters summary

Name	Type	Direction	Summary
`feature`	ClusterFeature	Out	Retrieved cluster feature.
`follow`	String	In	Indicates which inner links should be followed.

6.42.1.1. follow

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

6.43. ClusterFeatures

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

Table 6.124. Methods summary

Name	Summary
`list`	Lists the cluster features supported by the cluster level.

6.43.1. list GET

Lists the cluster features supported by the cluster level.

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

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

<cluster_features>
  <cluster_feature id="123">
     <name>test_feature</name>
  </cluster_feature>
  ...
</cluster_features>

Table 6.125. Parameters summary

Name	Type	Direction	Summary
`features`	ClusterFeature[]	Out	Retrieved features.
`follow`	String	In	Indicates which inner links should be followed.

6.43.1.1. follow

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

6.44. ClusterLevel

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

Table 6.126. Methods summary

Name	Summary
`get`	Provides the information about the capabilities of the specific cluster level managed by this service.

6.44.1. get GET

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

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

GET /ovirt-engine/api/clusterlevels/3.6

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

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

Table 6.127. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`level`	ClusterLevel	Out	Retreived cluster level.

6.44.1.1. follow

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

6.45. ClusterLevels

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

Table 6.128. Methods summary

Name	Summary
`list`	Lists the cluster levels supported by the system.

6.45.1. list GET

Lists the cluster levels supported by the system.

GET /ovirt-engine/api/clusterlevels

This will return a list of available cluster levels.

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

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

Table 6.129. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`levels`	ClusterLevel[]	Out	Retrieved cluster levels.

6.45.1.1. follow

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

6.46. ClusterNetwork

A service to manage a specific cluster network.

Table 6.130. Methods summary

Name	Summary
`get`	Retrieves the cluster network details.
`remove`	Unassigns the network from a cluster.
`update`	Updates the network in the cluster.

6.46.1. get GET

Retrieves the cluster network details.

Table 6.131. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`network`	Network	Out	The cluster network.

6.46.1.1. follow

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

6.46.2. remove DELETE

Unassigns the network from a cluster.

6.46.3. update PUT

Updates the network in the cluster.

Table 6.132. Parameters summary

Name	Type	Direction	Summary
`network`	Network	In/Out	The cluster network.

6.47. ClusterNetworks

A service to manage cluster networks.

Table 6.133. Methods summary

Name	Summary
`add`	Assigns the network to a cluster.
`list`	Lists the networks that are assigned to the cluster.

6.47.1. add POST

Assigns the network to a cluster.

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

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

Use the following example in its body:

<network id="123" />

Table 6.134. Parameters summary

Name	Type	Direction	Summary
`network`	Network	In/Out	The network object to be assigned to the cluster.

6.47.2. list GET

Lists the networks that are assigned to the cluster.

The order of the returned clusters isn’t guaranteed.

Table 6.135. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of networks to return.
`networks`	Network[]	Out	The list of networks that are assigned to the cluster.

6.47.2.1. follow

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

6.47.2.2. max

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

6.48. Clusters

A service to manage clusters.

Table 6.136. Methods summary

Name	Summary
`add`	Creates a new cluster.
`list`	Returns the list of clusters of the system.

6.48.1. add POST

Creates a new cluster.

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

POST /ovirt-engine/api/clusters

With a request body like this:

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

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

POST /ovirt-engine/api/clusters

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

<cluster>
  <name>mycluster</name>
  <cpu>
    <type>Intel Nehalem Family</type>
  </cpu>
  <data_center id="123"/>
  <external_network_providers>
    <external_provider name="ovirt-provider-ovn"/>
  </external_network_providers>
</cluster>

Table 6.137. Parameters summary

Name	Type	Direction	Summary
`cluster`	Cluster	In/Out

6.48.2. list GET

Returns the list of clusters of the system.

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

Table 6.138. Parameters summary

Name	Type	Direction	Summary
`case_sensitive`	Boolean	In	Indicates if the search should be performed taking case into account.
`clusters`	Cluster[]	Out
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of clusters to return.
`search`	String	In	A query string used to restrict the returned clusters.

6.48.2.1. case_sensitive

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

6.48.2.2. follow

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

6.48.2.3. max

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

6.49. Copyable

Table 6.139. Methods summary

Name	Summary
`copy`

6.49.1. copy POST

Table 6.140. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the copy should be performed asynchronously.

6.50. CpuProfile

Table 6.141. Methods summary

Name	Summary
`get`
`remove`
`update`	Update the specified cpu profile in the system.

6.50.1. get GET

Table 6.142. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`profile`	CpuProfile	Out

6.50.1.1. follow

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

6.50.2. remove DELETE

Table 6.143. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.50.3. update PUT

Update the specified cpu profile in the system.

Table 6.144. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the update should be performed asynchronously.
`profile`	CpuProfile	In/Out

6.51. CpuProfiles

Table 6.145. Methods summary

Name	Summary
`add`	Add a new cpu profile to the system.
`list`	Returns the list of CPU profiles of the system.

6.51.1. add POST

Add a new cpu profile to the system.

Table 6.146. Parameters summary

Name	Type	Direction	Summary
`profile`	CpuProfile	In/Out

6.51.2. list GET

Returns the list of CPU profiles of the system.

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

Table 6.147. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of profiles to return.
`profile`	CpuProfile[]	Out

6.51.2.1. follow

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

6.51.2.2. max

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

6.52. DataCenter

A service to manage a data center.

Table 6.148. Methods summary

Name	Summary
`cleanfinishedtasks`	Currently, the storage pool manager (SPM) fails to switch to another host if the SPM has uncleared tasks.
`get`	Get a data center.
`remove`	Removes the data center.
`setmaster`	Used for manually setting a storage domain in the data center as a master.
`update`	Updates the data center.

6.52.1. cleanfinishedtasks POST

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

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

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

With a request body like this:

<action/>

Table 6.149. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the action should be performed asynchronously.

6.52.2. get GET

Get a data center.

An example of getting a data center:

GET /ovirt-engine/api/datacenters/123

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

Table 6.150. Parameters summary

Name	Type	Direction	Summary
`data_center`	DataCenter	Out
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`follow`	String	In	Indicates which inner links should be followed.

6.52.2.1. follow

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

6.52.3. remove DELETE

Removes the data center.

DELETE /ovirt-engine/api/datacenters/123

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

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

Table 6.151. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.
`force`	Boolean	In	Indicates if the operation should succeed, and the storage domain removed from the database, even if something fails during the operation.

6.52.3.1. force

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

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

6.52.4. setmaster POST

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

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

With a request body like this:

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

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

Table 6.152. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the action should be performed asynchronously.
`storage_domain`	StorageDomain	In	The new master storage domain for the data center.

6.52.5. update PUT

Updates the data center.

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

PUT /ovirt-engine/api/datacenters/123

With a request body like this:

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

Table 6.153. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the update should be performed asynchronously.
`data_center`	DataCenter	In/Out	The data center that is being updated.

6.53. DataCenterNetwork

A service to manage a specific data center network.

Table 6.154. Methods summary

Name	Summary
`get`	Retrieves the data center network details.
`remove`	Removes the network.
`update`	Updates the network in the data center.

6.53.1. get GET

Retrieves the data center network details.

Table 6.155. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`network`	Network	Out	The data center network.

6.53.1.1. follow

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

6.53.2. remove DELETE

Removes the network.

6.53.3. update PUT

Updates the network in the data center.

Table 6.156. Parameters summary

Name	Type	Direction	Summary
`network`	Network	In/Out	The data center network.

6.54. DataCenterNetworks

A service to manage data center networks.

Table 6.157. Methods summary

Name	Summary
`add`	Create a new network in a data center.
`list`	Lists networks in the data center.

6.54.1. add POST

Create a new network in a data center.

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

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

Use the following example in its body:

<network>
  <name>mynetwork</name>
</network>

Table 6.158. Parameters summary

Name	Type	Direction	Summary
`network`	Network	In/Out	The network object to be created in the data center.

6.54.2. list GET

Lists networks in the data center.

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

Table 6.159. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of networks to return.
`networks`	Network[]	Out	The list of networks which are in the data center.

6.54.2.1. follow

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

6.54.2.2. max

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

6.55. DataCenters

A service to manage data centers.

Table 6.160. Methods summary

Name	Summary
`add`	Creates a new data center.
`list`	Lists the data centers.

6.55.1. add POST

Creates a new data center.

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

POST /ovirt-engine/api/datacenters

With a request body like this:

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

Table 6.161. Parameters summary

Name	Type	Direction	Summary
`data_center`	DataCenter	In/Out	The data center that is being added.

6.55.2. list GET

Lists the data centers.

The following request retrieves a representation of the data centers:

GET /ovirt-engine/api/datacenters

The above request performed with curl:

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

This is what an example response could look like:

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

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

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

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

Table 6.162. Parameters summary

Name	Type	Direction	Summary
`case_sensitive`	Boolean	In	Indicates if the search performed using the `search` parameter should be performed taking case into account.
`data_centers`	DataCenter[]	Out
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of data centers to return.
`search`	String	In	A query string used to restrict the returned data centers.

6.55.2.1. case_sensitive

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

6.55.2.2. follow

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

6.55.2.3. max

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

6.56. Disk

Manages a single disk.

Table 6.163. Methods summary

Name	Summary
`copy`	This operation copies a disk to the specified storage domain.
`export`	Exports a disk to an export storage domain.
`get`	Retrieves the description of the disk.
`move`	Moves a disk to another storage domain.
`reduce`	Reduces the size of the disk image.
`refreshlun`	Refreshes a direct LUN disk with up-to-date information from the storage.
`remove`	Removes a disk.
`sparsify`	Sparsify the disk.
`update`	Updates the parameters of the specified disk.

6.56.1. copy POST

This operation copies a disk to the specified storage domain.

For example, a disk can be copied using the following request:

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

With a request body like this:

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

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

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

<action>
  <storage_domain id="456"/>
  <disk_profile id="987"/>
  <quota id="753"/>
</action>

Table 6.164. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the copy should be performed asynchronously.
`disk`	Disk	In
`disk_profile`	DiskProfile	In	Disk profile for the disk in the new storage domain.
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`quota`	Quota	In	Quota for the disk in the new storage domain.
`storage_domain`	StorageDomain	In	The storage domain where the new disk is created.

6.56.1.1. disk_profile

Disk profile for the disk in the new storage domain.

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

6.56.1.2. quota

Quota for the disk in the new storage domain.

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

6.56.1.3. storage_domain

The storage domain where the new disk is created. This can be specified using the id or name attributes. For example, to copy a disk to the storage domain called mydata, send a request like this:

POST /ovirt-engine/api/storagedomains/123/disks/789

With a request body like this:

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

6.56.2. export POST

Exports a disk to an export storage domain.

Table 6.165. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the export should be performed asynchronously.
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`storage_domain`	StorageDomain	In	The export storage domain where the disk will be exported to.

6.56.3. get GET

Retrieves the description of the disk.

Table 6.166. Parameters summary

Name	Type	Direction	Summary
`all_content`	Boolean	In	Indicates if all of the attributes of the disk should be included in the response.
`disk`	Disk	Out	The description of the disk.
`follow`	String	In	Indicates which inner links should be followed.

6.56.3.1. all_content

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

By default the following disk attributes are excluded:

vms

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

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

6.56.3.2. follow

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

6.56.4. move POST

Moves a disk to another storage domain.

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

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

With the following request body:

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

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

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

<action>
  <storage_domain id="456"/>
  <disk_profile id="987"/>
  <quota id="753"/>
</action>

Table 6.167. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the move should be performed asynchronously.
`disk_profile`	DiskProfile	In	Disk profile for the disk in the new storage domain.
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`quota`	Quota	In	Quota for the disk in the new storage domain.
`storage_domain`	StorageDomain	In	The storage domain where the disk will be moved to.

6.56.4.1. disk_profile

Disk profile for the disk in the new storage domain.

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

6.56.4.2. quota

Quota for the disk in the new storage domain.

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

6.56.5. reduce POST

Reduces the size of the disk image.

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

Table 6.168. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.56.6. refreshlun POST

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

Refreshing a direct LUN disk is useful when:

The LUN was added using the API without the host parameter, and therefore does not contain any information from the storage (see DisksService::add).
New information about the LUN is available on the storage and you want to update the LUN with it.

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

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

With the following request body:

<action>
  <host id='456'/>
</action>

Table 6.169. Parameters summary

Name	Type	Direction	Summary
`host`	Host	In	The host that will be used to refresh the direct LUN disk.

6.56.7. remove DELETE

Removes a disk.

Table 6.170. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.56.8. sparsify POST

Sparsify the disk.

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

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

6.56.9. update PUT

Updates the parameters of the specified disk.

This operation allows updating the following floating disk properties:

For Image disks: provisioned_size, alias, description, wipe_after_delete, shareable, backup and disk_profile.
For LUN disks: alias, description and shareable.
For Cinder and Managed Block disks: provisioned_size, alias and description.
For VM attached disks, the qcow_version can also be updated.

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

PUT /ovirt-engine/api/disks/123

With a request body like this:

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

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

Table 6.171. Parameters summary

Name	Type	Direction	Summary
`disk`	Disk	In/Out	The update to apply to the disk.

6.57. DiskAttachment

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

Table 6.172. Methods summary

Name	Summary
`get`	Returns the details of the attachment, including the bootable flag and link to the disk.
`remove`	Removes the disk attachment.
`update`	Update the disk attachment and the disk properties within it.

6.57.1. get GET

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

An example of getting a disk attachment:

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

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

Table 6.173. Parameters summary

Name	Type	Direction	Summary
`attachment`	DiskAttachment	Out
`follow`	String	In	Indicates which inner links should be followed.

6.57.1.1. follow

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

6.57.2. remove DELETE

Removes the disk attachment.

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

An example of removing a disk attachment:

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

Table 6.174. Parameters summary

Name	Type	Direction	Summary
`detach_only`	Boolean	In	Indicates if the disk should only be detached from the virtual machine, but not removed from the system.

6.57.2.1. detach_only

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

6.57.3. update PUT

Update the disk attachment and the disk properties within it.

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

Table 6.175. Parameters summary

Name	Type	Direction	Summary
`disk_attachment`	DiskAttachment	In/Out

6.58. DiskAttachments

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

Table 6.176. Methods summary

Name	Summary
`add`	Adds a new disk attachment to the virtual machine.
`list`	List the disk that are attached to the virtual machine.

6.58.1. add POST

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

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

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

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

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

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

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

Important

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

Table 6.177. Parameters summary

Name	Type	Direction	Summary
`attachment`	DiskAttachment	In/Out	The disk attachment to add to the virtual machine.

6.58.2. list GET

List the disk that are attached to the virtual machine.

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

Table 6.178. Parameters summary

Name	Type	Direction	Summary
`attachments`	DiskAttachment[]	Out	A list of disk attachments that are attached to the virtual machine.
`follow`	String	In	Indicates which inner links should be followed.

6.58.2.1. follow

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

6.59. DiskProfile

Table 6.179. Methods summary

Name	Summary
`get`
`remove`
`update`	Update the specified disk profile in the system.

6.59.1. get GET

Table 6.180. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`profile`	DiskProfile	Out

6.59.1.1. follow

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

6.59.2. remove DELETE

Table 6.181. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.59.3. update PUT

Update the specified disk profile in the system.

Table 6.182. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the update should be performed asynchronously.
`profile`	DiskProfile	In/Out

6.60. DiskProfiles

Table 6.183. Methods summary

Name	Summary
`add`	Add a new disk profile to the system.
`list`	Returns the list of disk profiles of the system.

6.60.1. add POST

Add a new disk profile to the system.

Table 6.184. Parameters summary

Name	Type	Direction	Summary
`profile`	DiskProfile	In/Out

6.60.2. list GET

Returns the list of disk profiles of the system.

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

Table 6.185. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of profiles to return.
`profile`	DiskProfile[]	Out

6.60.2.1. follow

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

6.60.2.2. max

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

6.61. DiskSnapshot

Table 6.186. Methods summary

Name	Summary
`get`
`remove`

6.61.1. get GET

Table 6.187. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`snapshot`	DiskSnapshot	Out

6.61.1.1. follow

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

6.61.2. remove DELETE

Table 6.188. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.62. DiskSnapshots

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

Table 6.189. Methods summary

Name	Summary
`list`	Returns the list of disk snapshots of the storage domain.

6.62.1. list GET

Returns the list of disk snapshots of the storage domain.

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

Table 6.190. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`include_active`	Boolean	In	If true return also active snapshots.
`max`	Integer	In	Sets the maximum number of snapshots to return.
`snapshots`	DiskSnapshot[]	Out

6.62.1.1. follow

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

6.62.1.2. include_active

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

6.62.1.3. max

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

6.63. Disks

Manages the collection of disks available in the system.

Table 6.191. Methods summary

Name	Summary
`add`	Adds a new floating disk.
`list`	Get list of disks.

6.63.1. add POST

Adds a new floating disk.

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

Adding a new image disk:

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

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

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

POST /ovirt-engine/api/disks

With a request body as follows:

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

Adding a new direct LUN disk:

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

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).
Without a host element - in this case, the operation is a database-only operation, and the storage is never accessed.

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

POST /ovirt-engine/api/disks

With a request body as follows:

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

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

Adding a new Cinder disk:

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

POST /ovirt-engine/api/disks

With a request body as follows:

<disk>
  <openstack_volume_type>
    <name>myceph</name>
  </openstack_volume_type>
  <storage_domains>
    <storage_domain>
      <name>cinderDomain</name>
    </storage_domain>
  </storage_domains>
  <provisioned_size>1073741824</provisioned_size>
  <interface>virtio</interface>
  <format>raw</format>
</disk>

Adding a floating disks in order to upload disk snapshots:

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

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

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

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

POST /ovirt-engine/api/disks

With a request body as follows:

<disk id="b7a4c6c5-443b-47c5-967f-6abc79675e8b">
  <image_id>b548366b-fb51-4b41-97be-733c887fe305</image_id>
  <storage_domains>
    <storage_domain id="123"/>
  </storage_domains>
  <name>mydisk</name>
  <provisioned_size>1048576</provisioned_size>
  <format>cow</format>
</disk>

Table 6.192. Parameters summary

Name	Type	Direction	Summary
`disk`	Disk	In/Out	The disk.

6.63.2. list GET

Get list of disks.

GET /ovirt-engine/api/disks

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

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

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

Table 6.193. Parameters summary

Name	Type	Direction	Summary
`case_sensitive`	Boolean	In	Indicates if the search performed using the `search` parameter should be performed taking case into account.
`disks`	Disk[]	Out	List of retrieved disks.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of disks to return.
`search`	String	In	A query string used to restrict the returned disks.

6.63.2.1. case_sensitive

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

6.63.2.2. follow

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

6.63.2.3. max

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

6.64. Domain

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

Table 6.194. Methods summary

Name	Summary
`get`	Gets the authentication domain information.

6.64.1. get GET

Gets the authentication domain information.

Usage:

GET /ovirt-engine/api/domains/5678

Will return the domain information:

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

Table 6.195. Parameters summary

Name	Type	Direction	Summary
`domain`	Domain	Out	The authentication domain.
`follow`	String	In	Indicates which inner links should be followed.

6.64.1.1. follow

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

6.65. DomainGroup

Table 6.196. Methods summary

Name	Summary
`get`

6.65.1. get GET

Table 6.197. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`get`	Group	Out

6.65.1.1. follow

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

6.66. DomainGroups

Table 6.198. Methods summary

Name	Summary
`list`	Returns the list of groups.

6.66.1. list GET

Returns the list of groups.

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

Table 6.199. Parameters summary

Name	Type	Direction	Summary
`case_sensitive`	Boolean	In	Indicates if the search performed using the `search` parameter should be performed taking case into account.
`follow`	String	In	Indicates which inner links should be followed.
`groups`	Group[]	Out
`max`	Integer	In	Sets the maximum number of groups to return.
`search`	String	In	A query string used to restrict the returned groups.

6.66.1.1. case_sensitive

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

6.66.1.2. follow

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

6.66.1.3. max

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

6.67. DomainUser

A service to view a domain user in the system.

Table 6.200. Methods summary

Name	Summary
`get`	Gets the domain user information.

6.67.1. get GET

Gets the domain user information.

Usage:

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

Will return the domain user information:

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

Table 6.201. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`user`	User	Out	The domain user.

6.67.1.1. follow

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

6.68. DomainUserGroups

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

Table 6.202. Methods summary

Name	Summary
`list`	Returns the list of groups that the user is a member of.

6.68.1. list GET

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

Table 6.203. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`groups`	Group[]	Out	The list of groups that the user is a member of.

6.68.1.1. follow

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

6.69. DomainUsers

A service to list all domain users in the system.

Table 6.204. Methods summary

Name	Summary
`list`	List all the users in the domain.

6.69.1. list GET

List all the users in the domain.

Usage:

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

Will return the list of users in the domain:

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

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

Table 6.205. Parameters summary

Name	Type	Direction	Summary
`case_sensitive`	Boolean	In	Indicates if the search performed using the `search` parameter should be performed taking case into account.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of users to return.
`search`	String	In	A query string used to restrict the returned users.
`users`	User[]	Out	The list of users in the domain.

6.69.1.1. case_sensitive

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

6.69.1.2. follow

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

6.69.1.3. max

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

6.70. Domains

A service to list all authentication domains in the system.

Table 6.206. Methods summary

Name	Summary
`list`	List all the authentication domains in the system.

6.70.1. list GET

List all the authentication domains in the system.

Usage:

GET /ovirt-engine/api/domains

Will return the list of domains:

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

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

Table 6.207. Parameters summary

Name	Type	Direction	Summary
`domains`	Domain[]	Out	The list of domains.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of domains to return.

6.70.1.1. follow

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

6.70.1.2. max

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

6.71. EngineKatelloErrata

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

Table 6.208. Methods summary

Name	Summary
`list`	Retrieves the representation of the Katello errata.

6.71.1. list GET

Retrieves the representation of the Katello errata.

GET /ovirt-engine/api/katelloerrata

You will receive response in XML like this one:

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

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

Table 6.209. Parameters summary

Name	Type	Direction	Summary
`errata`	KatelloErratum[]	Out	A representation of Katello errata.
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of errata to return.

6.71.1.1. follow

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

6.71.1.2. max

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

6.72. Event

A service to manage an event in the system.

Table 6.210. Methods summary

Name	Summary
`get`	Get an event.
`remove`	Removes an event from internal audit log.

6.72.1. get GET

Get an event.

An example of getting an event:

GET /ovirt-engine/api/events/123

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

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

Table 6.211. Parameters summary

Name	Type	Direction	Summary
`event`	Event	Out
`follow`	String	In	Indicates which inner links should be followed.

6.72.1.1. follow

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

6.72.2. remove DELETE

Removes an event from internal audit log.

An event can be removed by sending following request

DELETE /ovirt-engine/api/events/123

Table 6.212. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.73. EventSubscription

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

Table 6.213. Methods summary

Name	Summary
`get`	Gets the information about the event-subscription.
`remove`	Removes the event-subscription from the system.

6.73.1. get GET

Gets the information about the event-subscription.

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

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

<event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/vm_console_detected">
  <event>vm_console_detected</event>
  <notification_method>smtp</notification_method>
  <user href="/ovirt-engine/api/users/123" id="123"/>
  <address>a@b.com</address>
</event-subscription>

Table 6.214. Parameters summary

Name	Type	Direction	Summary
`event_subscription`	EventSubscription	Out	The event-subscription.

6.73.2. remove DELETE

Removes the event-subscription from the system.

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

DELETE /ovirt-engine/api/users/123/vm_console_detected

Table 6.215. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.74. EventSubscriptions

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

Table 6.216. Methods summary

Name	Summary
`add`	Add a new event-subscription to the system.
`list`	List the event-subscriptions for the provided user.

6.74.1. add POST

Add a new event-subscription to the system.

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

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

With a request body like this:

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

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

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

Table 6.217. Parameters summary

Name	Type	Direction	Summary
`event_subscription`	EventSubscription	In/Out	The added event-subscription.

6.74.2. list GET

List the event-subscriptions for the provided user.

For example to list event-subscriptions for user 123:

GET /ovirt-engine/api/users/123/event-subscriptions

<event-subscriptions>
  <event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/host_install_failed">
    <event>host_install_failed</event>
    <notification_method>smtp</notification_method>
    <user href="/ovirt-engine/api/users/123" id="123"/>
    <address>a@b.com</address>
  </event-subscription>
  <event-subscription href="/ovirt-engine/api/users/123/event-subscriptions/vm_paused">
    <event>vm_paused</event>
    <notification_method>smtp</notification_method>
    <user href="/ovirt-engine/api/users/123" id="123"/>
    <address>a@b.com</address>
  </event-subscription>
</event-subscriptions>

Table 6.218. Parameters summary

Name	Type	Direction	Summary
`event_subscriptions`	EventSubscription[]	Out	List of the event-subscriptions for the specified user
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of event-subscriptions to return.

6.74.2.1. follow

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

6.74.2.2. max

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

6.75. Events

A service to manage events in the system.

Table 6.219. Methods summary

Name	Summary
`add`	Adds an external event to the internal audit log.
`list`	Get list of events.
`undelete`

6.75.1. add POST

Adds an external event to the internal audit log.

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

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

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

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

Note

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

Table 6.220. Parameters summary

Name	Type	Direction	Summary
`event`	Event	In/Out

6.75.2. list GET

Get list of events.

GET /ovirt-engine/api/events

To the above request we get following response:

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

The following events occur:

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

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

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

Table 6.221. Parameters summary

Name	Type	Direction	Summary
`case_sensitive`	Boolean	In	Indicates if the search performed using the `search` parameter should be performed taking case into account.
`events`	Event[]	Out
`follow`	String	In	Indicates which inner links should be followed.
`from`	Integer	In	Indicates the event index after which events should be returned.
`max`	Integer	In	Sets the maximum number of events to return.
`search`	String	In	The events service provides search queries similar to other resource services.

6.75.2.1. case_sensitive

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

6.75.2.2. follow

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

6.75.2.3. from

Indicates the event index after which events should be returned. The indexes of events are strictly increasing, so when this parameter is used only the events with greater indexes will be returned. For example, the following request will return only the events with indexes greater than 123:

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

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

6.75.2.4. max

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

6.75.2.5. search

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

We can search by providing specific severity.

GET /ovirt-engine/api/events?search=severity%3Dnormal

To the above request we get a list of events which severity is equal to normal:

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

A virtualization environment generates a large amount of events after a period of time. However, the API only displays a default number of events for one search query. To display more than the default, the API separates results into pages with the page command in a search query. The following search query tells the API to paginate results using a page value in combination with the sortby clause:

sortby time asc page 1

Below example paginates event resources. The URL-encoded request is:

GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201

Increase the page value to view the next page of results.

GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202

6.75.3. undelete POST

Table 6.222. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the un-delete should be performed asynchronously.

6.76. ExternalComputeResource

Manages a single external compute resource.

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

Table 6.223. Methods summary

Name	Summary
`get`	Retrieves external compute resource details.

6.76.1. get GET

Retrieves external compute resource details.

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

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

It will return a response like this:

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

Table 6.224. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`resource`	ExternalComputeResource	Out	External compute resource information

6.76.1.1. follow

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

6.77. ExternalComputeResources

Manages a collection of external compute resources.

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

Table 6.225. Methods summary

Name	Summary
`list`	Retrieves a list of external compute resources.

6.77.1. list GET

Retrieves a list of external compute resources.

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

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

It will return a response like this:

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

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

Table 6.226. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of resources to return.
`resources`	ExternalComputeResource[]	Out	List of external computer resources.

6.77.1.1. follow

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

6.77.1.2. max

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

6.78. ExternalDiscoveredHost

This service manages a single discovered host.

Table 6.227. Methods summary

Name	Summary
`get`	Get discovered host info.

6.78.1. get GET

Get discovered host info.

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

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

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

The result will be like this:

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

Table 6.228. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`host`	ExternalDiscoveredHost	Out	Host’s hardware and config information.

6.78.1.1. follow

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

6.79. ExternalDiscoveredHosts

This service manages external discovered hosts.

Table 6.229. Methods summary

Name	Summary
`list`	Get list of discovered hosts' information.

6.79.1. list GET

Get list of discovered hosts' information.

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

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

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

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

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

Table 6.230. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`hosts`	ExternalDiscoveredHost[]	Out	List of discovered hosts
`max`	Integer	In	Sets the maximum number of hosts to return.

6.79.1.1. follow

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

6.79.1.2. max

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

6.80. ExternalHost

Table 6.231. Methods summary

Name	Summary
`get`

6.80.1. get GET

Table 6.232. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`host`	ExternalHost	Out

6.80.1.1. follow

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

6.81. ExternalHostGroup

This service manages a single host group information.

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

Table 6.233. Methods summary

Name	Summary
`get`	Get host group information.

6.81.1. get GET

Get host group information.

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

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

It will return a response like this:

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

Table 6.234. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`group`	ExternalHostGroup	Out	Host group information.

6.81.1.1. follow

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

6.82. ExternalHostGroups

This service manages hostgroups.

Table 6.235. Methods summary

Name	Summary
`list`	Get host groups list from external host provider.

6.82.1. list GET

Get host groups list from external host provider.

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

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

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

The response will be like this:

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

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

Table 6.236. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`groups`	ExternalHostGroup[]	Out	List of all hostgroups available for external host provider
`max`	Integer	In	Sets the maximum number of groups to return.

6.82.1.1. follow

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

6.82.1.2. max

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

6.83. ExternalHostProvider

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

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

Table 6.237. Methods summary

Name	Summary
`get`	Get external host provider information Host provider, Foreman or Satellite, can be set as an external provider in ovirt.
`importcertificates`	Import the SSL certificates of the external host provider.
`remove`
`testconnectivity`	In order to test connectivity for external provider we need to run following request where 123 is an id of a provider.
`update`	Update the specified external host provider in the system.

6.83.1. get GET

Get external host provider information

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

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

GET /ovirt-engine/api/externalhostproviders/123

The response will be like this:

<external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123">
  <name>mysatellite</name>
  <requires_authentication>true</requires_authentication>
  <url>https://mysatellite.example.com</url>
  <username>admin</username>
</external_host_provider>

Table 6.238. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`provider`	ExternalHostProvider	Out

6.83.1.1. follow

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

6.83.2. importcertificates POST

Import the SSL certificates of the external host provider.

Table 6.239. Parameters summary

Name	Type	Direction	Summary
`certificates`	Certificate[]	In

6.83.3. remove DELETE

Table 6.240. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.

6.83.4. testconnectivity POST

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

POST /ovirt-engine/api/externalhostproviders/123/testconnectivity

Table 6.241. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the test should be performed asynchronously.

6.83.5. update PUT

Update the specified external host provider in the system.

Table 6.242. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the update should be performed asynchronously.
`provider`	ExternalHostProvider	In/Out

6.84. ExternalHostProviders

Table 6.243. Methods summary

Name	Summary
`add`	Add a new external host provider to the system.
`list`	Returns the list of external host providers.

6.84.1. add POST

Add a new external host provider to the system.

Table 6.244. Parameters summary

Name	Type	Direction	Summary
`provider`	ExternalHostProvider	In/Out

6.84.2. list GET

Returns the list of external host providers.

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

Table 6.245. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`max`	Integer	In	Sets the maximum number of providers to return.
`providers`	ExternalHostProvider[]	Out
`search`	String	In	A query string used to restrict the returned external host providers.

6.84.2.1. follow

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

6.84.2.2. max

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

6.85. ExternalHosts

Table 6.246. Methods summary

Name	Summary
`list`	Return the list of external hosts.

6.85.1. list GET

Return the list of external hosts.

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

Table 6.247. Parameters summary

Name	Type	Direction	Summary
`follow`	String	In	Indicates which inner links should be followed.
`hosts`	ExternalHost[]	Out
`max`