Chapter 6. Services Red Hat Virtualization 4.1

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
`group`	AffinityGroup	Out	The affinity group.

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

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

Table 6.5. Methods summary

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

6.2.1. remove DELETE

Remove this virtual machine 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. AffinityGroupVms

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

Table 6.7. Methods summary

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

6.3.1. add POST

Add a virtual machine to the affinity group.

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

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

With the following body:

<vm id="000-000"/>

Table 6.8. Parameters summary

Name	Type	Direction	Summary
`vm`	Vm	In/Out

6.3.2. list GET

List all virtual machines assigned to this affinity group.

Table 6.9. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of virtual machines to return.
`vms`	Vm[]	Out

6.3.2.1. max

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

6.4. AffinityGroups

The affinity groups service manages virtual machine relationships and dependencies.

Table 6.10. Methods summary

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

6.4.1. add POST

Create a new affinity group.

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

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

And use the following example in its body:

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

Table 6.11. Parameters summary

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

6.4.2. list GET

List existing affinity groups.

Table 6.12. Parameters summary

Name	Type	Direction	Summary
`groups`	AffinityGroup[]	Out	The list of existing affinity groups.
`max`	Integer	In	Sets the maximum number of affinity groups to return.

6.4.2.1. max

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

6.5. AffinityLabel

The details of a single affinity label.

Table 6.13. 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.5.1. get GET

Retrieves the details of a label.

Table 6.14. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	Out

6.5.2. remove DELETE

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

6.5.3. update PUT

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

Table 6.15. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	In/Out

6.6. AffinityLabelHost

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

Table 6.16. Methods summary

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

6.6.1. get GET

Retrieves details about a host that has this label assigned.

Table 6.17. Parameters summary

Name	Type	Direction	Summary
`host`	Host	Out

6.6.2. remove DELETE

Remove a label from a host.

6.7. AffinityLabelHosts

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

Table 6.18. Methods summary

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

6.7.1. add POST

Add a label to a host.

Table 6.19. Parameters summary

Name	Type	Direction	Summary
`host`	Host	In/Out

6.7.2. list GET

List all hosts with the label.

Table 6.20. Parameters summary

Name	Type	Direction	Summary
`hosts`	Host[]	Out

6.8. AffinityLabelVm

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

Table 6.21. Methods summary

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

6.8.1. get GET

Retrieves details about a vm that has this label assigned.

Table 6.22. Parameters summary

Name	Type	Direction	Summary
`vm`	Vm	Out

6.8.2. remove DELETE

Remove a label from a vm.

6.9. AffinityLabelVms

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

Table 6.23. Methods summary

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

6.9.1. add POST

Add a label to a vm.

Table 6.24. Parameters summary

Name	Type	Direction	Summary
`vm`	Vm	In/Out

6.9.2. list GET

List all vms with the label.

Table 6.25. Parameters summary

Name	Type	Direction	Summary
`vms`	Vm[]	Out

6.10. AffinityLabels

Manages the affinity labels available in the system.

Table 6.26. Methods summary

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

6.10.1. add POST

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

Table 6.27. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	In/Out

6.10.2. list GET

Lists all labels present in the system.

Table 6.28. Parameters summary

Name	Type	Direction	Summary
`labels`	AffinityLabel[]	Out
`max`	Integer	In	Sets the maximum number of labels to return.

6.10.2.1. max

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

6.11. AssignedAffinityLabel

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

Table 6.29. Methods summary

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

6.11.1. get GET

Retrieves details about the attached label.

Table 6.30. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	Out

6.11.2. remove DELETE

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

6.12. AssignedAffinityLabels

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

Table 6.31. Methods summary

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

6.12.1. add POST

Attaches a label to an entity.

Table 6.32. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel	In/Out

6.12.2. list GET

Lists all labels that are attached to an entity.

Table 6.33. Parameters summary

Name	Type	Direction	Summary
`label`	AffinityLabel[]	Out

6.13. AssignedCpuProfile

Table 6.34. Methods summary

Name	Summary
`get`
`remove`

6.13.1. get GET

Table 6.35. Parameters summary

Name	Type	Direction	Summary
`profile`	CpuProfile	Out

6.13.2. remove DELETE

Table 6.36. Parameters summary

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

6.14. AssignedCpuProfiles

Table 6.37. Methods summary

Name	Summary
`add`
`list`

6.14.1. add POST

Table 6.38. Parameters summary

Name	Type	Direction	Summary
`profile`	CpuProfile	In/Out

6.14.2. list GET

Table 6.39. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of profiles to return.
`profiles`	CpuProfile[]	Out

6.14.2.1. max

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

6.15. AssignedDiskProfile

Table 6.40. Methods summary

Name	Summary
`get`
`remove`

6.15.1. get GET

Table 6.41. Parameters summary

Name	Type	Direction	Summary
`disk_profile`	DiskProfile	Out

6.15.2. remove DELETE

Table 6.42. Parameters summary

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

6.16. AssignedDiskProfiles

Table 6.43. Methods summary

Name	Summary
`add`
`list`

6.16.1. add POST

Table 6.44. Parameters summary

Name	Type	Direction	Summary
`profile`	DiskProfile	In/Out

6.16.2. list GET

Table 6.45. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of profiles to return.
`profiles`	DiskProfile[]	Out

6.16.2.1. max

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

6.17. AssignedPermissions

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

Table 6.46. 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.17.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.47. Parameters summary

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

6.17.2. list GET

List all the permissions of the specific entity.

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

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

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

Table 6.48. Parameters summary

Name	Type	Direction	Summary
`permissions`	Permission[]	Out	The list of permissions.

6.18. AssignedRoles

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

Table 6.49. Methods summary

Name	Summary
`list`

6.18.1. list GET

Table 6.50. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of roles to return.
`roles`	Role[]	Out

6.18.1.1. max

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

6.19. AssignedTag

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

Table 6.51. Methods summary

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

6.19.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.52. Parameters summary

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

6.19.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.53. Parameters summary

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

6.20. AssignedTags

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

Table 6.54. Methods summary

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

6.20.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.55. Parameters summary

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

6.20.2. list GET

List all tags assigned to the specific entity.

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

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

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

Table 6.56. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of tags to return.
`tags`	Tag[]	Out	The list of assigned tags.

6.20.2.1. max

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

6.21. AssignedVnicProfile

Table 6.57. Methods summary

Name	Summary
`get`
`remove`

6.21.1. get GET

Table 6.58. Parameters summary

Name	Type	Direction	Summary
`profile`	VnicProfile	Out

6.21.2. remove DELETE

Table 6.59. Parameters summary

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

6.22. AssignedVnicProfiles

Table 6.60. Methods summary

Name	Summary
`add`
`list`

6.22.1. add POST

Table 6.61. Parameters summary

Name	Type	Direction	Summary
`profile`	VnicProfile	In/Out

6.22.2. list GET

Table 6.62. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of profiles to return.
`profiles`	VnicProfile[]	Out

6.22.2.1. max

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

6.23. AttachedStorageDomain

Table 6.63. Methods summary

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

6.23.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.64. Parameters summary

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

6.23.2. deactivate POST

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

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

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

<action/>

Table 6.65. Parameters summary

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

6.23.3. get GET

Table 6.66. Parameters summary

Name	Type	Direction	Summary
`storage_domain`	StorageDomain	Out

6.23.4. remove DELETE

Table 6.67. Parameters summary

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

6.24. AttachedStorageDomains

Table 6.68. Methods summary

Name	Summary
`add`
`list`

6.24.1. add POST

Table 6.69. Parameters summary

Name	Type	Direction	Summary
`storage_domain`	StorageDomain	In/Out

6.24.2. list GET

Table 6.70. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of storage domains to return.
`storage_domains`	StorageDomain[]	Out

6.24.2.1. max

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

6.25. Balance

Table 6.71. Methods summary

Name	Summary
`get`
`remove`

6.25.1. get GET

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

6.25.2. remove DELETE

Table 6.73. Parameters summary

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

6.26. Balances

Table 6.74. Methods summary

Name	Summary
`add`
`list`

6.26.1. add POST

Table 6.75. Parameters summary

Name	Type	Direction	Summary
`balance`	Balance	In/Out

6.26.2. list GET

Table 6.76. 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.
`max`	Integer	In	Sets the maximum number of balances to return.

6.26.2.1. max

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

6.27. Bookmark

A service to manage a bookmark.

Table 6.77. Methods summary

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

6.27.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.78. Parameters summary

Name	Type	Direction	Summary
`bookmark`	Bookmark	Out	The requested bookmark.

6.27.2. remove DELETE

Remove a bookmark.

An example for removing a bookmark:

DELETE /ovirt-engine/api/bookmarks/123

Table 6.79. Parameters summary

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

6.27.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.80. 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.28. Bookmarks

A service to manage bookmarks.

Table 6.81. Methods summary

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

6.28.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.82. Parameters summary

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

6.28.2. list GET

Listing all the available bookmarks.

Example of listing bookmarks:

GET /ovirt-engine/api/bookmarks

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

Table 6.83. Parameters summary

Name	Type	Direction	Summary
`bookmarks`	Bookmark[]	Out	The list of available bookmarks.
`max`	Integer	In	Sets the maximum number of bookmarks to return.

6.28.2.1. max

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

6.29. Cluster

A service to manage specific cluster.

Table 6.84. Methods summary

Name	Summary
`get`	Get information about the cluster.
`remove`	Removes cluster from the system.
`resetemulatedmachine`
`update`	Updates information about the cluster.

6.29.1. get GET

Get information about the cluster.

An example of getting a cluster:

GET /ovirt-engine/api/clusters/123

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

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

6.29.2. remove DELETE

Removes cluster from the system.

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

Table 6.86. Parameters summary

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

6.29.3. resetemulatedmachine POST

Table 6.87. Parameters summary

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

6.29.4. update PUT

Updates information about the cluster.

Only specified fields are updated, others remain unchanged.

E.g. update cluster’s CPU:

PUT /ovirt-engine/api/clusters/123

With request body like:

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

Table 6.88. Parameters summary

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

6.30. ClusterLevel

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

Table 6.89. Methods summary

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

6.30.1. get GET

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

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

GET /ovirt-engine/api/clusterlevels/3.6

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

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

Table 6.90. Parameters summary

Name	Type	Direction	Summary
`level`	ClusterLevel	Out	Retreived cluster level.

6.31. 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.91. Methods summary

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

6.31.1. list GET

Lists the cluster levels supported by the system.

GET /ovirt-engine/api/clusterlevels

This will return a list of available cluster levels.

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

Table 6.92. Parameters summary

Name	Type	Direction	Summary
`levels`	ClusterLevel[]	Out	Retrieved cluster levels.

6.32. ClusterNetwork

A service to manage a specific cluster network.

Table 6.93. 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.32.1. get GET

Retrieves the cluster network details.

Table 6.94. Parameters summary

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

6.32.2. remove DELETE

Unassigns the network from a cluster.

6.32.3. update PUT

Updates the network in the cluster.

Table 6.95. Parameters summary

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

6.33. ClusterNetworks

A service to manage cluster networks.

Table 6.96. Methods summary

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

6.33.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.97. Parameters summary

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

6.33.2. list GET

Lists the networks that are assigned to the cluster.

Table 6.98. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of networks to return.
`networks`	Network[]	Out	The list of networks that are assigned to the cluster.

6.33.2.1. max

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

6.34. Clusters

A service to manage clusters.

Table 6.99. Methods summary

Name	Summary
`add`	Creates a new cluster.
`list`

6.34.1. add POST

Creates a new cluster.

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

POST /ovirt-engine/api/clusters

With a request body like this:

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

Table 6.100. Parameters summary

Name	Type	Direction	Summary
`cluster`	Cluster	In/Out

6.34.2. list GET

Table 6.101. 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.
`clusters`	Cluster[]	Out
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`max`	Integer	In	Sets the maximum number of clusters to return.
`search`	String	In	A query string used to restrict the returned clusters.

6.34.2.1. case_sensitive

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

6.34.2.2. max

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

6.35. Copyable

Table 6.102. Methods summary

Name	Summary
`copy`

6.35.1. copy POST

Table 6.103. Parameters summary

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

6.36. CpuProfile

Table 6.104. Methods summary

Name	Summary
`get`
`remove`
`update`

6.36.1. get GET

Table 6.105. Parameters summary

Name	Type	Direction	Summary
`profile`	CpuProfile	Out

6.36.2. remove DELETE

Table 6.106. Parameters summary

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

6.36.3. update PUT

Table 6.107. Parameters summary

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

6.37. CpuProfiles

Table 6.108. Methods summary

Name	Summary
`add`
`list`

6.37.1. add POST

Table 6.109. Parameters summary

Name	Type	Direction	Summary
`profile`	CpuProfile	In/Out

6.37.2. list GET

Table 6.110. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of profiles to return.
`profile`	CpuProfile[]	Out

6.37.2.1. max

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

6.38. DataCenter

A service to manage a data center.

Table 6.111. Methods summary

Name	Summary
`get`	Get a data center.
`remove`	Removes the data center.
`update`	Updates the data center.

6.38.1. get GET

Get a data center.

An example of getting a data center:

GET /ovirt-engine/api/datacenters/123

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

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

6.38.2. remove DELETE

Removes the data center.

DELETE /ovirt-engine/api/datacenters/123

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

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

Table 6.113. 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.38.2.1. force

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

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

6.38.3. update PUT

Updates the data center.

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

PUT /ovirt-engine/api/datacenters/123

With a request body like this:

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

Table 6.114. 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.39. DataCenterNetwork

A service to manage a specific data center network.

Table 6.115. Methods summary

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

6.39.1. get GET

Retrieves the data center network details.

Table 6.116. Parameters summary

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

6.39.2. remove DELETE

Removes the network.

6.39.3. update PUT

Updates the network in the data center.

Table 6.117. Parameters summary

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

6.40. DataCenterNetworks

A service to manage data center networks.

Table 6.118. Methods summary

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

6.40.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.119. Parameters summary

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

6.40.2. list GET

Lists networks in the data center.

Table 6.120. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of networks to return.
`networks`	Network[]	Out	The list of networks which are in the data center.

6.40.2.1. max

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

6.41. DataCenters

A service to manage data centers.

Table 6.121. Methods summary

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

6.41.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.122. Parameters summary

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

6.41.2. list GET

Lists the data centers.

The following request retrieves a representation of the data centers:

GET /ovirt-engine/api/datacenters

The above request performed with curl:

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

This is what an example response could look like:

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

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

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

Table 6.123. 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.
`max`	Integer	In	Sets the maximum number of data centers to return.
`search`	String	In	A query string used to restrict the returned data centers.

6.41.2.1. case_sensitive

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

6.41.2.2. max

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

6.42. Disk

Manages a single disk.

Table 6.124. Methods summary

Name	Summary
`copy`	This operation copies a disk to the specified storage domain.
`export`
`get`
`move`	Moves a disk to another storage domain.
`remove`
`sparsify`	Sparsify the disk.

6.42.1. copy POST

This operation copies a disk to the specified storage domain.

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

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

With a request body like this:

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

Table 6.125. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the copy should be performed asynchronously.
`disk`	Disk	In
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`storage_domain`	StorageDomain	In

6.42.2. export POST

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

6.42.3. get GET

Table 6.127. Parameters summary

Name	Type	Direction	Summary
`disk`	Disk	Out

6.42.4. move POST

Moves a disk to another storage domain.

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

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

With the following request body:

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

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

6.42.5. remove DELETE

Table 6.129. Parameters summary

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

6.42.6. 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.43. DiskAttachment

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

Table 6.130. 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.43.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.131. Parameters summary

Name	Type	Direction	Summary
`attachment`	DiskAttachment	Out

6.43.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.132. 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.43.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.43.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.133. Parameters summary

Name	Type	Direction	Summary
`disk_attachment`	DiskAttachment	In/Out

6.44. 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.134. 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.44.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.135. Parameters summary

Name	Type	Direction	Summary
`attachment`	DiskAttachment	In/Out

6.44.2. list GET

List the disk that are attached to the virtual machine.

Table 6.136. Parameters summary

Name	Type	Direction	Summary
`attachments`	DiskAttachment[]	Out

6.45. DiskProfile

Table 6.137. Methods summary

Name	Summary
`get`
`remove`
`update`

6.45.1. get GET

Table 6.138. Parameters summary

Name	Type	Direction	Summary
`profile`	DiskProfile	Out

6.45.2. remove DELETE

Table 6.139. Parameters summary

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

6.45.3. update PUT

Table 6.140. Parameters summary

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

6.46. DiskProfiles

Table 6.141. Methods summary

Name	Summary
`add`
`list`

6.46.1. add POST

Table 6.142. Parameters summary

Name	Type	Direction	Summary
`profile`	DiskProfile	In/Out

6.46.2. list GET

Table 6.143. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of profiles to return.
`profile`	DiskProfile[]	Out

6.46.2.1. max

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

6.47. DiskSnapshot

Table 6.144. Methods summary

Name	Summary
`get`
`remove`

6.47.1. get GET

Table 6.145. Parameters summary

Name	Type	Direction	Summary
`snapshot`	DiskSnapshot	Out

6.47.2. remove DELETE

Table 6.146. Parameters summary

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

6.48. DiskSnapshots

Table 6.147. Methods summary

Name	Summary
`list`

6.48.1. list GET

Table 6.148. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of snapshots to return.
`snapshots`	DiskSnapshot[]	Out

6.48.1.1. max

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

6.49. Disks

Manages the collection of disks available in the system.

Table 6.149. Methods summary

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

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

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>

Table 6.150. Parameters summary

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

6.49.2. list GET

Get list of disks.

GET /ovirt-engine/api/disks

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

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

Table 6.151. 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.
`max`	Integer	In	Sets the maximum number of disks to return.
`search`	String	In	A query string used to restrict the returned disks.
`unregistered`	Boolean	In	Indicates whether to retrieve a list of registered or unregistered disks in the storage domain.

6.49.2.1. case_sensitive

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

6.49.2.2. max

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

6.49.2.3. unregistered

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

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

The default value of the unregistered flag is false.

Important

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

6.50. Domain

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

Table 6.152. Methods summary

Name	Summary
`get`	Gets the authentication domain information.

6.50.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.153. Parameters summary

Name	Type	Direction	Summary
`domain`	Domain	Out	The authentication domain.

6.51. DomainGroup

Table 6.154. Methods summary

Name	Summary
`get`

6.51.1. get GET

Table 6.155. Parameters summary

Name	Type	Direction	Summary
`get`	Group	Out

6.52. DomainGroups

Table 6.156. Methods summary

Name	Summary
`list`

6.52.1. list GET

Table 6.157. 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.
`groups`	Group[]	Out
`max`	Integer	In	Sets the maximum number of groups to return.
`search`	String	In	A query string used to restrict the returned groups.

6.52.1.1. case_sensitive

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

6.52.1.2. max

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

6.53. DomainUser

A service to view a domain user in the system.

Table 6.158. Methods summary

Name	Summary
`get`	Gets the domain user information.

6.53.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.159. Parameters summary

Name	Type	Direction	Summary
`user`	User	Out	The domain user.

6.54. DomainUsers

A service to list all domain users in the system.

Table 6.160. Methods summary

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

6.54.1. list GET

List all the users in the domain.

Usage:

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

Will return the list of users in the domain:

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

Table 6.161. 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.
`max`	Integer	In	Sets the maximum number of users to return.
`search`	String	In	A query string used to restrict the returned users.
`users`	User[]	Out	The list of users in the domain.

6.54.1.1. case_sensitive

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

6.54.1.2. max

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

6.55. Domains

A service to list all authentication domains in the system.

Table 6.162. Methods summary

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

6.55.1. list GET

List all the authentication domains in the system.

Usage:

GET /ovirt-engine/api/domains

Will return the list of domains:

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

Table 6.163. Parameters summary

Name	Type	Direction	Summary
`domains`	Domain[]	Out	The list of domains.
`max`	Integer	In	Sets the maximum number of domains to return.

6.55.1.1. max

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

6.56. EngineKatelloErrata

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

Table 6.164. Methods summary

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

6.56.1. list GET

Retrieves the representation of the Katello errata.

GET /ovirt-engine/api/katelloerrata

You will receive response in XML like this one:

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

Table 6.165. Parameters summary

Name	Type	Direction	Summary
`errata`	KatelloErratum[]	Out	A representation of Katello errata.
`max`	Integer	In	Sets the maximum number of errata to return.

6.56.1.1. max

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

6.57. Event

A service to manage an event in the system.

Table 6.166. Methods summary

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

6.57.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.167. Parameters summary

Name	Type	Direction	Summary
`event`	Event	Out

6.57.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.168. Parameters summary

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

6.58. Events

A service to manage events in the system.

Table 6.169. Methods summary

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

6.58.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.170. Parameters summary

Name	Type	Direction	Summary
`event`	Event	In/Out

6.58.2. list GET

Get list of events.

GET /ovirt-engine/api/events

To the above request we get following response:

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

The following events occur:

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

Table 6.171. 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
`from`	Integer	In	Indicates the identifier of the the first event that should be returned.
`max`	Integer	In	Sets the maximum number of events to return.
`search`	String	In	The events service provides search queries similar to other resource services.

6.58.2.1. case_sensitive

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

6.58.2.2. from

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

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

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

6.58.2.3. max

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

6.58.2.4. 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.58.3. undelete POST

Table 6.172. Parameters summary

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

6.59. ExternalComputeResource

Table 6.173. Methods summary

Name	Summary
`get`

6.59.1. get GET

Table 6.174. Parameters summary

Name	Type	Direction	Summary
`resource`	ExternalComputeResource	Out

6.60. ExternalComputeResources

Table 6.175. Methods summary

Name	Summary
`list`

6.60.1. list GET

Table 6.176. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of resources to return.
`resources`	ExternalComputeResource[]	Out

6.60.1.1. max

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

6.61. ExternalDiscoveredHost

Table 6.177. Methods summary

Name	Summary
`get`

6.61.1. get GET

Table 6.178. Parameters summary

Name	Type	Direction	Summary
`host`	ExternalDiscoveredHost	Out

6.62. ExternalDiscoveredHosts

Table 6.179. Methods summary

Name	Summary
`list`

6.62.1. list GET

Table 6.180. Parameters summary

Name	Type	Direction	Summary
`hosts`	ExternalDiscoveredHost[]	Out
`max`	Integer	In	Sets the maximum number of hosts to return.

6.62.1.1. max

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

6.63. ExternalHost

Table 6.181. Methods summary

Name	Summary
`get`

6.63.1. get GET

Table 6.182. Parameters summary

Name	Type	Direction	Summary
`host`	ExternalHost	Out

6.64. ExternalHostGroup

Table 6.183. Methods summary

Name	Summary
`get`

6.64.1. get GET

Table 6.184. Parameters summary

Name	Type	Direction	Summary
`group`	ExternalHostGroup	Out

6.65. ExternalHostGroups

Table 6.185. Methods summary

Name	Summary
`list`

6.65.1. list GET

Table 6.186. Parameters summary

Name	Type	Direction	Summary
`groups`	ExternalHostGroup[]	Out
`max`	Integer	In	Sets the maximum number of groups to return.

6.65.1.1. max

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

6.66. ExternalHostProvider

Table 6.187. Methods summary

Name	Summary
`get`
`importcertificates`
`remove`
`testconnectivity`
`update`

6.66.1. get GET

Table 6.188. Parameters summary

Name	Type	Direction	Summary
`provider`	ExternalHostProvider	Out

6.66.2. importcertificates POST

Table 6.189. Parameters summary

Name	Type	Direction	Summary
`certificates`	Certificate[]	In

6.66.3. remove DELETE

Table 6.190. Parameters summary

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

6.66.4. testconnectivity POST

Table 6.191. Parameters summary

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

6.66.5. update PUT

Table 6.192. Parameters summary

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

6.67. ExternalHostProviders

Table 6.193. Methods summary

Name	Summary
`add`
`list`

6.67.1. add POST

Table 6.194. Parameters summary

Name	Type	Direction	Summary
`provider`	ExternalHostProvider	In/Out

6.67.2. list GET

Table 6.195. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of providers to return.
`providers`	ExternalHostProvider[]	Out

6.67.2.1. max

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

6.68. ExternalHosts

Table 6.196. Methods summary

Name	Summary
`list`

6.68.1. list GET

Table 6.197. Parameters summary

Name	Type	Direction	Summary
`hosts`	ExternalHost[]	Out
`max`	Integer	In	Sets the maximum number of hosts to return.

6.68.1.1. max

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

6.69. ExternalProvider

Table 6.198. Methods summary

Name	Summary
`importcertificates`
`testconnectivity`

6.69.1. importcertificates POST

Table 6.199. Parameters summary

Name	Type	Direction	Summary
`certificates`	Certificate[]	In

6.69.2. testconnectivity POST

Table 6.200. Parameters summary

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

6.70. ExternalProviderCertificate

Table 6.201. Methods summary

Name	Summary
`get`

6.70.1. get GET

Table 6.202. Parameters summary

Name	Type	Direction	Summary
`certificate`	Certificate	Out

6.71. ExternalProviderCertificates

Table 6.203. Methods summary

Name	Summary
`list`

6.71.1. list GET

Table 6.204. Parameters summary

Name	Type	Direction	Summary
`certificates`	Certificate[]	Out
`max`	Integer	In	Sets the maximum number of certificates to return.

6.71.1.1. max

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

6.72. ExternalVmImports

Provides capability to import external virtual machines.

Table 6.205. Methods summary

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

6.72.1. add POST

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

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

POST /externalvmimports

With request body of type ExternalVmImport, for example:

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

Table 6.206. Parameters summary

Name	Type	Direction	Summary
`import`	ExternalVmImport	In/Out

6.73. FenceAgent

Table 6.207. Methods summary

Name	Summary
`get`
`remove`
`update`

6.73.1. get GET

Table 6.208. Parameters summary

Name	Type	Direction	Summary
`agent`	Agent	Out

6.73.2. remove DELETE

Table 6.209. Parameters summary

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

6.73.3. update PUT

Table 6.210. Parameters summary

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

6.74. FenceAgents

Table 6.211. Methods summary

Name	Summary
`add`
`list`

6.74.1. add POST

Table 6.212. Parameters summary

Name	Type	Direction	Summary
`agent`	Agent	In/Out

6.74.2. list GET

Table 6.213. Parameters summary

Name	Type	Direction	Summary
`agents`	Agent[]	Out
`max`	Integer	In	Sets the maximum number of agents to return.

6.74.2.1. max

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

6.75. File

Table 6.214. Methods summary

Name	Summary
`get`

6.75.1. get GET

Table 6.215. Parameters summary

Name	Type	Direction	Summary
`file`	File	Out

6.76. Files

Provides a way for clients to list available files.

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

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

Table 6.216. Methods summary

Name	Summary
`list`

6.76.1. list GET

Table 6.217. 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.
`file`	File[]	Out
`max`	Integer	In	Sets the maximum number of files to return.
`search`	String	In	A query string used to restrict the returned files.

6.76.1.1. case_sensitive

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

6.76.1.2. max

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

6.77. Filter

Table 6.218. Methods summary

Name	Summary
`get`
`remove`

6.77.1. get GET

Table 6.219. Parameters summary

Name	Type	Direction	Summary
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`result`	Filter	Out

6.77.2. remove DELETE

Table 6.220. Parameters summary

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

6.78. Filters

Table 6.221. Methods summary

Name	Summary
`add`
`list`

6.78.1. add POST

Table 6.222. Parameters summary

Name	Type	Direction	Summary
`filter`	Filter	In/Out

6.78.2. list GET

Table 6.223. Parameters summary

Name	Type	Direction	Summary
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`filters`	Filter[]	Out
`max`	Integer	In	Sets the maximum number of filters to return.

6.78.2.1. max

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

6.79. GlusterBrick

This service manages a single gluster brick.

Table 6.224. Methods summary

Name	Summary
`get`	Get details of a brick.
`remove`	Removes a brick.
`replace`	Replaces this brick with a new one.

6.79.1. get GET

Get details of a brick.

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

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

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234

Which will return a response body like this:

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

Table 6.225. Parameters summary

Name	Type	Direction	Summary
`brick`	GlusterBrick	Out

6.79.2. remove DELETE

Removes a brick.

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

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

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234

Table 6.226. Parameters summary

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

6.79.3. replace POST

Replaces this brick with a new one.

Important

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

Table 6.227. Parameters summary

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

6.80. GlusterBricks

This service manages the gluster bricks in a gluster volume

Table 6.228. Methods summary

Name	Summary
`activate`	Activate the bricks post data migration of remove brick operation.
`add`	Adds a list of bricks to gluster volume.
`list`	Lists the bricks of a gluster volume.
`migrate`	Start migration of data prior to removing bricks.
`remove`	Removes bricks from gluster volume.
`stopmigrate`	Stops migration of data from bricks for a remove brick operation.

6.80.1. activate POST

Activate the bricks post data migration of remove brick operation.

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

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

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/activate

With a request body like this:

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>

Table 6.229. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the activation should be performed asynchronously.
`bricks`	GlusterBrick[]	In	The list of bricks that need to be re-activated.

6.80.2. add POST

Adds a list of bricks to gluster volume.

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

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

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

With a request body like this:

<bricks>
  <brick>
    <server_id>111</server_id>
    <brick_dir>/export/data/brick3</brick_dir>
  </brick>
</bricks>

Table 6.230. Parameters summary

Name	Type	Direction	Summary
`bricks`	GlusterBrick[]	In/Out	The list of bricks to be added to the volume
`replica_count`	Integer	In	Replica count of volume post add operation.
`stripe_count`	Integer	In	Stripe count of volume post add operation.

6.80.3. list GET

Lists the bricks of a gluster volume.

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

GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

Provides an output as below:

<bricks>
  <brick id="234">
    <name>host1:/rhgs/data/brick1</name>
    <brick_dir>/rhgs/data/brick1</brick_dir>
    <server_id>111</server_id>
    <status>up</status>
  </brick>
  <brick id="233">
    <name>host2:/rhgs/data/brick1</name>
    <brick_dir>/rhgs/data/brick1</brick_dir>
    <server_id>222</server_id>
    <status>up</status>
  </brick>
</bricks>

Table 6.231. Parameters summary

Name	Type	Direction	Summary
`bricks`	GlusterBrick[]	Out
`max`	Integer	In	Sets the maximum number of bricks to return.

6.80.3.1. max

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

6.80.4. migrate POST

Start migration of data prior to removing bricks.

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

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

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/migrate

With a request body like this:

<action>
  <bricks>
    <brick>
      <name>host1:/rhgs/brick1</name>
    </brick>
  </bricks>
</action>

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

Table 6.232. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the migration should be performed asynchronously.
`bricks`	GlusterBrick[]	In	List of bricks for which data migration needs to be started.

6.80.5. remove DELETE

Removes bricks from gluster volume.

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

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

DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks

With a request body like this:

<bricks>
  <brick>
    <name>host:brick_directory</name>
  </brick>
</bricks>

Table 6.233. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the remove should be performed asynchronously.
`bricks`	GlusterBrick[]	In	The list of bricks to be removed
`replica_count`	Integer	In	Replica count of volume post add operation.

6.80.6. stopmigrate POST

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

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

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

POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/stopmigrate

With a request body like this:

<bricks>
  <brick>
    <name>host:brick_directory</name>
  </brick>
</bricks>

Table 6.234. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the action should be performed asynchronously.
`bricks`	GlusterBrick[]	In	List of bricks for which data migration needs to be stopped.

6.80.6.1. bricks

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

6.81. GlusterHook

Table 6.235. Methods summary

Name	Summary
`disable`	Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the cluster.
`enable`	Resolves status conflict of hook among servers in cluster by disabling Gluster hook in all servers of the cluster.
`get`
`remove`	Removes the this Gluster hook from all servers in cluster and deletes it from the database.
`resolve`	Resolves missing hook conflict depending on the resolution type.

6.81.1. disable POST

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

Table 6.236. Parameters summary

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

6.81.2. enable POST

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

Table 6.237. Parameters summary

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

6.81.3. get GET

Table 6.238. Parameters summary

Name	Type	Direction	Summary
`hook`	GlusterHook	Out

6.81.4. remove DELETE

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

Table 6.239. Parameters summary

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

6.81.5. resolve POST

Resolves missing hook conflict depending on the resolution type.

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

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

Table 6.240. Parameters summary

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

6.82. GlusterHooks

Table 6.241. Methods summary

Name	Summary
`list`

6.82.1. list GET

Table 6.242. Parameters summary

Name	Type	Direction	Summary
`hooks`	GlusterHook[]	Out
`max`	Integer	In	Sets the maximum number of hooks to return.

6.82.1.1. max

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

6.83. GlusterVolume

This service manages a single gluster volume.

Table 6.243. Methods summary

Name	Summary
`get`	Get the gluster volume details.
`getprofilestatistics`	Get gluster volume profile statistics.
`rebalance`	Rebalance the gluster volume.
`remove`	Removes the gluster volume.
`resetalloptions`	Resets all the options set in the gluster volume.
`resetoption`	Resets a particular option in the gluster volume.
`setoption`	Sets a particular option in the gluster volume.
`start`	Starts the gluster volume.
`startprofile`	Start profiling the gluster volume.
`stop`	Stops the gluster volume.
`stopprofile`	Stop profiling the gluster volume.
`stoprebalance`	Stop rebalancing the gluster volume.

6.83.1. get GET

Get the gluster volume details.

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

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

This GET request will return the following output:

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

Table 6.244. Parameters summary

Name	Type	Direction	Summary
`volume`	GlusterVolume	Out	Representation of the gluster volume.

6.83.2. getprofilestatistics POST

Get gluster volume profile statistics.

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

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

Table 6.245. Parameters summary

Name	Type	Direction	Summary
`details`	GlusterVolumeProfileDetails	Out	Gluster volume profiling information returned from the action.

6.83.3. rebalance POST

Rebalance the gluster volume.

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

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

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

Table 6.246. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the rebalance should be performed asynchronously.
`fix_layout`	Boolean	In	If set to true, rebalance will only fix the layout so that new data added to the volume is distributed across all the hosts.
`force`	Boolean	In	Indicates if the rebalance should be force started.

6.83.3.1. fix_layout

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

6.83.3.2. force

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

6.83.4. remove DELETE

Removes the gluster volume.

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

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

Table 6.247. Parameters summary

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

6.83.5. resetalloptions POST

Resets all the options set in the gluster volume.

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

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

Table 6.248. Parameters summary

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

6.83.6. resetoption POST

Resets a particular option in the gluster volume.

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

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

With the following request body:

<action>
 <option name="option1"/>
</action>

Table 6.249. Parameters summary

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

6.83.7. setoption POST

Sets a particular option in the gluster volume.

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

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

With the following request body:

<action>
 <option name="option1" value="value1"/>
</action>

Table 6.250. Parameters summary

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

6.83.8. start POST

Starts the gluster volume.

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

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

Table 6.251. Parameters summary

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

6.83.8.1. force

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

6.83.9. startprofile POST

Start profiling the gluster volume.

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

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

Table 6.252. Parameters summary

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

6.83.10. stop POST

Stops the gluster volume.

Stopping a volume will make its data inaccessible.

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

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

Table 6.253. Parameters summary

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

6.83.11. stopprofile POST

Stop profiling the gluster volume.

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

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

Table 6.254. Parameters summary

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

6.83.12. stoprebalance POST

Stop rebalancing the gluster volume.

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

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

Table 6.255. Parameters summary

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

6.84. GlusterVolumes

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

Table 6.256. Methods summary

Name	Summary
`add`	Creates a new gluster volume.
`list`	Lists all gluster volumes in the cluster.

6.84.1. add POST

Creates a new gluster volume.

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

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

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

With the following request body:

<gluster_volume>
  <name>myvolume</name>
  <volume_type>replicate</volume_type>
  <replica_count>3</replica_count>
  <bricks>
    <brick>
      <server_id>server1</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
    <brick>
      <server_id>server2</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
    <brick>
      <server_id>server3</server_id>
      <brick_dir>/exp1</brick_dir>
    </brick>
  <bricks>
</gluster_volume>

Table 6.257. Parameters summary

Name	Type	Direction	Summary
`volume`	GlusterVolume	In/Out	The gluster volume definition from which to create the volume is passed as input and the newly created volume is returned.

6.84.2. list GET

Lists all gluster volumes in the cluster.

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

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

Table 6.258. 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.
`max`	Integer	In	Sets the maximum number of volumes to return.
`search`	String	In	A query string used to restrict the returned volumes.
`volumes`	GlusterVolume[]	Out

6.84.2.1. case_sensitive

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

6.84.2.2. max

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

6.85. Group

Table 6.259. Methods summary

Name	Summary
`get`
`remove`

6.85.1. get GET

Table 6.260. Parameters summary

Name	Type	Direction	Summary
`get`	Group	Out

6.85.2. remove DELETE

Table 6.261. Parameters summary

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

6.86. Groups

Table 6.262. Methods summary

Name	Summary
`add`	Add group from a directory service.
`list`

6.86.1. add POST

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

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

POST /ovirt-engine/api/groups

With a request body like this:

<group>
  <name>Developers</name>
  <domain>
    <name>internal-authz</name>
  </domain>
</group>

Table 6.263. Parameters summary

Name	Type	Direction	Summary
`group`	Group	In/Out

6.86.2. list GET

Table 6.264. 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.
`groups`	Group[]	Out
`max`	Integer	In	Sets the maximum number of groups to return.
`search`	String	In	A query string used to restrict the returned groups.

6.86.2.1. case_sensitive

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

6.86.2.2. max

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

6.87. Host

A service to manage a host.

Table 6.265. Methods summary

Name	Summary
`activate`	Activate the host for use, such as running virtual machines.
`approve`	Approve a pre-installed Hypervisor host for usage in the virtualization environment.
`commitnetconfig`	Marks the network configuration as good and persists it inside the host.
`deactivate`	Deactivate the host to perform maintenance tasks.
`enrollcertificate`	Enroll certificate of the host.
`fence`	Controls host’s power management device.
`forceselectspm`	Manually set a host as the storage pool manager (SPM).
`get`	Get the host details.
`install`	Install VDSM and related software on the host.
`iscsidiscover`	Discover iSCSI targets on the host, using the initiator details.
`iscsilogin`	Login to iSCSI targets on the host, using the target details.
`refresh`	Refresh the host devices and capabilities.
`remove`	Remove the host from the system.
`setupnetworks`	This method is used to change the configuration of the network interfaces of a host.
`unregisteredstoragedomainsdiscover`
`update`	Update the host properties.
`upgrade`	Upgrade VDSM and selected software on the host.
`upgradecheck`	Check if there are upgrades available for the host.

6.87.1. activate POST

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

Table 6.266. Parameters summary

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

6.87.2. approve POST

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

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

Table 6.267. Parameters summary

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

6.87.3. commitnetconfig POST

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

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

Important

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

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

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

With a request body like this:

<action/>

Table 6.268. Parameters summary

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

6.87.4. deactivate POST

Deactivate the host to perform maintenance tasks.

Table 6.269. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the deactivation should be performed asynchronously.
`reason`	String	In
`stop_gluster_service`	Boolean	In	Indicates if the gluster service should be stopped as part of deactivating the host.

6.87.4.1. stop_gluster_service

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

6.87.5. enrollcertificate POST

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

Table 6.270. Parameters summary

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

6.87.6. fence POST

Controls host’s power management device.

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

#!/bin/sh -ex

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

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

Table 6.271. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the fencing should be performed asynchronously.
`fence_type`	String	In
`power_management`	PowerManagement	Out

6.87.7. forceselectspm POST

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

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

With a request body like this:

<action/>

Table 6.272. Parameters summary

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

6.87.8. get GET

Get the host details.

Table 6.273. Parameters summary

Name	Type	Direction	Summary
`filter`	Boolean	In	Indicates if the results should be filtered according to the permissions of the user.
`host`	Host	Out

6.87.9. install POST

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

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

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

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

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

Important

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

Table 6.274. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the installation should be performed asynchronously.
`deploy_hosted_engine`	Boolean	In	When set to `true` it means this host should deploy also hosted engine components.
`host`	Host	In	This `override_iptables` property is used to indicate if the firewall configuration should be replaced by the default one.
`image`	String	In	When installing an oVirt node a image ISO file is needed.
`root_password`	String	In	The password of of the `root` user, used to connect to the host via SSH.
`ssh`	Ssh	In	The SSH details used to connect to the host.
`undeploy_hosted_engine`	Boolean	In	When set to `true` it means this host should un-deploy hosted engine components and this host will not function as part of the High Availability cluster.

6.87.9.1. deploy_hosted_engine

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

6.87.9.2. undeploy_hosted_engine

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

6.87.10. iscsidiscover POST

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

Table 6.275. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the discovery should be performed asynchronously.
`iscsi`	IscsiDetails	In	The target iSCSI device.
`iscsi_targets`	String[]	Out	The iSCSI targets.

6.87.11. iscsilogin POST

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

Table 6.276. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the login should be performed asynchronously.
`iscsi`	IscsiDetails	In	The target iSCSI device.

6.87.12. refresh POST

Refresh the host devices and capabilities.

Table 6.277. Parameters summary

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

6.87.13. remove DELETE

Remove the host from the system.

#!/bin/sh -ex

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

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

Table 6.278. Parameters summary

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

6.87.14. setupnetworks POST

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

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

#!/bin/sh -ex

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

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

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

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

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

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

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

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

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

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

Important

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

Table 6.279. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the action should be performed asynchronously.
`check_connectivity`	Boolean	In
`connectivity_timeout`	Integer	In
`modified_bonds`	HostNic[]	In
`modified_labels`	NetworkLabel[]	In
`modified_network_attachments`	NetworkAttachment[]	In
`removed_bonds`	HostNic[]	In
`removed_labels`	NetworkLabel[]	In
`removed_network_attachments`	NetworkAttachment[]	In
`synchronized_network_attachments`	NetworkAttachment[]	In

6.87.15. unregisteredstoragedomainsdiscover POST

Table 6.280. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the discovery should be performed asynchronously.
`iscsi`	IscsiDetails	In
`storage_domains`	StorageDomain[]	Out

6.87.16. update PUT

Update the host properties.

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

PUT /ovirt-engine/api/hosts/123

With request body like this:

<host>
  <os>
    <custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline>
  </os>
</host>

Table 6.281. Parameters summary

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

6.87.17. upgrade POST

Upgrade VDSM and selected software on the host.

Table 6.282. Parameters summary

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

6.87.18. upgradecheck POST

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

6.88. HostDevice

A service to access a particular device of a host.

Table 6.283. Methods summary

Name	Summary
`get`	Retrieve information about a particular host’s device.

6.88.1. get GET

Retrieve information about a particular host’s device.

An example of getting a host device:

GET /ovirt-engine/api/hosts/123/devices/456

<host_device href="/ovirt-engine/api/hosts/123/devices/456" id="456">
  <name>usb_1_9_1_1_0</name>
  <capability>usb</capability>
  <host href="/ovirt-engine/api/hosts/123" id="123"/>
  <parent_device href="/ovirt-engine/api/hosts/123/devices/789" id="789">
    <name>usb_1_9_1</name>
  </parent_device>
</host_device>

Table 6.284. Parameters summary

Name	Type	Direction	Summary
`device`	HostDevice	Out

6.89. HostDevices

A service to access host devices.

Table 6.285. Methods summary

Name	Summary
`list`	List the devices of a host.

6.89.1. list GET

List the devices of a host.

Table 6.286. Parameters summary

Name	Type	Direction	Summary
`devices`	HostDevice[]	Out
`max`	Integer	In	Sets the maximum number of devices to return.

6.89.1.1. max

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

6.90. HostHook

Table 6.287. Methods summary

Name	Summary
`get`

6.90.1. get GET

Table 6.288. Parameters summary

Name	Type	Direction	Summary
`hook`	Hook	Out

6.91. HostHooks

Table 6.289. Methods summary

Name	Summary
`list`

6.91.1. list GET

Table 6.290. Parameters summary

Name	Type	Direction	Summary
`hooks`	Hook[]	Out
`max`	Integer	In	Sets the maximum number of hooks to return.

6.91.1.1. max

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

6.92. HostNic

A service to manage a network interface of a host.

Table 6.291. Methods summary

Name	Summary
`get`
`updatevirtualfunctionsconfiguration`	The action updates virtual function configuration in case the current resource represents an SR-IOV enabled NIC.

6.92.1. get GET

Table 6.292. Parameters summary

Name	Type	Direction	Summary
`nic`	HostNic	Out

6.92.2. updatevirtualfunctionsconfiguration POST

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

allNetworksAllowed
numberOfVirtualFunctions

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

Table 6.293. Parameters summary

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

6.93. HostNics

A service to manage the network interfaces of a host.

Table 6.294. Methods summary

Name	Summary
`list`

6.93.1. list GET

Table 6.295. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of NICs to return.
`nics`	HostNic[]	Out

6.93.1.1. max

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

6.94. HostNumaNode

Table 6.296. Methods summary

Name	Summary
`get`

6.94.1. get GET

Table 6.297. Parameters summary

Name	Type	Direction	Summary
`node`	NumaNode	Out

6.95. HostNumaNodes

Table 6.298. Methods summary

Name	Summary
`list`

6.95.1. list GET

Table 6.299. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of nodes to return.
`nodes`	NumaNode[]	Out

6.95.1.1. max

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

6.96. HostStorage

A service to manage host storages.

Table 6.300. Methods summary

Name	Summary
`list`	Get list of storages.

6.96.1. list GET

Get list of storages.

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

The XML response you get will be like this one:

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

Table 6.301. Parameters summary

Name	Type	Direction	Summary
`report_status`	Boolean	In	Indicates if the status of the LUNs in the storage should be checked.
`storages`	HostStorage[]	Out	Retrieved list of storages.

6.96.1.1. report_status

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

The default is true for backward compatibility.

Here an example with the LUN status :

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

Here an example without the LUN status :

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

6.97. Hosts

A service that manages hosts.

Table 6.302. Methods summary

Name	Summary
`add`	Creates a new host.
`list`	Get a list of all available hosts.

6.97.1. add POST

Creates a new host.

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

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

POST /ovirt-engine/api/hosts

With the following request body:

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

Note

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

Important

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

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

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

Table 6.303. Parameters summary

Name	Type	Direction	Summary
`deploy_hosted_engine`	Boolean	In	When set to `true` it means this host should deploy also hosted engine components.
`host`	Host	In/Out	The host definition from which to create the new host is passed as parameter, and the newly created host is returned.
`undeploy_hosted_engine`	Boolean	In	When set to `true` it means this host should un-deploy hosted engine components and this host will not function as part of the High Availability cluster.

6.97.1.1. deploy_hosted_engine

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

6.97.1.2. undeploy_hosted_engine

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

6.97.2. list GET

Get a list of all available hosts.

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

GET /ovirt-engine/api/hosts

The response body will be something like this:

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

Table 6.304. Parameters summary

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

6.97.2.1. case_sensitive

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

6.97.2.2. max

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

6.98. Icon

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

Table 6.305. Methods summary

Name	Summary
`get`	Get an icon.

6.98.1. get GET

Get an icon.

GET /ovirt-engine/api/icons/123

You will get a XML response like this one:

<icon id="123">
  <data>Some binary data here</data>
  <media_type>image/png</media_type>
</icon>

Table 6.306. Parameters summary

Name	Type	Direction	Summary
`icon`	Icon	Out	Retrieved icon.

6.99. Icons

A service to manage icons.

Table 6.307. Methods summary

Name	Summary
`list`	Get a list of icons.

6.99.1. list GET

Get a list of icons.

GET /ovirt-engine/api/icons

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

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

Table 6.308. Parameters summary

Name	Type	Direction	Summary
`icons`	Icon[]	Out	Retrieved list of icons.
`max`	Integer	In	Sets the maximum number of icons to return.

6.99.1.1. max

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

6.100. Image

Table 6.309. Methods summary

Name	Summary
`get`
`import`	Imports an image.

6.100.1. get GET

Table 6.310. Parameters summary

Name	Type	Direction	Summary
`image`	Image	Out

6.100.2. import POST

Imports an image.

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

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

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

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

Table 6.311. Parameters summary

Name	Type	Direction	Summary
`async`	Boolean	In	Indicates if the import should be performed asynchronously.
`cluster`	Cluster	In	The cluster to which the image should be imported if the `import_as_template` parameter is set to `true`.
`disk`	Disk	In	The disk to import.
`import_as_template`	Boolean	In	Specifies if a template should be created from the imported disk.
`storage_domain`	StorageDomain	In	The storage domain to which the disk should be imported.
`template`	Template	In	The name of the template being created if the `import_as_template` parameter is set to `true`.

6.101. ImageTransfer

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

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

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

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

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

E.g:

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

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

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

For example:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For example:

transfer_service.finalize()

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

Table 6.312. Methods summary

Name	Summary
`extend`	Extend the image transfer session.
`finalize`	After finishing to transfer the data, finalize the transfer.
`get`	Get the image transfer entity.
`pause`	Pause the image transfer session.
`resume`	Resume the image transfer session.

6.101.1. extend POST

Extend the image transfer session.

6.101.2. finalize POST

After finishing to transfer the data, finalize the transfer.

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

6.101.3. get GET

Get the image transfer entity.

Table 6.313. Parameters summary

Name	Type	Direction	Summary
`image_transfer`	ImageTransfer	Out

6.101.4. pause POST

Pause the image transfer session.

6.101.5. resume POST

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

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

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

6.102. ImageTransfers

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

Table 6.314. Methods summary

Name	Summary
`add`	Add a new image transfer.
`list`	Retrieves the list of image transfers that are currently being performed.

6.102.1. add POST

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

Table 6.315. Parameters summary

Name	Type	Direction	Summary
`image_transfer`	ImageTransfer	In/Out

6.102.2. list GET

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

Table 6.316. Parameters summary

Name	Type	Direction	Summary
`image_transfer`	ImageTransfer[]	Out

6.103. Images

Table 6.317. Methods summary

Name	Summary
`list`

6.103.1. list GET

Table 6.318. Parameters summary

Name	Type	Direction	Summary
`images`	Image[]	Out
`max`	Integer	In	Sets the maximum number of images to return.

6.103.1.1. max

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

6.104. InstanceType

Table 6.319. Methods summary

Name	Summary
`get`	Get a specific instance type and it’s attributes.
`remove`	Removes a specific instance type from the system.
`update`	Update a specific instance type and it’s attributes.

6.104.1. get GET

Get a specific instance type and it’s attributes.

GET /ovirt-engine/api/instancetypes/123

Table 6.320. Parameters summary

Name	Type	Direction	Summary
`instance_type`	InstanceType	Out

6.104.2. remove DELETE

Removes a specific instance type from the system.

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

DELETE /ovirt-engine/api/instancetypes/123

Table 6.321. Parameters summary

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

6.104.3. update PUT

Update a specific instance type and it’s attributes.

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

PUT /ovirt-engine/api/instancetypes/123

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

<instance_type>
  <memory>1073741824</memory>
  <cpu>
    <topology>
      <cores>1</cores>
      <sockets>2</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
</instance_type>

Table 6.322. Parameters summary

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

6.105. InstanceTypeGraphicsConsole

Table 6.323. Methods summary

Name	Summary
`get`	Gets graphics console configuration of the instance type.
`remove`	Remove the graphics console from the instance type.

6.105.1. get GET

Gets graphics console configuration of the instance type.

Table 6.324. Parameters summary

Name	Type	Direction	Summary
`console`	GraphicsConsole	Out	The information about the graphics console of the instance type.

6.105.2. remove DELETE

Remove the graphics console from the instance type.

Table 6.325. Parameters summary

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

6.106. InstanceTypeGraphicsConsoles

Table 6.326. Methods summary

Name	Summary
`add`	Add new graphics console to the instance type.
`list`	Lists all the configured graphics consoles of the instance type.

6.106.1. add POST

Add new graphics console to the instance type.

Table 6.327. Parameters summary

Name	Type	Direction	Summary
`console`	GraphicsConsole	In/Out

6.106.2. list GET

Lists all the configured graphics consoles of the instance type.

Table 6.328. Parameters summary

Name	Type	Direction	Summary
`consoles`	GraphicsConsole[]	Out	The list of graphics consoles of the instance type.
`max`	Integer	In	Sets the maximum number of consoles to return.

6.106.2.1. max

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

6.107. InstanceTypeNic

Table 6.329. Methods summary

Name	Summary
`get`	Gets network interface configuration of the instance type.
`remove`	Remove the network interface from the instance type.
`update`	Updates the network interface configuration of the instance type.

6.107.1. get GET

Gets network interface configuration of the instance type.

Table 6.330. Parameters summary

Name	Type	Direction	Summary
`nic`	Nic	Out

6.107.2. remove DELETE

Remove the network interface from the instance type.

Table 6.331. Parameters summary

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

6.107.3. update PUT

Updates the network interface configuration of the instance type.

Table 6.332. Parameters summary

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

6.108. InstanceTypeNics

Table 6.333. Methods summary

Name	Summary
`add`	Add new network interface to the instance type.
`list`	Lists all the configured network interface of the instance type.

6.108.1. add POST

Add new network interface to the instance type.

Table 6.334. Parameters summary

Name	Type	Direction	Summary
`nic`	Nic	In/Out

6.108.2. list GET

Lists all the configured network interface of the instance type.

Table 6.335. Parameters summary

Name	Type	Direction	Summary
`max`	Integer	In	Sets the maximum number of NICs to return.
`nics`	Nic[]	Out
`search`	String	In	A query string used to restrict the returned templates.

6.108.2.1. max

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

6.109. InstanceTypeWatchdog

Table 6.336. Methods summary