Chapter 6. Services This section enumerates all the services that are available in the API. 6.1. AffinityGroup This service manages a single affinity group. Table 6.1. Methods summary Name Summary get Retrieve the affinity group details. remove Remove the affinity group. update Update the affinity group. 6.1.1. get GET Retrieve the affinity group details. <affinity_group id="00000000-0000-0000-0000-000000000000"> <name>AF_GROUP_001</name> <cluster id="00000000-0000-0000-0000-000000000000"/> <positive>true</positive> <enforcing>true</enforcing> </affinity_group> Table 6.2. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . group AffinityGroup Out The affinity group. 6.1.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.1.2. remove DELETE Remove the affinity group. 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 Adds a virtual machine to the affinity group. list List all virtual machines assigned to this affinity group. 6.3.1. add POST Adds a virtual machine to the affinity group. For example, to add the virtual machine 789 to the affinity group 456 of cluster 123 , send a request like this: With the following body: <vm id="789"/> 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. The order of the returned virtual machines isn't guaranteed. Table 6.9. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of virtual machines to return. vms Vm[] Out 6.3.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.3.2.2. 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: And use the following example in its body: <affinity_group> <name>AF_GROUP_001</name> <hosts_rule> <enforcing>true</enforcing> <positive>true</positive> </hosts_rule> <vms_rule> <enabled>false</enabled> </vms_rule> </affinity_group> Table 6.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. The order of the affinity groups results isn't guaranteed. Table 6.12. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . groups AffinityGroup[] Out The list of existing affinity groups. max Integer In Sets the maximum number of affinity groups to return. 6.4.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.4.2.2. max Sets the maximum number of 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 follow String In Indicates which inner links should be followed . label AffinityLabel Out 6.5.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.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 follow String In Indicates which inner links should be followed . host Host Out 6.6.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.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. The order of the returned hosts isn't guaranteed. Table 6.20. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . hosts Host[] Out 6.7.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.8. 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 follow String In Indicates which inner links should be followed . vm Vm Out 6.8.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.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 virtual machines 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 virtual machines with the label. The order of the returned virtual machines isn't guaranteed. Table 6.25. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . vms Vm[] Out 6.9.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.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. The order of the returned labels isn't guaranteed. Table 6.28. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . labels AffinityLabel[] Out max Integer In Sets the maximum number of labels to return. 6.10.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.10.2.2. max Sets the maximum number of labels to return. If not specified all the labels are returned. 6.11. Area This annotation is intended to specify what oVirt area is the annotated concept related to. Currently the following areas are in use, and they are closely related to the oVirt teams, but not necessarily the same: Infrastructure Network SLA Storage Virtualization A concept may be associated to more than one area, or to no area. The value of this annotation is intended for reporting only, and it doesn't affect at all the generated code or the validity of the model 6.12. 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.12.1. get GET Retrieves details about the attached label. Table 6.30. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . label AffinityLabel Out 6.12.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.12.2. remove DELETE Removes the label from an entity. Does not touch the label itself. 6.13. 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.13.1. add POST Attaches a label to an entity. Table 6.32. Parameters summary Name Type Direction Summary label AffinityLabel In/Out 6.13.2. list GET Lists all labels that are attached to an entity. The order of the returned entities isn't guaranteed. Table 6.33. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . label AffinityLabel[] Out 6.13.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.14. AssignedCpuProfile Table 6.34. Methods summary Name Summary get remove 6.14.1. get GET Table 6.35. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . profile CpuProfile Out 6.14.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.14.2. remove DELETE Table 6.36. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.15. AssignedCpuProfiles Table 6.37. Methods summary Name Summary add Add a new cpu profile for the cluster. list List the CPU profiles assigned to the cluster. 6.15.1. add POST Add a new cpu profile for the cluster. Table 6.38. Parameters summary Name Type Direction Summary profile CpuProfile In/Out 6.15.2. list GET List the CPU profiles assigned to the cluster. The order of the returned CPU profiles isn't guaranteed. Table 6.39. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of profiles to return. profiles CpuProfile[] Out 6.15.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.15.2.2. max Sets the maximum number of profiles to return. If not specified all the profiles are returned. 6.16. AssignedDiskProfile Table 6.40. Methods summary Name Summary get remove 6.16.1. get GET Table 6.41. Parameters summary Name Type Direction Summary disk_profile DiskProfile Out follow String In Indicates which inner links should be followed . 6.16.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.16.2. remove DELETE Table 6.42. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.17. AssignedDiskProfiles Table 6.43. Methods summary Name Summary add Add a new disk profile for the storage domain. list Returns the list of disk profiles assigned to the storage domain. 6.17.1. add POST Add a new disk profile for the storage domain. Table 6.44. Parameters summary Name Type Direction Summary profile DiskProfile In/Out 6.17.2. list GET Returns the list of disk profiles assigned to the storage domain. The order of the returned disk profiles isn't guaranteed. Table 6.45. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of profiles to return. profiles DiskProfile[] Out 6.17.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.17.2.2. max Sets the maximum number of profiles to return. If not specified all the profiles are returned. 6.18. 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.18.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: 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: 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: 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.18.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: <permissions> <permission id="456"> <cluster id="123"/> <role id="789"/> <user id="451"/> </permission> <permission id="654"> <cluster id="123"/> <role id="789"/> <group id="127"/> </permission> </permissions> The order of the returned permissions isn't guaranteed. Table 6.48. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . permissions Permission[] Out The list of permissions. 6.18.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.19. AssignedRoles Represents a roles sub-collection, for example scoped by user. Table 6.49. Methods summary Name Summary list Returns the roles assigned to the permission. 6.19.1. list GET Returns the roles assigned to the permission. The order of the returned roles isn't guaranteed. Table 6.50. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of roles to return. roles Role[] Out 6.19.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.19.1.2. max Sets the maximum number of roles to return. If not specified all the roles are returned. 6.20. 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.20.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: <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 follow String In Indicates which inner links should be followed . tag Tag Out The assigned tag. 6.20.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.20.2. remove DELETE 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: Table 6.53. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.21. 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.21.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: 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.21.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: <tags> <tag href="/ovirt-engine/api/tags/222" id="222"> <name>mytag</name> <description>mytag</description> <vm href="/ovirt-engine/api/vms/123" id="123"/> </tag> </tags> The order of the returned tags isn't guaranteed. Table 6.56. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of tags to return. tags Tag[] Out The list of assigned tags. 6.21.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.21.2.2. max Sets the maximum number of tags to return. If not specified all the tags are returned. 6.22. AssignedVnicProfile Table 6.57. Methods summary Name Summary get remove 6.22.1. get GET Table 6.58. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . profile VnicProfile Out 6.22.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.22.2. remove DELETE Table 6.59. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.23. AssignedVnicProfiles Table 6.60. Methods summary Name Summary add Add a new virtual network interface card profile for the network. list Returns the list of VNIC profiles assifned to the network. 6.23.1. add POST Add a new virtual network interface card profile for the network. Table 6.61. Parameters summary Name Type Direction Summary profile VnicProfile In/Out 6.23.2. list GET Returns the list of VNIC profiles assifned to the network. The order of the returned VNIC profiles isn't guaranteed. Table 6.62. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of profiles to return. profiles VnicProfile[] Out 6.23.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.23.2.2. max Sets the maximum number of profiles to return. If not specified all the profiles are returned. 6.24. 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.24.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. 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.24.2. deactivate POST This operation deactivates an attached storage domain. Once the storage domain is deactivated it will not be used with the data center. For example, to deactivate storage domain 456 , send the following request: With a request body like this: <action/> If the force parameter is true then the operation will succeed, even if the OVF update which takes place before the deactivation of the storage domain failed. If the force parameter is false and the OVF update failed, the deactivation of the storage domain will also fail. Table 6.65. Parameters summary Name Type Direction Summary async Boolean In Indicates if the deactivation should be performed asynchronously. force Boolean In Indicates if the operation should succeed and the storage domain should be moved to a deactivated state, even if the OVF update for the storage domain failed. 6.24.2.1. force Indicates if the operation should succeed and the storage domain should be moved to a deactivated state, even if the OVF update for the storage domain failed. For example, to deactivate storage domain 456 using force flag, send the following request: With a request body like this: <action> <force>true</force> <action> This parameter is optional, and the default value is false . 6.24.3. get GET Table 6.66. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . storage_domain StorageDomain Out 6.24.3.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.24.4. remove DELETE Table 6.67. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.25. AttachedStorageDomainDisk Manages a single disk available in a storage domain attached to a data center. Important Since version 4.2 of the engine this service is intended only to list disks available in the storage domain, and to register unregistered disks. All the other operations, like copying a disk, moving a disk, etc, have been deprecated and will be removed in the future. To perform those operations use the service that manages all the disks of the system , or the service that manages an specific disk . Table 6.68. Methods summary Name Summary copy Copies a disk to the specified storage domain. export Exports a disk to an export storage domain. get Retrieves the description of the disk. move Moves a disk to another storage domain. register Registers an unregistered disk. remove Removes a disk. sparsify Sparsify the disk. update Updates the disk. 6.25.1. copy POST Copies a disk to the specified storage domain. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To copy a disk use the copy operation of the service that manages that disk. Table 6.69. Parameters summary Name Type Direction Summary disk Disk In Description of the resulting disk. storage_domain StorageDomain In The storage domain where the new disk will be created. 6.25.2. export POST Exports a disk to an export storage domain. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To export a disk use the export operation of the service that manages that disk. Table 6.70. Parameters summary Name Type Direction Summary storage_domain StorageDomain In The export storage domain where the disk should be exported to. 6.25.3. get GET Retrieves the description of the disk. Table 6.71. Parameters summary Name Type Direction Summary disk Disk Out The description of the disk. follow String In Indicates which inner links should be followed . 6.25.3.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.25.4. move POST Moves a disk to another storage domain. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To move a disk use the move operation of the service that manages that disk. Table 6.72. Parameters summary Name Type Direction Summary async Boolean In Indicates if the move should be performed asynchronously. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. storage_domain StorageDomain In The storage domain where the disk will be moved to. 6.25.5. register POST Registers an unregistered disk. 6.25.6. remove DELETE Removes a disk. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk. 6.25.7. sparsify POST Sparsify the disk. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk. 6.25.8. update PUT Updates the disk. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To update a disk use the update operation of the service that manages that disk. Table 6.73. Parameters summary Name Type Direction Summary disk Disk In/Out The update to apply to the disk. 6.26. AttachedStorageDomainDisks Manages the collection of disks available inside an storage domain that is attached to a data center. Table 6.74. Methods summary Name Summary add Adds or registers a disk. list Retrieve the list of disks that are available in the storage domain. 6.26.1. add POST Adds or registers a disk. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To add a new disk use the add operation of the service that manages the disks of the system. To register an unregistered disk use the register operation of the service that manages that disk. Table 6.75. Parameters summary Name Type Direction Summary disk Disk In/Out The disk to add or register. unregistered Boolean In Indicates if a new disk should be added or if an existing unregistered disk should be registered. 6.26.1.1. unregistered Indicates if a new disk should be added or if an existing unregistered disk should be registered. If the value is true then the identifier of the disk to register needs to be provided. For example, to register the disk with id 456 send a request like this: With a request body like this: <disk id="456"/> If the value is false then a new disk will be created in the storage domain. In that case the provisioned_size , format and name attributes are mandatory. For example, to create a new copy on write disk of 1 GiB, send a request like this: With a request body like this: <disk> <name>mydisk</name> <format>cow</format> <provisioned_size>1073741824</provisioned_size> </disk> The default value is false . 6.26.2. list GET Retrieve the list of disks that are available in the storage domain. Table 6.76. Parameters summary Name Type Direction Summary disks Disk[] Out List of retrieved disks. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of disks to return. 6.26.2.1. disks List of retrieved disks. The order of the returned disks isn't guaranteed. 6.26.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.26.2.3. max Sets the maximum number of disks to return. If not specified all the disks are returned. 6.27. AttachedStorageDomains Manages the storage domains attached to a data center. Table 6.77. Methods summary Name Summary add Attaches an existing storage domain to the data center. list Returns the list of storage domains attached to the data center. 6.27.1. add POST Attaches an existing storage domain to the data center. Table 6.78. Parameters summary Name Type Direction Summary storage_domain StorageDomain In/Out The storage domain to attach to the data center. 6.27.2. list GET Returns the list of storage domains attached to the data center. The order of the returned storage domains isn't guaranteed. Table 6.79. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of storage domains to return. storage_domains StorageDomain[] Out A list of storage domains that are attached to the data center. 6.27.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.27.2.2. max Sets the maximum number of storage domains to return. If not specified all the storage domains are returned. 6.28. Balance Table 6.80. Methods summary Name Summary get remove 6.28.1. get GET Table 6.81. Parameters summary Name Type Direction Summary balance Balance Out filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . 6.28.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.28.2. remove DELETE Table 6.82. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.29. Balances Table 6.83. Methods summary Name Summary add Add a balance module to a specified user defined scheduling policy. list Returns the list of balance modules used by the scheduling policy. 6.29.1. add POST Add a balance module to a specified user defined scheduling policy. Table 6.84. Parameters summary Name Type Direction Summary balance Balance In/Out 6.29.2. list GET Returns the list of balance modules used by the scheduling policy. The order of the returned balance modules isn't guaranteed. Table 6.85. Parameters summary Name Type Direction Summary balances Balance[] Out filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of balances to return. 6.29.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.29.2.2. max Sets the maximum number of balances to return. If not specified all the balances are returned. 6.30. Bookmark A service to manage a bookmark. Table 6.86. Methods summary Name Summary get Get a bookmark. remove Remove a bookmark. update Update a bookmark. 6.30.1. get GET Get a bookmark. An example for getting a bookmark: <bookmark href="/ovirt-engine/api/bookmarks/123" id="123"> <name>example_vm</name> <value>vm: name=example*</value> </bookmark> Table 6.87. Parameters summary Name Type Direction Summary bookmark Bookmark Out The requested bookmark. follow String In Indicates which inner links should be followed . 6.30.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.30.2. remove DELETE Remove a bookmark. An example for removing a bookmark: Table 6.88. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.30.3. update PUT Update a bookmark. An example for updating a bookmark: With the request body: <bookmark> <name>new_example_vm</name> <value>vm: name=new_example*</value> </bookmark> Table 6.89. 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.31. Bookmarks A service to manage bookmarks. Table 6.90. Methods summary Name Summary add Adding a new bookmark. list Listing all the available bookmarks. 6.31.1. add POST Adding a new bookmark. Example of adding a bookmark: <bookmark> <name>new_example_vm</name> <value>vm: name=new_example*</value> </bookmark> Table 6.91. Parameters summary Name Type Direction Summary bookmark Bookmark In/Out The added bookmark. 6.31.2. list GET Listing all the available bookmarks. Example of listing bookmarks: <bookmarks> <bookmark href="/ovirt-engine/api/bookmarks/123" id="123"> <name>database</name> <value>vm: name=database*</value> </bookmark> <bookmark href="/ovirt-engine/api/bookmarks/456" id="456"> <name>example</name> <value>vm: name=example*</value> </bookmark> </bookmarks> The order of the returned bookmarks isn't guaranteed. Table 6.92. Parameters summary Name Type Direction Summary bookmarks Bookmark[] Out The list of available bookmarks. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of bookmarks to return. 6.31.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.31.2.2. max Sets the maximum number of bookmarks to return. If not specified all the bookmarks are returned. 6.32. Cluster A service to manage a specific cluster. Table 6.93. Methods summary Name Summary get Gets information about the cluster. remove Removes the cluster from the system. resetemulatedmachine syncallnetworks Synchronizes all networks on the cluster. update Updates information about the cluster. 6.32.1. get GET Gets information about the cluster. An example of getting a cluster: <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.94. Parameters summary Name Type Direction Summary cluster Cluster Out filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . 6.32.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.32.2. remove DELETE Removes the cluster from the system. Table 6.95. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.32.3. resetemulatedmachine POST Table 6.96. Parameters summary Name Type Direction Summary async Boolean In Indicates if the reset should be performed asynchronously. 6.32.4. syncallnetworks POST Synchronizes all networks on the cluster. With a request body like this: <action/> Table 6.97. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.32.5. update PUT Updates information about the cluster. Only the specified fields are updated; others remain unchanged. For example, to update the cluster's CPU: With a request body like this: <cluster> <cpu> <type>Intel Haswell-noTSX Family</type> </cpu> </cluster> Table 6.98. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. cluster Cluster In/Out 6.33. ClusterEnabledFeature Represents a feature enabled for the cluster. Table 6.99. Methods summary Name Summary get Provides the information about the cluster feature enabled. remove Disables a cluster feature. 6.33.1. get GET Provides the information about the cluster feature enabled. For example, to find details of the enabled feature 456 for cluster 123 , send a request like this: That will return a ClusterFeature object containing the name: <cluster_feature id="456"> <name>libgfapi_supported</name> </cluster_feature> Table 6.100. Parameters summary Name Type Direction Summary feature ClusterFeature Out Retrieved cluster feature that's enabled. follow String In Indicates which inner links should be followed . 6.33.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.33.2. remove DELETE Disables a cluster feature. For example, to disable the feature 456 of cluster 123 send a request like this: 6.34. ClusterEnabledFeatures Provides information about the additional features that are enabled for this cluster. The features that are enabled are the available features for the cluster level Table 6.101. Methods summary Name Summary add Enable an additional feature for a cluster. list Lists the additional features enabled for the cluster. 6.34.1. add POST Enable an additional feature for a cluster. For example, to enable a feature 456 on cluster 123 , send a request like this: The request body should look like this: <cluster_feature id="456"/> Table 6.102. Parameters summary Name Type Direction Summary feature ClusterFeature In/Out 6.34.2. list GET Lists the additional features enabled for the cluster. For example, to get the features enabled for cluster 123 send a request like this: This will return a list of features: <enabled_features> <cluster_feature id="123"> <name>test_feature</name> </cluster_feature> ... </enabled_features> Table 6.103. Parameters summary Name Type Direction Summary features ClusterFeature[] Out Retrieved features. follow String In Indicates which inner links should be followed . 6.34.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.35. ClusterExternalProviders This service lists external providers. Table 6.104. Methods summary Name Summary list Returns the list of external providers. 6.35.1. list GET Returns the list of external providers. The order of the returned list of providers is not guaranteed. Table 6.105. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . providers ExternalProvider[] Out 6.35.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.36. ClusterFeature Represents a feature enabled for the cluster level Table 6.106. Methods summary Name Summary get Provides the information about the a cluster feature supported by a cluster level. 6.36.1. get GET Provides the information about the a cluster feature supported by a cluster level. For example, to find details of the cluster feature 456 for cluster level 4.1, send a request like this: That will return a ClusterFeature object containing the name: <cluster_feature id="456"> <name>libgfapi_supported</name> </cluster_feature> Table 6.107. Parameters summary Name Type Direction Summary feature ClusterFeature Out Retrieved cluster feature. follow String In Indicates which inner links should be followed . 6.36.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.37. ClusterFeatures Provides information about the cluster features that are supported by a cluster level. Table 6.108. Methods summary Name Summary list Lists the cluster features supported by the cluster level. 6.37.1. list GET Lists the cluster features supported by the cluster level. This will return a list of cluster features supported by the cluster level: <cluster_features> <cluster_feature id="123"> <name>test_feature</name> </cluster_feature> ... </cluster_features> Table 6.109. Parameters summary Name Type Direction Summary features ClusterFeature[] Out Retrieved features. follow String In Indicates which inner links should be followed . 6.37.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.38. ClusterLevel Provides information about a specific cluster level. See the ClusterLevels service for more information. Table 6.110. Methods summary Name Summary get Provides the information about the capabilities of the specific cluster level managed by this service. 6.38.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: 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.111. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . level ClusterLevel Out Retreived cluster level. 6.38.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.39. 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.112. Methods summary Name Summary list Lists the cluster levels supported by the system. 6.39.1. list GET Lists the cluster levels supported by the system. This will return a list of available cluster levels. <cluster_levels> <cluster_level id="4.0"> ... </cluster_level> ... </cluster_levels> The order of the returned cluster levels isn't guaranteed. Table 6.113. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . levels ClusterLevel[] Out Retrieved cluster levels. 6.39.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.40. ClusterNetwork A service to manage a specific cluster network. Table 6.114. 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.40.1. get GET Retrieves the cluster network details. Table 6.115. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . network Network Out The cluster network. 6.40.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.40.2. remove DELETE Unassigns the network from a cluster. 6.40.3. update PUT Updates the network in the cluster. Table 6.116. Parameters summary Name Type Direction Summary network Network In/Out The cluster network. 6.41. ClusterNetworks A service to manage cluster networks. Table 6.117. Methods summary Name Summary add Assigns the network to a cluster. list Lists the networks that are assigned to the cluster. 6.41.1. add POST Assigns the network to a cluster. Post a request like in the example below to assign the network to a cluster: Use the following example in its body: <network id="123" /> Table 6.118. Parameters summary Name Type Direction Summary network Network In/Out The network object to be assigned to the cluster. 6.41.2. list GET Lists the networks that are assigned to the cluster. The order of the returned clusters isn't guaranteed. Table 6.119. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of networks to return. networks Network[] Out The list of networks that are assigned to the cluster. 6.41.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.41.2.2. max Sets the maximum number of networks to return. If not specified, all the networks are returned. 6.42. Clusters A service to manage clusters. Table 6.120. Methods summary Name Summary add Creates a new cluster. list Returns the list of clusters of the system. 6.42.1. add POST Creates a new cluster. This requires the name , cpu.type , and data_center attributes. Identify the data center with either the id or name attribute. With a request body like this: <cluster> <name>mycluster</name> <cpu> <type>Intel Penryn Family</type> </cpu> <data_center id="123"/> </cluster> To create a cluster with an external network provider to be deployed on every host that is added to the cluster, send a request like this: With a request body containing a reference to the desired provider: <cluster> <name>mycluster</name> <cpu> <type>Intel Penryn Family</type> </cpu> <data_center id="123"/> <external_network_providers> <external_provider name="ovirt-provider-ovn"/> </external_network_providers> </cluster> Table 6.121. Parameters summary Name Type Direction Summary cluster Cluster In/Out 6.42.2. list GET Returns the list of clusters of the system. The order of the returned clusters is guaranteed only if the sortby clause is included in the search parameter. Table 6.122. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search should be performed taking case into account. clusters Cluster[] Out filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of clusters to return. search String In A query string used to restrict the returned clusters. 6.42.2.1. case_sensitive Indicates if the search should be performed taking case into account. The default value is true , which means that case is taken into account. To search ignoring case, set it to false . 6.42.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.42.2.3. max Sets the maximum number of clusters to return. If not specified, all the clusters are returned. 6.43. Copyable Table 6.123. Methods summary Name Summary copy 6.43.1. copy POST Table 6.124. Parameters summary Name Type Direction Summary async Boolean In Indicates if the copy should be performed asynchronously. 6.44. CpuProfile Table 6.125. Methods summary Name Summary get remove update Update the specified cpu profile in the system. 6.44.1. get GET Table 6.126. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . profile CpuProfile Out 6.44.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.44.2. remove DELETE Table 6.127. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.44.3. update PUT Update the specified cpu profile in the system. Table 6.128. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. profile CpuProfile In/Out 6.45. CpuProfiles Table 6.129. Methods summary Name Summary add Add a new cpu profile to the system. list Returns the list of CPU profiles of the system. 6.45.1. add POST Add a new cpu profile to the system. Table 6.130. Parameters summary Name Type Direction Summary profile CpuProfile In/Out 6.45.2. list GET Returns the list of CPU profiles of the system. The order of the returned list of CPU profiles isn't guranteed. Table 6.131. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of profiles to return. profile CpuProfile[] Out 6.45.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.45.2.2. max Sets the maximum number of profiles to return. If not specified all the profiles are returned. 6.46. DataCenter A service to manage a data center. Table 6.132. Methods summary Name Summary get Get a data center. remove Removes the data center. update Updates the data center. 6.46.1. get GET Get a data center. An example of getting a data center: <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.133. Parameters summary Name Type Direction Summary data_center DataCenter Out filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . 6.46.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.46.2. remove DELETE Removes the data center. 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.134. 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.46.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.46.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: With a request body like this: <data_center> <name>myupdatedname</name> <description>An updated description for the data center</description> </data_center> Table 6.135. 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.47. DataCenterNetwork A service to manage a specific data center network. Table 6.136. Methods summary Name Summary get Retrieves the data center network details. remove Removes the network. update Updates the network in the data center. 6.47.1. get GET Retrieves the data center network details. Table 6.137. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . network Network Out The data center network. 6.47.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.47.2. remove DELETE Removes the network. 6.47.3. update PUT Updates the network in the data center. Table 6.138. Parameters summary Name Type Direction Summary network Network In/Out The data center network. 6.48. DataCenterNetworks A service to manage data center networks. Table 6.139. Methods summary Name Summary add Create a new network in a data center. list Lists networks in the data center. 6.48.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 . Use the following example in its body: <network> <name>mynetwork</name> </network> Table 6.140. Parameters summary Name Type Direction Summary network Network In/Out The network object to be created in the data center. 6.48.2. list GET Lists networks in the data center. The order of the returned list of networks isn't guaranteed. Table 6.141. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of networks to return. networks Network[] Out The list of networks which are in the data center. 6.48.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.48.2.2. max Sets the maximum number of networks to return. If not specified, all the networks are returned. 6.49. DataCenters A service to manage data centers. Table 6.142. Methods summary Name Summary add Creates a new data center. list Lists the data centers. 6.49.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: With a request body like this: <data_center> <name>mydc</name> <local>false</local> </data_center> Table 6.143. Parameters summary Name Type Direction Summary data_center DataCenter In/Out The data center that is being added. For more information, see Data Center Properties and Changing the Data Center Storage Type in the Administration Guide. 6.49.2. list GET Lists the data centers. The following request retrieves a representation of the data centers: The above request performed with curl : curl \ --request GET \ --cacert /etc/pki/ovirt-engine/ca.pem \ --header "Version: 4" \ --header "Accept: application/xml" \ --user "admin@internal:mypassword" \ https://myengine.example.com/ovirt-engine/api/datacenters This is what an example response could look like: <data_center href="/ovirt-engine/api/datacenters/123" id="123"> <name>Default</name> <description>The default Data Center</description> <link href="/ovirt-engine/api/datacenters/123/networks" rel="networks"/> <link href="/ovirt-engine/api/datacenters/123/storagedomains" rel="storagedomains"/> <link href="/ovirt-engine/api/datacenters/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/datacenters/123/clusters" rel="clusters"/> <link href="/ovirt-engine/api/datacenters/123/qoss" rel="qoss"/> <link href="/ovirt-engine/api/datacenters/123/iscsibonds" rel="iscsibonds"/> <link href="/ovirt-engine/api/datacenters/123/quotas" rel="quotas"/> <local>false</local> <quota_mode>disabled</quota_mode> <status>up</status> <supported_versions> <version> <major>4</major> <minor>0</minor> </version> </supported_versions> <version> <major>4</major> <minor>0</minor> </version> </data_center> Note the id code of your Default data center. This code identifies this data center in relation to other resources of your virtual environment. The data center also contains a link to the storage domains collection. The data center uses this collection to attach storage domains from the storage domains main collection. The order of the returned list of data centers is guaranteed only if the sortby clause is included in the search parameter. Table 6.144. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. data_centers DataCenter[] Out filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of data centers to return. search String In A query string used to restrict the returned data centers. 6.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. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.49.2.3. max Sets the maximum number of data centers to return. If not specified all the data centers are returned. 6.50. Disk Manages a single disk. Table 6.145. Methods summary Name Summary copy This operation copies a disk to the specified storage domain. export Exports a disk to an export storage domain. get Retrieves the description of the disk. move Moves a disk to another storage domain. reduce Reduces the size of the disk image. refreshlun Refreshes a direct LUN disk with up-to-date information from the storage. remove Removes a disk. sparsify Sparsify the disk. update This operation updates the disk with the appropriate parameters. 6.50.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: With a request body like this: <action> <storage_domain id="456"/> <disk> <name>mydisk</name> </disk> </action> If the disk profile or the quota used currently by the disk aren't defined for the new storage domain, then they can be explicitly specified. If they aren't then the first available disk profile and the default quota are used. For example, to explicitly use disk profile 987 and quota 753 send a request body like this: <action> <storage_domain id="456"/> <disk_profile id="987"/> <quota id="753"/> </action> Table 6.146. Parameters summary Name Type Direction Summary async Boolean In Indicates if the copy should be performed asynchronously. disk Disk In disk_profile DiskProfile In Disk profile for the disk in the new storage domain. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. quota Quota In Quota for the disk in the new storage domain. storage_domain StorageDomain In The storage domain where the new disk will be created. 6.50.1.1. disk_profile Disk profile for the disk in the new storage domain. Disk profiles are defined for storage domains, so the old disk profile will not exist in the new storage domain. If this parameter is not used, the first disk profile from the new storage domain to which the user has permissions will be assigned to the disk. 6.50.1.2. quota Quota for the disk in the new storage domain. This optional parameter can be used to specify new quota for the disk, because the current quota may not be defined for the new storage domain. If this parameter is not used and the old quota is not defined for the new storage domain, the default (unlimited) quota will be assigned to the disk. 6.50.1.3. storage_domain The storage domain where the new disk will be created. Can be specified using the id or name attributes. For example, to copy a disk to the storage domain named mydata send a request like this: With a request body like this: <action> <storage_domain> <name>mydata</name> </storage_domain> </action> 6.50.2. export POST Exports a disk to an export storage domain. Table 6.147. 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.50.3. get GET Retrieves the description of the disk. Table 6.148. Parameters summary Name Type Direction Summary all_content Boolean In Indicates if all of the attributes of the disk should be included in the response. disk Disk Out The description of the disk. follow String In Indicates which inner links should be followed . 6.50.3.1. all_content Indicates if all of the attributes of the disk should be included in the response. By default the following disk attributes are excluded: vms For example, to retrieve the complete representation of disk '123': 6.50.3.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.50.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: With the following request body: <action> <storage_domain id="456"/> </action> If the disk profile or the quota used currently by the disk aren't defined for the new storage domain, then they can be explicitly specified. If they aren't then the first available disk profile and the default quota are used. For example, to explicitly use disk profile 987 and quota 753 send a request body like this: <action> <storage_domain id="456"/> <disk_profile id="987"/> <quota id="753"/> </action> Table 6.149. Parameters summary Name Type Direction Summary async Boolean In Indicates if the move should be performed asynchronously. disk_profile DiskProfile In Disk profile for the disk in the new storage domain. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. quota Quota In Quota for the disk in the new storage domain. storage_domain StorageDomain In 6.50.4.1. disk_profile Disk profile for the disk in the new storage domain. Disk profiles are defined for storage domains, so the old disk profile will not exist in the new storage domain. If this parameter is not used, the first disk profile from the new storage domain to which the user has permissions will be assigned to the disk. 6.50.4.2. quota Quota for the disk in the new storage domain. This optional parameter can be used to specify new quota for the disk, because the current quota may not be defined for the new storage domain. If this parameter is not used and the old quota is not defined for the new storage domain, the default (unlimited) quota will be assigned to the disk. 6.50.5. reduce POST Reduces the size of the disk image. Invokes reduce on the logical volume (i.e. this is only applicable for block storage domains). This is applicable for floating disks and disks attached to non-running virtual machines. There is no need to specify the size as the optimal size is calculated automatically. Table 6.150. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.50.6. refreshlun POST Refreshes a direct LUN disk with up-to-date information from the storage. Refreshing a direct LUN disk is useful when: The LUN was added using the API without the host parameter, and therefore does not contain any information from the storage (see DisksService::add ). New information about the LUN is available on the storage and you want to update the LUN with it. To refresh direct LUN disk 123 using host 456 , send the following request: With the following request body: <action> <host id='456'/> </action> Table 6.151. Parameters summary Name Type Direction Summary host Host In The host that will be used to refresh the direct LUN disk. 6.50.7. remove DELETE Removes a disk. Table 6.152. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.50.8. sparsify POST Sparsify the disk. Sparsification frees space in the disk image that is not used by its filesystem. As a result, the image will occupy less space on the storage. Currently sparsification works only on disks without snapshots. Disks having derived disks are also not allowed. 6.50.9. update PUT This operation updates the disk with the appropriate parameters. The only field that can be updated is qcow_version . For example, update disk can be facilitated using the following request: With a request body like this: <disk> <qcow_version>qcow2_v3</qcow_version> </disk> Since the backend operation is asynchronous the disk element which will be returned to the user might not be synced with the changed properties. Table 6.153. Parameters summary Name Type Direction Summary disk Disk In/Out The update to apply to the disk. 6.51. DiskAttachment This service manages the attachment of a disk to a virtual machine. Table 6.154. 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.51.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: <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.155. Parameters summary Name Type Direction Summary attachment DiskAttachment Out follow String In Indicates which inner links should be followed . 6.51.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.51.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: Table 6.156. 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.51.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.51.3. update PUT Update the disk attachment and the disk properties within it. Table 6.157. Parameters summary Name Type Direction Summary disk_attachment DiskAttachment In/Out 6.52. 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.158. 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.52.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 : 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.159. Parameters summary Name Type Direction Summary attachment DiskAttachment In/Out The disk attachment to add to the virtual machine. 6.52.2. list GET List the disk that are attached to the virtual machine. The order of the returned list of disks attachments isn't guaranteed. Table 6.160. Parameters summary Name Type Direction Summary attachments DiskAttachment[] Out A list of disk attachments that are attached to the virtual machine. follow String In Indicates which inner links should be followed . 6.52.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.53. DiskProfile Table 6.161. Methods summary Name Summary get remove update Update the specified disk profile in the system. 6.53.1. get GET Table 6.162. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . profile DiskProfile Out 6.53.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.53.2. remove DELETE Table 6.163. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.53.3. update PUT Update the specified disk profile in the system. Table 6.164. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. profile DiskProfile In/Out 6.54. DiskProfiles Table 6.165. Methods summary Name Summary add Add a new disk profile to the system. list Returns the list of disk profiles of the system. 6.54.1. add POST Add a new disk profile to the system. Table 6.166. Parameters summary Name Type Direction Summary profile DiskProfile In/Out 6.54.2. list GET Returns the list of disk profiles of the system. The order of the returned list of disk profiles isn't guaranteed. Table 6.167. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of profiles to return. profile DiskProfile[] Out 6.54.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.54.2.2. max Sets the maximum number of profiles to return. If not specified all the profiles are returned. 6.55. DiskSnapshot Table 6.168. Methods summary Name Summary get remove 6.55.1. get GET Table 6.169. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . snapshot DiskSnapshot Out 6.55.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.55.2. remove DELETE Table 6.170. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.56. DiskSnapshots Manages the collection of disk snapshots available in an storage domain. Table 6.171. Methods summary Name Summary list Returns the list of disk snapshots of the storage domain. 6.56.1. list GET Returns the list of disk snapshots of the storage domain. The order of the returned list of disk snapshots isn't guaranteed. Table 6.172. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of snapshots to return. snapshots DiskSnapshot[] Out 6.56.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.56.1.2. max Sets the maximum number of snapshots to return. If not specified all the snapshots are returned. 6.57. Disks Manages the collection of disks available in the system. Table 6.173. Methods summary Name Summary add Adds a new floating disk. list Get list of disks. 6.57.1. add POST Adds a new floating disk. There are three types of disks that can be added - disk image, direct LUN and Cinder disk. Adding a new image disk: When creating a new floating image Disk , the API requires the storage_domain , provisioned_size and format attributes. Note that block storage domains (i.e., storage domains with the storage type of iSCSI or FCP) don't support the combination of the raw format with sparse=true , so sparse=false must be stated explicitly. To create a new floating image disk with specified provisioned_size , format and name on a storage domain with an id 123 , send a request as follows: 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: 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: With a request body as follows: <disk> <openstack_volume_type> <name>myceph</name> </openstack_volume_type> <storage_domains> <storage_domain> <name>cinderDomain</name> </storage_domain> </storage_domains> <provisioned_size>1073741824</provisioned_size> <interface>virtio</interface> <format>raw</format> </disk> Adding a floating disks in order to upload disk snapshots: Since version 4.2 of the engine it is possible to upload disks with snapshots. This request should be used to create the base image of the images chain (The consecutive disk snapshots (images), should be created using disk-attachments element when creating a snapshot). The disk has to be created with the same disk identifier and image identifier of the uploaded image. I.e. the identifiers should be saved as part of the backup process. The image identifier can be also fetched using the qemu-img info command. For example, if the disk image is stored into a file named b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img : USD qemu-img info b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img image: b548366b-fb51-4b41-97be-733c887fe305 file format: qcow2 virtual size: 1.0G (1073741824 bytes) disk size: 196K cluster_size: 65536 backing file: ad58716a-1fe9-481f-815e-664de1df04eb backing file format: raw To create a disk with with the disk identifier and image identifier obtained with the qemu-img info command shown above, send a request like this: With a request body as follows: <disk id="b7a4c6c5-443b-47c5-967f-6abc79675e8b"> <image_id>b548366b-fb51-4b41-97be-733c887fe305</image_id> <storage_domains> <storage_domain id="123"/> </storage_domains> <name>mydisk</name> <provisioned_size>1048576</provisioned_size> <format>cow</format> </disk> Table 6.174. Parameters summary Name Type Direction Summary disk Disk In/Out The disk. 6.57.2. list GET Get list of disks. You will get a XML response which will look like this one: <disks> <disk id="123"> <actions>...</actions> <name>MyDisk</name> <description>MyDisk description</description> <link href="/ovirt-engine/api/disks/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/disks/123/statistics" rel="statistics"/> <actual_size>5345845248</actual_size> <alias>MyDisk alias</alias> ... <status>ok</status> <storage_type>image</storage_type> <wipe_after_delete>false</wipe_after_delete> <disk_profile id="123"/> <quota id="123"/> <storage_domains>...</storage_domains> </disk> ... </disks> The order of the returned list of disks is guaranteed only if the sortby clause is included in the search parameter. Table 6.175. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. disks Disk[] Out List of retrieved disks. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of disks to return. search String In A query string used to restrict the returned disks. 6.57.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.57.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.57.2.3. max Sets the maximum number of disks to return. If not specified all the disks are returned. 6.58. Domain A service to view details of an authentication domain in the system. Table 6.176. Methods summary Name Summary get Gets the authentication domain information. 6.58.1. get GET Gets the authentication domain information. Usage: 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.177. Parameters summary Name Type Direction Summary domain Domain Out The authentication domain. follow String In Indicates which inner links should be followed . 6.58.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.59. DomainGroup Table 6.178. Methods summary Name Summary get 6.59.1. get GET Table 6.179. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . get Group Out 6.59.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.60. DomainGroups Table 6.180. Methods summary Name Summary list Returns the list of groups. 6.60.1. list GET Returns the list of groups. The order of the returned list of groups isn't guaranteed. Table 6.181. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. follow String In Indicates which inner links should be followed . groups Group[] Out max Integer In Sets the maximum number of groups to return. search String In A query string used to restrict the returned groups. 6.60.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.60.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.60.1.3. max Sets the maximum number of groups to return. If not specified all the groups are returned. 6.61. DomainUser A service to view a domain user in the system. Table 6.182. Methods summary Name Summary get Gets the domain user information. 6.61.1. get GET Gets the domain user information. Usage: 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.183. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . user User Out The domain user. 6.61.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.62. DomainUserGroups A service that shows a user's group membership in the AAA extension. Table 6.184. Methods summary Name Summary list Returns the list of groups that the user is a member of. 6.62.1. list GET Returns the list of groups that the user is a member of. Table 6.185. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . groups Group[] Out The list of groups that the user is a member of. 6.62.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.63. DomainUsers A service to list all domain users in the system. Table 6.186. Methods summary Name Summary list List all the users in the domain. 6.63.1. list GET List all the users in the domain. Usage: Will return the list of users in the domain: <users> <user href="/ovirt-engine/api/domains/5678/users/1234" id="1234"> <name>admin</name> <namespace>*</namespace> <principal>admin</principal> <user_name>admin@internal-authz</user_name> <domain href="/ovirt-engine/api/domains/5678" id="5678"> <name>internal-authz</name> </domain> <groups/> </user> </users> The order of the returned list of users isn't guaranteed. Table 6.187. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of users to return. search String In A query string used to restrict the returned users. users User[] Out The list of users in the domain. 6.63.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.63.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.63.1.3. max Sets the maximum number of users to return. If not specified all the users are returned. 6.64. Domains A service to list all authentication domains in the system. Table 6.188. Methods summary Name Summary list List all the authentication domains in the system. 6.64.1. list GET List all the authentication domains in the system. Usage: Will return the list of domains: <domains> <domain href="/ovirt-engine/api/domains/5678" id="5678"> <name>internal-authz</name> <link href="/ovirt-engine/api/domains/5678/users" rel="users"/> <link href="/ovirt-engine/api/domains/5678/groups" rel="groups"/> <link href="/ovirt-engine/api/domains/5678/users?search={query}" rel="users/search"/> <link href="/ovirt-engine/api/domains/5678/groups?search={query}" rel="groups/search"/> </domain> </domains> The order of the returned list of domains isn't guaranteed. Table 6.189. Parameters summary Name Type Direction Summary domains Domain[] Out The list of domains. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of domains to return. 6.64.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.64.1.2. max Sets the maximum number of domains to return. If not specified all the domains are returned. 6.65. EngineKatelloErrata A service to manage Katello errata assigned to the engine. The information is retrieved from Katello. Table 6.190. Methods summary Name Summary list Retrieves the representation of the Katello errata. 6.65.1. list GET Retrieves the representation of the Katello errata. You will receive response in XML like this one: <katello_errata> <katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123"> <name>RHBA-2013:XYZ</name> <description>The description of the erratum</description> <title>some bug fix update</title> <type>bugfix</type> <issued>2013-11-20T02:00:00.000+02:00</issued> <solution>Few guidelines regarding the solution</solution> <summary>Updated packages that fix one bug are now available for XYZ</summary> <packages> <package> <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name> </package> ... </packages> </katello_erratum> ... </katello_errata> The order of the returned list of erratum isn't guaranteed. Table 6.191. Parameters summary Name Type Direction Summary errata KatelloErratum[] Out A representation of Katello errata. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of errata to return. 6.65.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.65.1.2. max Sets the maximum number of errata to return. If not specified all the errata are returned. 6.66. Event A service to manage an event in the system. Table 6.192. Methods summary Name Summary get Get an event. remove Removes an event from internal audit log. 6.66.1. get GET Get an event. An example of getting an event: <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.193. Parameters summary Name Type Direction Summary event Event Out follow String In Indicates which inner links should be followed . 6.66.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.66.2. remove DELETE Removes an event from internal audit log. An event can be removed by sending following request Table 6.194. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.67. Events A service to manage events in the system. Table 6.195. Methods summary Name Summary add Adds an external event to the internal audit log. list Get list of events. undelete 6.67.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: 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: Note When using links, like the vm in the example, only the id attribute is accepted. The name attribute, if provided, is simply ignored. Table 6.196. Parameters summary Name Type Direction Summary event Event In/Out 6.67.2. list GET Get list of events. To the above request we get following response: <events> <event href="/ovirt-engine/api/events/2" id="2"> <description>User admin@internal-authz logged out.</description> <code>31</code> <correlation_id>1e892ea9</correlation_id> <custom_id>-1</custom_id> <flood_rate>30</flood_rate> <origin>oVirt</origin> <severity>normal</severity> <time>2016-09-14T12:14:34.541+02:00</time> <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/> </event> <event href="/ovirt-engine/api/events/1" id="1"> <description>User admin logged in.</description> <code>30</code> <correlation_id>1fbd81f4</correlation_id> <custom_id>-1</custom_id> <flood_rate>30</flood_rate> <origin>oVirt</origin> <severity>normal</severity> <time>2016-09-14T11:54:35.229+02:00</time> <user href="/ovirt-engine/api/users/57d91d48-00da-0137-0138-000000000244" id="57d91d48-00da-0137-0138-000000000244"/> </event> </events> The following events occur: id="1" - The API logs in the admin user account. id="2" - The API logs out of the admin user account. The order of the returned list of events is always garanteed. If the sortby clause is included in the search parameter, then the events will be ordered according to that clause. If the sortby clause isn't included, then the events will be sorted by the numeric value of the id attribute, starting with the highest value. This, combined with the max parameter, simplifies obtaining the most recent event: Table 6.197. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. events Event[] Out follow String In Indicates which inner links should be followed . from Integer In Indicates the event index after which events should be returned. max Integer In Sets the maximum number of events to return. search String In The events service provides search queries similar to other resource services. 6.67.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.67.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.67.2.3. from Indicates the event index after which events should be returned. The indexes of events are strictly increasing, so when this parameter is used only the events with greater indexes will be returned. For example, the following request will return only the events with indexes greater than 123 : This parameter is optional, and if not specified then the first event returned will be most recently generated. 6.67.2.4. max Sets the maximum number of events to return. If not specified all the events are returned. 6.67.2.5. search The events service provides search queries similar to other resource services. We can search by providing specific severity. 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: Below example paginates event resources. The URL-encoded request is: Increase the page value to view the page of results. 6.67.3. undelete POST Table 6.198. Parameters summary Name Type Direction Summary async Boolean In Indicates if the un-delete should be performed asynchronously. 6.68. ExternalComputeResource Manages a single external compute resource. Compute resource is a term of host external provider. The external provider also needs to know to where the provisioned host needs to register. The login details of the engine are saved as a compute resource in the external provider side. Table 6.199. Methods summary Name Summary get Retrieves external compute resource details. 6.68.1. get GET Retrieves external compute resource details. For example, to get the details of compute resource 234 of provider 123 , send a request like this: It will return a response like this: <external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234"> <name>hostname</name> <provider>oVirt</provider> <url>https://hostname/api</url> <user>admin@internal</user> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_compute_resource> Table 6.200. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . resource ExternalComputeResource Out External compute resource information 6.68.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.69. ExternalComputeResources Manages a collection of external compute resources. Compute resource is a term of host external provider. The external provider also needs to know to where the provisioned host needs to register. The login details of the engine is saved as a compute resource in the external provider side. Table 6.201. Methods summary Name Summary list Retrieves a list of external compute resources. 6.69.1. list GET Retrieves a list of external compute resources. For example, to retrieve the compute resources of external host provider 123 , send a request like this: It will return a response like this: <external_compute_resources> <external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234"> <name>hostname</name> <provider>oVirt</provider> <url>https://address/api</url> <user>admin@internal</user> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_compute_resource> ... </external_compute_resources> The order of the returned list of compute resources isn't guaranteed. Table 6.202. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of resources to return. resources ExternalComputeResource[] Out List of external computer resources. 6.69.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.69.1.2. max Sets the maximum number of resources to return. If not specified all the resources are returned. 6.70. ExternalDiscoveredHost This service manages a single discovered host. Table 6.203. Methods summary Name Summary get Get discovered host info. 6.70.1. get GET Get discovered host info. Retrieves information about an host that is managed in external provider management system, such as Foreman. The information includes hostname, address, subnet, base image and more. For example, to get the details of host 234 from provider 123 , send a request like this: The result will be like this: <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/234" id="234"> <name>mac001a4ad04040</name> <ip>10.34.67.43</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:40</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host> Table 6.204. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . host ExternalDiscoveredHost Out Host's hardware and config information. 6.70.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.71. ExternalDiscoveredHosts This service manages external discovered hosts. Table 6.205. Methods summary Name Summary list Get list of discovered hosts' information. 6.71.1. list GET Get list of discovered hosts' information. Discovered hosts are fetched from third-party providers such as Foreman. To list all discovered hosts for provider 123 send the following: <external_discovered_hosts> <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/456" id="456"> <name>mac001a4ad04031</name> <ip>10.34.67.42</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:31</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host> <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/789" id="789"> <name>mac001a4ad04040</name> <ip>10.34.67.43</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:40</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host> ... </external_discovered_hosts> The order of the returned list of hosts isn't guaranteed. Table 6.206. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . hosts ExternalDiscoveredHost[] Out List of discovered hosts max Integer In Sets the maximum number of hosts to return. 6.71.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.71.1.2. max Sets the maximum number of hosts to return. If not specified all the hosts are returned. 6.72. ExternalHost Table 6.207. Methods summary Name Summary get 6.72.1. get GET Table 6.208. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . host ExternalHost Out 6.72.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.73. ExternalHostGroup This service manages a single host group information. Host group is a term of host provider - the host group includes provision details that are applied to new discovered host. Information such as subnet, operating system, domain, etc. Table 6.209. Methods summary Name Summary get Get host group information. 6.73.1. get GET Get host group information. For example, to get the details of hostgroup 234 of provider 123 , send a request like this: It will return a response like this: <external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234"> <name>rhel7</name> <architecture_name>x86_64</architecture_name> <domain_name>s.com</domain_name> <operating_system_name>RedHat 7.3</operating_system_name> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_host_group> Table 6.210. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . group ExternalHostGroup Out Host group information. 6.73.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.74. ExternalHostGroups This service manages hostgroups. Table 6.211. Methods summary Name Summary list Get host groups list from external host provider. 6.74.1. list GET Get host groups list from external host provider. Host group is a term of host providers - the host group includes provision details. This API returns all possible hostgroups exposed by the external provider. For example, to get the details of all host groups of provider 123 , send a request like this: The response will be like this: <external_host_groups> <external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234"> <name>rhel7</name> <architecture_name>x86_64</architecture_name> <domain_name>example.com</domain_name> <operating_system_name>RedHat 7.3</operating_system_name> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_host_group> ... </external_host_groups> The order of the returned list of host groups isn't guaranteed. Table 6.212. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . groups ExternalHostGroup[] Out List of all hostgroups available for external host provider max Integer In Sets the maximum number of groups to return. 6.74.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.74.1.2. max Sets the maximum number of groups to return. If not specified all the groups are returned. 6.75. ExternalHostProvider Represents an external host provider, such as Foreman or Satellite. See https://www.theforeman.org/ for more details on Foreman. See https://access.redhat.com/products/red-hat-satellite for more details on Red Hat Satellite. Table 6.213. Methods summary Name Summary get Get external host provider information Host provider, Foreman or Satellite, can be set as an external provider in ovirt. importcertificates Import the SSL certificates of the external host provider. remove testconnectivity In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. update Update the specified external host provider in the system. 6.75.1. get GET Get external host provider information Host provider, Foreman or Satellite, can be set as an external provider in ovirt. To see details about specific host providers attached to ovirt use this API. For example, to get the details of host provider 123 , send a request like this: The response will be like this: <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"> <name>mysatellite</name> <requires_authentication>true</requires_authentication> <url>https://mysatellite.example.com</url> <username>admin</username> </external_host_provider> Table 6.214. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . provider ExternalHostProvider Out 6.75.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.75.2. importcertificates POST Import the SSL certificates of the external host provider. Table 6.215. Parameters summary Name Type Direction Summary certificates Certificate[] In 6.75.3. remove DELETE Table 6.216. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.75.4. testconnectivity POST In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. Table 6.217. Parameters summary Name Type Direction Summary async Boolean In Indicates if the test should be performed asynchronously. 6.75.5. update PUT Update the specified external host provider in the system. Table 6.218. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. provider ExternalHostProvider In/Out 6.76. ExternalHostProviders Table 6.219. Methods summary Name Summary add Adds a new external host provider to the system. list Returns the list of external host providers. 6.76.1. add POST Adds a new external host provider to the system. Table 6.220. Parameters summary Name Type Direction Summary provider ExternalHostProvider In/Out 6.76.2. list GET Returns the list of external host providers. The order of the returned list of host providers is not guaranteed. Table 6.221. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of providers to return. providers ExternalHostProvider[] Out search String In A query string used to restrict the returned external host providers. 6.76.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.76.2.2. max Sets the maximum number of providers to return. If not specified, all the providers are returned. 6.77. ExternalHosts Table 6.222. Methods summary Name Summary list Return the list of external hosts. 6.77.1. list GET Return the list of external hosts. The order of the returned list of hosts isn't guaranteed. Table 6.223. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . hosts ExternalHost[] Out max Integer In Sets the maximum number of hosts to return. 6.77.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.77.1.2. max Sets the maximum number of hosts to return. If not specified all the hosts are returned. 6.78. ExternalNetworkProviderConfiguration Describes how an external network provider is provisioned by the system on the host. Table 6.224. Methods summary Name Summary get Returns the information about an external network provider on the host. 6.78.1. get GET Returns the information about an external network provider on the host. Table 6.225. Parameters summary Name Type Direction Summary configuration ExternalNetworkProviderConfiguration Out follow String In Indicates which inner links should be followed . 6.78.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.79. ExternalNetworkProviderConfigurations A service to list all external network providers provisioned by the system on the host. Table 6.226. Methods summary Name Summary list Returns the list of all external network providers on the host. 6.79.1. list GET Returns the list of all external network providers on the host. The order of the returned list of networks is not guaranteed. Table 6.227. Parameters summary Name Type Direction Summary configurations ExternalNetworkProviderConfiguration[] Out follow String In Indicates which inner links should be followed . 6.79.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.80. ExternalProvider Provides capability to manage external providers. Table 6.228. Methods summary Name Summary importcertificates Import the SSL certificates of the external host provider. testconnectivity In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. 6.80.1. importcertificates POST Import the SSL certificates of the external host provider. Table 6.229. Parameters summary Name Type Direction Summary certificates Certificate[] In 6.80.2. testconnectivity POST In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. Table 6.230. Parameters summary Name Type Direction Summary async Boolean In Indicates if the test should be performed asynchronously. 6.81. ExternalProviderCertificate A service to view specific certificate for external provider. Table 6.231. Methods summary Name Summary get Get specific certificate. 6.81.1. get GET Get specific certificate. And here is sample response: <certificate id="0"> <organization>provider.example.com</organization> <subject>CN=provider.example.com</subject> <content>...</content> </certificate> Table 6.232. Parameters summary Name Type Direction Summary certificate Certificate Out The details of the certificate. follow String In Indicates which inner links should be followed . 6.81.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.82. ExternalProviderCertificates A service to view certificates for external provider. Table 6.233. Methods summary Name Summary list Returns the chain of certificates presented by the external provider. 6.82.1. list GET Returns the chain of certificates presented by the external provider. And here is sample response: <certificates> <certificate id="789">...</certificate> ... </certificates> The order of the returned certificates is always guaranteed to be the sign order: the first is the certificate of the server itself, the second the certificate of the CA that signs the first, so on. Table 6.234. Parameters summary Name Type Direction Summary certificates Certificate[] Out List containing certificate details. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of certificates to return. 6.82.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.82.1.2. max Sets the maximum number of certificates to return. If not specified all the certificates are returned. 6.83. ExternalVmImports Provides capability to import external virtual machines. Table 6.235. Methods summary Name Summary add This operation is used to import a virtual machine from external hypervisor, such as KVM, XEN or VMware. 6.83.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: 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.236. Parameters summary Name Type Direction Summary import ExternalVmImport In/Out 6.84. FenceAgent A service to manage fence agent for a specific host. Table 6.237. Methods summary Name Summary get Gets details of this fence agent. remove Removes a fence agent for a specific host. update Update a fencing-agent. 6.84.1. get GET Gets details of this fence agent. And here is sample response: <agent id="0"> <type>apc</type> <order>1</order> <ip>192.168.1.101</ip> <user>user</user> <password>xxx</password> <port>9</port> <options>name1=value1, name2=value2</options> </agent> Table 6.238. Parameters summary Name Type Direction Summary agent Agent Out Fence agent details. follow String In Indicates which inner links should be followed . 6.84.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.84.2. remove DELETE Removes a fence agent for a specific host. Table 6.239. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.84.3. update PUT Update a fencing-agent. Table 6.240. Parameters summary Name Type Direction Summary agent Agent In/Out Fence agent details. async Boolean In Indicates if the update should be performed asynchronously. 6.85. FenceAgents A service to manage fence agents for a specific host. Table 6.241. Methods summary Name Summary add Add a new fencing-agent to the host. list Returns the list of fencing agents configured for the host. 6.85.1. add POST Add a new fencing-agent to the host. Table 6.242. Parameters summary Name Type Direction Summary agent Agent In/Out 6.85.2. list GET Returns the list of fencing agents configured for the host. And here is sample response: <agents> <agent id="0"> <type>apc</type> <order>1</order> <ip>192.168.1.101</ip> <user>user</user> <password>xxx</password> <port>9</port> <options>name1=value1, name2=value2</options> </agent> </agents> The order of the returned list of fencing agents isn't guaranteed. Table 6.243. Parameters summary Name Type Direction Summary agents Agent[] Out List of fence agent details. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of agents to return. 6.85.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.85.2.2. max Sets the maximum number of agents to return. If not specified all the agents are returned. 6.86. File Table 6.244. Methods summary Name Summary get 6.86.1. get GET Table 6.245. Parameters summary Name Type Direction Summary file File Out follow String In Indicates which inner links should be followed . 6.86.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.87. Files Provides a way for clients to list available files. This service is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks (VFDs) that an administrator uploads. The addition of a CD-ROM device to a virtual machine requires an ISO image from the files of an ISO storage domain. Table 6.246. Methods summary Name Summary list Returns the list of ISO images and virtual floppy disks available in the storage domain. 6.87.1. list GET Returns the list of ISO images and virtual floppy disks available in the storage domain. The order of the returned list is not guaranteed. If the refresh parameter is false , the returned list may not reflect recent changes to the storage domain; for example, it may not contain a new ISO file that was recently added. This is because the server caches the list of files to improve performance. To get the very latest results, set the refresh parameter to true . The default value of the refresh parameter is true , but it can be changed using the configuration value ForceRefreshDomainFilesByDefault : Important Setting the value of the refresh parameter to true has an impact on the performance of the server. Use it only if necessary. Table 6.247. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should take case into account. file File[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of files to return. refresh Boolean In Indicates whether the list of files should be refreshed from the storage domain, rather than showing cached results that are updated at certain intervals. search String In A query string used to restrict the returned files. 6.87.1.1. case_sensitive Indicates if the search performed using the search parameter should take case into account. The default value is true . 6.87.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.87.1.3. max Sets the maximum number of files to return. If not specified, all the files are returned. 6.88. Filter Table 6.248. Methods summary Name Summary get remove 6.88.1. get GET Table 6.249. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . result Filter Out 6.88.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.88.2. remove DELETE Table 6.250. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.89. Filters Manages the filters used by an scheduling policy. Table 6.251. Methods summary Name Summary add Add a filter to a specified user defined scheduling policy. list Returns the list of filters used by the scheduling policy. 6.89.1. add POST Add a filter to a specified user defined scheduling policy. Table 6.252. Parameters summary Name Type Direction Summary filter Filter In/Out 6.89.2. list GET Returns the list of filters used by the scheduling policy. The order of the returned list of filters isn't guaranteed. Table 6.253. 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 follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of filters to return. 6.89.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.89.2.2. max Sets the maximum number of filters to return. If not specified all the filters are returned. 6.90. Follow 6.91. GlusterBrick This service manages a single gluster brick. Table 6.254. Methods summary Name Summary get Get details of a brick. remove Removes a brick. replace Replaces this brick with a new one. 6.91.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: 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.255. Parameters summary Name Type Direction Summary brick GlusterBrick Out follow String In Indicates which inner links should be followed . 6.91.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.91.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: Table 6.256. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.91.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.257. Parameters summary Name Type Direction Summary async Boolean In Indicates if the replacement should be performed asynchronously. force Boolean In 6.92. GlusterBricks This service manages the gluster bricks in a gluster volume Table 6.258. 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.92.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: With a request body like this: <action> <bricks> <brick> <name>host1:/rhgs/brick1</name> </brick> </bricks> </action> Table 6.259. 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.92.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: With a request body like this: <bricks> <brick> <server_id>111</server_id> <brick_dir>/export/data/brick3</brick_dir> </brick> </bricks> Table 6.260. 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.92.3. list GET Lists the bricks of a gluster volume. For example, to list bricks of gluster volume 123 , send a request like this: 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> The order of the returned list is based on the brick order provided at gluster volume creation. Table 6.261. Parameters summary Name Type Direction Summary bricks GlusterBrick[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of bricks to return. 6.92.3.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.92.3.2. max Sets the maximum number of bricks to return. If not specified all the bricks are returned. 6.92.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: 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.262. 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.92.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: With a request body like this: <bricks> <brick> <name>host:brick_directory</name> </brick> </bricks> Table 6.263. 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.92.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: With a request body like this: <bricks> <brick> <name>host:brick_directory</name> </brick> </bricks> Table 6.264. 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.92.6.1. bricks List of bricks for which data migration needs to be stopped. This list should match the arguments passed to migrate . 6.93. GlusterHook Table 6.265. 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.93.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.266. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.93.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.267. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.93.3. get GET Table 6.268. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . hook GlusterHook Out 6.93.3.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.93.4. remove DELETE Removes the this Gluster hook from all servers in cluster and deletes it from the database. Table 6.269. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.93.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.270. 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.94. GlusterHooks Table 6.271. Methods summary Name Summary list Returns the list of hooks. 6.94.1. list GET Returns the list of hooks. The order of the returned list of hooks isn't guaranteed. Table 6.272. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . hooks GlusterHook[] Out max Integer In Sets the maximum number of hooks to return. 6.94.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.94.1.2. max Sets the maximum number of hooks to return. If not specified all the hooks are returned. 6.95. GlusterVolume This service manages a single gluster volume. Table 6.273. 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.95.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: 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.274. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . volume GlusterVolume Out Representation of the gluster volume. 6.95.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.95.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: Table 6.275. Parameters summary Name Type Direction Summary details GlusterVolumeProfileDetails Out Gluster volume profiling information returned from the action. 6.95.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: Table 6.276. 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.95.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.95.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.95.4. remove DELETE Removes the gluster volume. For example, to remove a volume with identifier 123 in cluster 456 , send a request like this: Table 6.277. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.95.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: Table 6.278. Parameters summary Name Type Direction Summary async Boolean In Indicates if the reset should be performed asynchronously. 6.95.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: With the following request body: <action> <option name="option1"/> </action> Table 6.279. 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.95.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: With the following request body: <action> <option name="option1" value="value1"/> </action> Table 6.280. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. option Option In Option to set. 6.95.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: Table 6.281. 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.95.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.95.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: Table 6.282. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.95.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: Table 6.283. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. force Boolean In 6.95.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: Table 6.284. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.95.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: Table 6.285. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.96. GlusterVolumes This service manages a collection of gluster volumes available in a cluster. Table 6.286. Methods summary Name Summary add Creates a new gluster volume. list Lists all gluster volumes in the cluster. 6.96.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: 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.287. 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.96.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: The order of the returned list of volumes isn't guaranteed. Table 6.288. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of volumes to return. search String In A query string used to restrict the returned volumes. volumes GlusterVolume[] Out 6.96.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.96.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.96.2.3. max Sets the maximum number of volumes to return. If not specified all the volumes are returned. 6.97. Group Manages a group of users. Use this service to either get groups details or remove groups. In order to add new groups please use service that manages the collection of groups. Table 6.289. Methods summary Name Summary get Gets the system group information. remove Removes the system group. 6.97.1. get GET Gets the system group information. Usage: Will return the group information: <group href="/ovirt-engine/api/groups/123" id="123"> <name>mygroup</name> <link href="/ovirt-engine/api/groups/123/roles" rel="roles"/> <link href="/ovirt-engine/api/groups/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/groups/123/tags" rel="tags"/> <domain_entry_id>476652557A382F67696B6D2B32762B37796E46476D513D3D</domain_entry_id> <namespace>DC=example,DC=com</namespace> <domain href="/ovirt-engine/api/domains/ABCDEF" id="ABCDEF"> <name>myextension-authz</name> </domain> </group> Table 6.290. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . get Group Out The system group. 6.97.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.97.2. remove DELETE Removes the system group. Usage: Table 6.291. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.98. Groups Manages the collection of groups of users. Table 6.292. Methods summary Name Summary add Add group from a directory service. list List all the groups in the system. 6.98.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: With a request body like this: <group> <name>Developers</name> <domain> <name>internal-authz</name> </domain> </group> Table 6.293. Parameters summary Name Type Direction Summary group Group In/Out The group to be added. 6.98.2. list GET List all the groups in the system. Usage: Will return the list of groups: <groups> <group href="/ovirt-engine/api/groups/123" id="123"> <name>mygroup</name> <link href="/ovirt-engine/api/groups/123/roles" rel="roles"/> <link href="/ovirt-engine/api/groups/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/groups/123/tags" rel="tags"/> <domain_entry_id>476652557A382F67696B6D2B32762B37796E46476D513D3D</domain_entry_id> <namespace>DC=example,DC=com</namespace> <domain href="/ovirt-engine/api/domains/ABCDEF" id="ABCDEF"> <name>myextension-authz</name> </domain> </group> ... </groups> The order of the returned list of groups isn't guaranteed. Table 6.294. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. follow String In Indicates which inner links should be followed . groups Group[] Out The list of groups. max Integer In Sets the maximum number of groups to return. search String In A query string used to restrict the returned groups. 6.98.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.98.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.98.2.3. max Sets the maximum number of groups to return. If not specified all the groups are returned. 6.99. Host A service to manage a host. Table 6.295. Methods summary Name Summary activate Activates the host for use, for example to run 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 Deactivates the host to perform maintenance tasks. enrollcertificate Enrolls the certificate of the host. fence Controls the host's power management device. forceselectspm To manually set a host as the storage pool manager (SPM). get Gets the host details. install Installs the latest version of VDSM and related software on the host. iscsidiscover Discovers 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. syncallnetworks To synchronize all networks on the host, send a request like this: [source] ---- POST /ovirt-engine/api/hosts/123/syncallnetworks ---- With a request body like this: [source,xml] ---- <action/> ---- unregisteredstoragedomainsdiscover Discovers the block Storage Domains which are candidates to be imported to the setup. update Update the host properties. upgrade Upgrades VDSM and selected software on the host. upgradecheck Check if there are upgrades available for the host. 6.99.1. activate POST Activates the host for use, for example to run virtual machines. Table 6.296. Parameters summary Name Type Direction Summary async Boolean In Indicates if the activation should be performed asynchronously. 6.99.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.297. Parameters summary Name Type Direction Summary async Boolean In Indicates if the approval should be performed asynchronously. cluster Cluster In The cluster where the host will be added after it is approved. host Host In The host to approve. 6.99.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 networking configuration. For example, to commit the network configuration of host with id 123 send a request like this: With a request body like this: <action/> Table 6.298. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.99.4. deactivate POST Deactivates the host to perform maintenance tasks. Table 6.299. 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.99.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.99.5. enrollcertificate POST Enrolls the certificate of the host. Useful in case you get a warning that it is about to expire or has already expired. Table 6.300. Parameters summary Name Type Direction Summary async Boolean In Indicates if the enrollment should be performed asynchronously. 6.99.6. fence POST Controls the host's power management device. For example, to start the host. This can be done via: Table 6.301. 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.99.7. forceselectspm POST To manually set a host as the storage pool manager (SPM). With a request body like this: <action/> Table 6.302. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.99.8. get GET Gets the host details. Table 6.303. Parameters summary Name Type Direction Summary all_content Boolean In Indicates if all of the attributes of the host should be included in the response. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . host Host Out The queried host. 6.99.8.1. all_content Indicates if all of the attributes of the host should be included in the response. By default the following attributes are excluded: hosted_engine For example, to retrieve the complete representation of host '123': Note These attributes are not included by default because retrieving them impacts performance. They are seldom used and require additional queries to the database. Use this parameter with caution and only when specifically required. 6.99.8.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.99.9. install POST Installs the latest version of VDSM and related software on the host. The action also performs every configuration steps on the host which is done during adding host to the engine: kdump configuration, hosted-engine deploy, kernel options changes, etc. 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.304. 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 also deploy the self-hosted engine components. host Host In The override_iptables property is used to indicate if the firewall configuration should be replaced by the default one. image String In When installing Red Hat Virtualization Host, an ISO image file is required. 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 the self-hosted engine components and this host will not function as part of the High Availability cluster. 6.99.9.1. deploy_hosted_engine When set to true it means this host should also deploy the self-hosted engine components. A missing value is treated as true i.e deploy. Omitting this parameter means false and will perform no operation in the self-hosted engine area. 6.99.9.2. undeploy_hosted_engine When set to true it means this host should un-deploy the self-hosted engine components and this host will not function as part of the High Availability cluster. A missing value is treated as true i.e un-deploy Omitting this parameter means false and will perform no operation in the self-hosted engine area. 6.99.10. iscsidiscover POST Discovers iSCSI targets on the host, using the initiator details. For example, to discover iSCSI targets available in myiscsi.example.com , from host 123 , send a request like this: With a request body like this: <action> <iscsi> <address>myiscsi.example.com</address> </iscsi> </action> The result will be like this: <discovered_targets> <iscsi_details> <address>10.35.1.72</address> <port>3260</port> <portal>10.35.1.72:3260,1</portal> <target>iqn.2015-08.com.tgt:444</target> </iscsi_details> </discovered_targets> Table 6.305. Parameters summary Name Type Direction Summary async Boolean In Indicates if the discovery should be performed asynchronously. discovered_targets IscsiDetails[] Out The discovered targets including all connection information. iscsi IscsiDetails In The target iSCSI device. iscsi_targets String[] Out The iSCSI targets. 6.99.10.1. iscsi_targets The iSCSI targets. Since version 4.2 of the engine, this parameter is deprecated, use discovered_targets instead. 6.99.11. iscsilogin POST Login to iSCSI targets on the host, using the target details. Table 6.306. 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.99.12. refresh POST Refresh the host devices and capabilities. Table 6.307. Parameters summary Name Type Direction Summary async Boolean In Indicates if the refresh should be performed asynchronously. 6.99.13. remove DELETE Remove the host from the system. Table 6.308. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.99.14. setupnetworks POST This method is used to change the configuration of the network interfaces of a host. For example, if you have a host with three network interfaces eth0 , eth1 and eth2 and 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: Note This is valid for version 4 of the API. In 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.309. 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 A list of network attachments that will be synchronized. 6.99.15. syncallnetworks POST To synchronize all networks on the host, send a request like this: With a request body like this: <action/> Table 6.310. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.99.16. unregisteredstoragedomainsdiscover POST Discovers the block Storage Domains which are candidates to be imported to the setup. For FCP no arguments are required. Table 6.311. 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.99.17. update PUT Update the host properties. For example, to update a the kernel command line of a host send a request like this: With request body like this: <host> <os> <custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline> </os> </host> Table 6.312. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. host Host In/Out 6.99.18. upgrade POST Upgrades VDSM and selected software on the host. Table 6.313. Parameters summary Name Type Direction Summary async Boolean In Indicates if the upgrade should be performed asynchronously. image String In The image parameter specifies path to image, which is used for upgrade. reboot Boolean In Indicates if the host should be rebooted after upgrade. 6.99.18.1. image The image parameter specifies path to image, which is used for upgrade. This parameter is used only to upgrade Vintage Node hosts and it is not relevant for other hosts types. 6.99.18.2. reboot Indicates if the host should be rebooted after upgrade. By default the host is rebooted. Note This parameter is ignored for Red Hat Virtualization Host, which is always rebooted after upgrade. 6.99.19. upgradecheck POST Check if there are upgrades available for the host. If there are upgrades available an icon will be displayed to host status icon in the Administration Portal. 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.100. HostDevice A service to access a particular device of a host. Table 6.314. Methods summary Name Summary get Retrieve information about a particular host's device. 6.100.1. get GET Retrieve information about a particular host's device. An example of getting a host device: <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.315. Parameters summary Name Type Direction Summary device HostDevice Out follow String In Indicates which inner links should be followed . 6.100.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.101. HostDevices A service to access host devices. Table 6.316. Methods summary Name Summary list List the devices of a host. 6.101.1. list GET List the devices of a host. The order of the returned list of devices isn't guaranteed. Table 6.317. Parameters summary Name Type Direction Summary devices HostDevice[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of devices to return. 6.101.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.101.1.2. max Sets the maximum number of devices to return. If not specified all the devices are returned. 6.102. HostHook Table 6.318. Methods summary Name Summary get 6.102.1. get GET Table 6.319. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . hook Hook Out 6.102.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.103. HostHooks Table 6.320. Methods summary Name Summary list Returns the list of hooks configured for the host. 6.103.1. list GET Returns the list of hooks configured for the host. The order of the returned list of hooks isn't guranteed. Table 6.321. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . hooks Hook[] Out max Integer In Sets the maximum number of hooks to return. 6.103.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.103.1.2. max Sets the maximum number of hooks to return. If not specified all the hooks are returned. 6.104. HostNic A service to manage a network interface of a host. Table 6.322. Methods summary Name Summary get updatevirtualfunctionsconfiguration The action updates virtual function configuration in case the current resource represents an SR-IOV enabled NIC. 6.104.1. get GET Table 6.323. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . nic HostNic Out 6.104.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.104.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.324. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. virtual_functions_configuration HostNicVirtualFunctionsConfiguration In 6.105. HostNics A service to manage the network interfaces of a host. Table 6.325. Methods summary Name Summary list Returns the list of network interfaces of the host. 6.105.1. list GET Returns the list of network interfaces of the host. The order of the returned list of network interfaces isn't guaranteed. Table 6.326. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of NICs to return. nics HostNic[] Out 6.105.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.105.1.2. max Sets the maximum number of NICs to return. If not specified all the NICs are returned. 6.106. HostNumaNode Table 6.327. Methods summary Name Summary get 6.106.1. get GET Table 6.328. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . node NumaNode Out 6.106.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.107. HostNumaNodes Table 6.329. Methods summary Name Summary list Returns the list of NUMA nodes of the host. 6.107.1. list GET Returns the list of NUMA nodes of the host. The order of the returned list of NUMA nodes isn't guaranteed. Table 6.330. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of nodes to return. nodes NumaNode[] Out 6.107.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.107.1.2. max Sets the maximum number of nodes to return. If not specified all the nodes are returned. 6.108. HostStorage A service to manage host storages. Table 6.331. Methods summary Name Summary list Get list of storages. 6.108.1. list GET Get list of storages. The XML response you get will be like this one: <host_storages> <host_storage id="123"> ... </host_storage> ... </host_storages> The order of the returned list of storages isn't guaranteed. Table 6.332. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . 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.108.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.108.1.2. 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.109. Hosts A service that manages hosts. Table 6.333. Methods summary Name Summary add Creates a new host. list Get a list of all available hosts. 6.109.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: 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: If the cluster has a default external network provider which is supported for automatic deployment, the external network provider is deployed when adding the host. Only external network providers for OVN are supported for the automatic deployment. To deploy an external network provider that differs to what is defined in the clusters, overwrite the external network provider when adding hosts by sending a request like this: With a request body that contains a reference to the desired provider in the external_network_provider_configuration : <host> <name>myhost</name> <address>myhost.example.com</address> <root_password>123456</root_password> <external_network_provider_configurations> <external_network_provider_configuration> <external_network_provider name="ovirt-provider-ovn"/> </external_network_provider_configuration> </external_network_provider_configurations> </host> Table 6.334. 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.109.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.109.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.109.2. list GET Get a list of all available hosts. For example, to list the hosts send the following request: 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> The order of the returned list of hosts is guaranteed only if the sortby clause is included in the search parameter. Table 6.335. Parameters summary Name Type Direction Summary all_content Boolean In Indicates if all of the attributes of the hosts should be included in the response. case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . 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.109.2.1. all_content Indicates if all of the attributes of the hosts should be included in the response. By default the following host attributes are excluded: hosted_engine For example, to retrieve the complete representation of the hosts: Note These attributes are not included by default because retrieving them impacts performance. They are seldom used and require additional queries to the database. Use this parameter with caution and only when specifically required. 6.109.2.2. 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.109.2.3. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.109.2.4. max Sets the maximum number of hosts to return. If not specified all the hosts are returned. 6.110. Icon A service to manage an icon (read-only). Table 6.336. Methods summary Name Summary get Get an icon. 6.110.1. get GET Get an icon. 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.337. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . icon Icon Out Retrieved icon. 6.110.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.111. Icons A service to manage icons. Table 6.338. Methods summary Name Summary list Get a list of icons. 6.111.1. list GET Get a list of 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> The order of the returned list of icons isn't guaranteed. Table 6.339. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . icons Icon[] Out Retrieved list of icons. max Integer In Sets the maximum number of icons to return. 6.111.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.111.1.2. max Sets the maximum number of icons to return. If not specified all the icons are returned. 6.112. Image Table 6.340. Methods summary Name Summary get import Imports an image. 6.112.1. get GET Table 6.341. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . image Image Out 6.112.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.112.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.342. 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.113. 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.114, "ImageTransfers" service, stating the image to transfer data to/from. After doing that, the transfer is managed by this service. Using oVirt's Python's SDK: Uploading a disk with id 123 (on a random host in the data center): transfers_service = system_service.image_transfers_service() transfer = transfers_service.add( types.ImageTransfer( disk=types.Disk( id='123' ) ) ) Uploading a disk with id 123 on host id 456 : transfers_service = system_service.image_transfers_service() transfer = transfers_service.add( types.ImageTransfer( disk=types.Disk( id='123' ), host=types.Host( id='456' ) ) ) 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( disk=types.Disk( id='123' ), 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. Using HTTP and cURL calls: For upload, create a new disk first: Specify 'initial_size' and 'provisioned_size' in bytes. 'initial_size' must be bigger or the same as the size of the uploaded data. With a request body as follows: <disk> <storage_domains> <storage_domain id="123"/> </storage_domains> <alias>mydisk</alias> <initial_size>1073741824</initial_size> <provisioned_size>1073741824</provisioned_size> <format>raw</format> </disk> Create a new image transfer for downloading/uploading a disk with id 456 : With a request body as follows: <image_transfer> <disk id="456"/> <direction>upload|download</direction> </image_transfer> Will respond: <image_transfer id="123"> <direction>download|upload</direction> <phase>initializing|transferring</phase> <proxy_url>https://proxy_fqdn:54323/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb</proxy_url> <transfer_url>https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb</transfer_url> ... </image_transfer> Note: If the phase is 'initializing', poll the image_transfer till its phase changes to 'transferring'. Use the 'transfer_url' or 'proxy_url' to invoke a curl command: use 'transfer_url' for transferring directly from/to ovirt-imageio-daemon, or, use 'proxy_url' for transferring from/to ovirt-imageio-proxy. Note: using the proxy would mitigate scenarios where there's no direct connectivity to the daemon machine, e.g. vdsm machines are on a different network than the engine. - Download: USD curl --cacert /etc/pki/ovirt-engine/ca.pem https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb -o <output_file> - Upload: USD curl --cacert /etc/pki/ovirt-engine/ca.pem --upload-file <file_to_upload> -X PUT https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb Finalize the image transfer by invoking the action: With a request body as follows: <action /> Table 6.343. Methods summary Name Summary cancel Cancel the image transfer session. 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.113.1. cancel POST Cancel the image transfer session. This terminates the transfer operation and removes the partial image. 6.113.2. extend POST Extend the image transfer session. 6.113.3. 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.113.4. get GET Get the image transfer entity. Table 6.344. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . image_transfer ImageTransfer Out 6.113.4.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.113.5. pause POST Pause the image transfer session. 6.113.6. 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.114. ImageTransfers This service manages image transfers, for performing Image I/O API in Red Hat Virtualization. Please refer to image transfer for further documentation. Table 6.345. Methods summary Name Summary add Add a new image transfer. list Retrieves the list of image transfers that are currently being performed. 6.114.1. add POST Add a new image transfer. An image, disk or disk snapshot needs to be specified in order to make a new transfer. Important The image attribute is deprecated since version 4.2 of the engine. Use the disk or snapshot attributes instead. Creating a new image transfer for downloading or uploading a disk : To create an image transfer to download or upload a disk with id 123 , send the following request: With a request body like this: <image_transfer> <disk id="123"/> <direction>upload|download</direction> </image_transfer> Creating a new image transfer for downloading or uploading a disk_snapshot : To create an image transfer to download or upload a disk_snapshot with id 456 , send the following request: With a request body like this: <image_transfer> <snapshot id="456"/> <direction>download|upload</direction> </image_transfer> Table 6.346. Parameters summary Name Type Direction Summary image_transfer ImageTransfer In/Out The image transfer to add. 6.114.2. list GET Retrieves the list of image transfers that are currently being performed. The order of the returned list of image transfers is not guaranteed. Table 6.347. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . image_transfer ImageTransfer[] Out A list of image transfers that are currently being performed. 6.114.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.115. Images Manages the set of images available in an storage domain or in an OpenStack image provider. Table 6.348. Methods summary Name Summary list Returns the list of images available in the storage domain or provider. 6.115.1. list GET Returns the list of images available in the storage domain or provider. The order of the returned list of images isn't guaranteed. Table 6.349. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . images Image[] Out max Integer In Sets the maximum number of images to return. 6.115.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.115.1.2. max Sets the maximum number of images to return. If not specified all the images are returned. 6.116. InstanceType Table 6.350. 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.116.1. get GET Get a specific instance type and it's attributes. Table 6.351. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . instance_type InstanceType Out 6.116.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.116.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 . Table 6.352. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.116.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. 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.353. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. instance_type InstanceType In/Out 6.117. InstanceTypeGraphicsConsole Table 6.354. Methods summary Name Summary get Gets graphics console configuration of the instance type. remove Remove the graphics console from the instance type. 6.117.1. get GET Gets graphics console configuration of the instance type. Table 6.355. Parameters summary Name Type Direction Summary console GraphicsConsole Out The information about the graphics console of the instance type. follow String In Indicates which inner links should be followed . 6.117.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.117.2. remove DELETE Remove the graphics console from the instance type. Table 6.356. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.118. InstanceTypeGraphicsConsoles Table 6.357. 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.118.1. add POST Add new graphics console to the instance type. Table 6.358. Parameters summary Name Type Direction Summary console GraphicsConsole In/Out 6.118.2. list GET Lists all the configured graphics consoles of the instance type. The order of the returned list of graphics consoles isn't guaranteed. Table 6.359. Parameters summary Name Type Direction Summary consoles GraphicsConsole[] Out The list of graphics consoles of the instance type. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of consoles to return. 6.118.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.118.2.2. max Sets the maximum number of consoles to return. If not specified all the consoles are returned. 6.119. InstanceTypeNic Table 6.360. 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.119.1. get GET Gets network interface configuration of the instance type. Table 6.361. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . nic Nic Out 6.119.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.119.2. remove DELETE Remove the network interface from the instance type. Table 6.362. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.119.3. update PUT Updates the network interface configuration of the instance type. Table 6.363. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. nic Nic In/Out 6.120. InstanceTypeNics Table 6.364. 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.120.1. add POST Add new network interface to the instance type. Table 6.365. Parameters summary Name Type Direction Summary nic Nic In/Out 6.120.2. list GET Lists all the configured network interface of the instance type. The order of the returned list of network interfaces isn't guaranteed. Table 6.366. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . 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.120.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.120.2.2. max Sets the maximum number of NICs to return. If not specified all the NICs are returned. 6.121. InstanceTypeWatchdog Table 6.367. Methods summary Name Summary get Gets watchdog configuration of the instance type. remove Remove a watchdog from the instance type. update Updates the watchdog configuration of the instance type. 6.121.1. get GET Gets watchdog configuration of the instance type. Table 6.368. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . watchdog Watchdog Out 6.121.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.121.2. remove DELETE Remove a watchdog from the instance type. Table 6.369. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.121.3. update PUT Updates the watchdog configuration of the instance type. Table 6.370. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. watchdog Watchdog In/Out 6.122. InstanceTypeWatchdogs Table 6.371. Methods summary Name Summary add Add new watchdog to the instance type. list Lists all the configured watchdogs of the instance type. 6.122.1. add POST Add new watchdog to the instance type. Table 6.372. Parameters summary Name Type Direction Summary watchdog Watchdog In/Out 6.122.2. list GET Lists all the configured watchdogs of the instance type. The order of the returned list of watchdogs isn't guaranteed. Table 6.373. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of watchdogs to return. search String In A query string used to restrict the returned templates. watchdogs Watchdog[] Out 6.122.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.122.2.2. max Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned. 6.123. InstanceTypes Table 6.374. Methods summary Name Summary add Creates a new instance type. list Lists all existing instance types in the system. 6.123.1. add POST Creates a new instance type. This requires only a name attribute and can include all hardware configurations of the virtual machine. With a request body like this: <instance_type> <name>myinstancetype</name> </template> Creating an instance type with all hardware configurations with a request body like this: <instance_type> <name>myinstancetype</name> <console> <enabled>true</enabled> </console> <cpu> <topology> <cores>2</cores> <sockets>2</sockets> <threads>1</threads> </topology> </cpu> <custom_cpu_model>AMD Opteron_G2</custom_cpu_model> <custom_emulated_machine>q35</custom_emulated_machine> <display> <monitors>1</monitors> <single_qxl_pci>true</single_qxl_pci> <smartcard_enabled>true</smartcard_enabled> <type>spice</type> </display> <high_availability> <enabled>true</enabled> <priority>1</priority> </high_availability> <io> <threads>2</threads> </io> <memory>4294967296</memory> <memory_policy> <ballooning>true</ballooning> <guaranteed>268435456</guaranteed> </memory_policy> <migration> <auto_converge>inherit</auto_converge> <compressed>inherit</compressed> <policy id="00000000-0000-0000-0000-000000000000"/> </migration> <migration_downtime>2</migration_downtime> <os> <boot> <devices> <device>hd</device> </devices> </boot> </os> <rng_device> <rate> <bytes>200</bytes> <period>2</period> </rate> <source>urandom</source> </rng_device> <soundcard_enabled>true</soundcard_enabled> <usb> <enabled>true</enabled> <type>native</type> </usb> <virtio_scsi> <enabled>true</enabled> </virtio_scsi> </instance_type> Table 6.375. Parameters summary Name Type Direction Summary instance_type InstanceType In/Out 6.123.2. list GET Lists all existing instance types in the system. The order of the returned list of instance types isn't guaranteed. Table 6.376. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. follow String In Indicates which inner links should be followed . instance_type InstanceType[] Out max Integer In Sets the maximum number of instance types to return. search String In A query string used to restrict the returned templates. 6.123.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.123.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.123.2.3. max Sets the maximum number of instance types to return. If not specified all the instance types are returned. 6.124. IscsiBond Table 6.377. Methods summary Name Summary get remove Removes of an existing iSCSI bond. update Updates an iSCSI bond. 6.124.1. get GET Table 6.378. Parameters summary Name Type Direction Summary bond IscsiBond Out The iSCSI bond. follow String In Indicates which inner links should be followed . 6.124.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.124.2. remove DELETE Removes of an existing iSCSI bond. For example, to remove the iSCSI bond 456 send a request like this: Table 6.379. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.124.3. update PUT Updates an iSCSI bond. Updating of an iSCSI bond can be done on the name and the description attributes only. For example, to update the iSCSI bond 456 of data center 123 , send a request like this: The request body should look like this: <iscsi_bond> <name>mybond</name> <description>My iSCSI bond</description> </iscsi_bond> Table 6.380. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. bond IscsiBond In/Out The iSCSI bond to update. 6.125. IscsiBonds Table 6.381. Methods summary Name Summary add Create a new iSCSI bond on a data center. list Returns the list of iSCSI bonds configured in the data center. 6.125.1. add POST Create a new iSCSI bond on a data center. For example, to create a new iSCSI bond on data center 123 using storage connections 456 and 789 , send a request like this: The request body should look like this: <iscsi_bond> <name>mybond</name> <storage_connections> <storage_connection id="456"/> <storage_connection id="789"/> </storage_connections> <networks> <network id="abc"/> </networks> </iscsi_bond> Table 6.382. Parameters summary Name Type Direction Summary bond IscsiBond In/Out 6.125.2. list GET Returns the list of iSCSI bonds configured in the data center. The order of the returned list of iSCSI bonds isn't guaranteed. Table 6.383. Parameters summary Name Type Direction Summary bonds IscsiBond[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of bonds to return. 6.125.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.125.2.2. max Sets the maximum number of bonds to return. If not specified all the bonds are returned. 6.126. Job A service to manage a job. Table 6.384. Methods summary Name Summary clear Set an external job execution to be cleared by the system. end Marks an external job execution as ended. get Retrieves a job. 6.126.1. clear POST Set an external job execution to be cleared by the system. For example, to set a job with identifier 123 send the following request: With the following request body: <action/> Table 6.385. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.126.2. end POST Marks an external job execution as ended. For example, to terminate a job with identifier 123 send the following request: With the following request body: <action> <force>true</force> <status>finished</status> </action> Table 6.386. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. force Boolean In Indicates if the job should be forcibly terminated. succeeded Boolean In Indicates if the job should be marked as successfully finished or as failed. 6.126.2.1. succeeded Indicates if the job should be marked as successfully finished or as failed. This parameter is optional, and the default value is true . 6.126.3. get GET Retrieves a job. You will receive response in XML like this one: <job href="/ovirt-engine/api/jobs/123" id="123"> <actions> <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/> <link href="/ovirt-engine/api/jobs/123/end" rel="end"/> </actions> <description>Adding Disk</description> <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/> <auto_cleared>true</auto_cleared> <end_time>2016-12-12T23:07:29.758+02:00</end_time> <external>false</external> <last_updated>2016-12-12T23:07:29.758+02:00</last_updated> <start_time>2016-12-12T23:07:26.593+02:00</start_time> <status>failed</status> <owner href="/ovirt-engine/api/users/456" id="456"/> </job> Table 6.387. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . job Job Out Retrieves the representation of the job. 6.126.3.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.127. Jobs A service to manage jobs. Table 6.388. Methods summary Name Summary add Add an external job. list Retrieves the representation of the jobs. 6.127.1. add POST Add an external job. For example, to add a job with the following request: With the following request body: <job> <description>Doing some work</description> <auto_cleared>true</auto_cleared> </job> The response should look like: <job href="/ovirt-engine/api/jobs/123" id="123"> <actions> <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/> <link href="/ovirt-engine/api/jobs/123/end" rel="end"/> </actions> <description>Doing some work</description> <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/> <auto_cleared>true</auto_cleared> <external>true</external> <last_updated>2016-12-13T02:15:42.130+02:00</last_updated> <start_time>2016-12-13T02:15:42.130+02:00</start_time> <status>started</status> <owner href="/ovirt-engine/api/users/456" id="456"/> </job> Table 6.389. Parameters summary Name Type Direction Summary job Job In/Out Job that will be added. 6.127.2. list GET Retrieves the representation of the jobs. You will receive response in XML like this one: <jobs> <job href="/ovirt-engine/api/jobs/123" id="123"> <actions> <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/> <link href="/ovirt-engine/api/jobs/123/end" rel="end"/> </actions> <description>Adding Disk</description> <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/> <auto_cleared>true</auto_cleared> <end_time>2016-12-12T23:07:29.758+02:00</end_time> <external>false</external> <last_updated>2016-12-12T23:07:29.758+02:00</last_updated> <start_time>2016-12-12T23:07:26.593+02:00</start_time> <status>failed</status> <owner href="/ovirt-engine/api/users/456" id="456"/> </job> ... </jobs> The order of the returned list of jobs isn't guaranteed. Table 6.390. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. follow String In Indicates which inner links should be followed . jobs Job[] Out A representation of jobs. max Integer In Sets the maximum number of jobs to return. search String In A query string used to restrict the returned jobs. 6.127.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.127.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.127.2.3. max Sets the maximum number of jobs to return. If not specified all the jobs are returned. 6.128. KatelloErrata A service to manage Katello errata. The information is retrieved from Katello. Table 6.391. Methods summary Name Summary list Retrieves the representation of the Katello errata. 6.128.1. list GET Retrieves the representation of the Katello errata. You will receive response in XML like this one: <katello_errata> <katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123"> <name>RHBA-2013:XYZ</name> <description>The description of the erratum</description> <title>some bug fix update</title> <type>bugfix</type> <issued>2013-11-20T02:00:00.000+02:00</issued> <solution>Few guidelines regarding the solution</solution> <summary>Updated packages that fix one bug are now available for XYZ</summary> <packages> <package> <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name> </package> ... </packages> </katello_erratum> ... </katello_errata> The order of the returned list of erratum isn't guaranteed. Table 6.392. Parameters summary Name Type Direction Summary errata KatelloErratum[] Out A representation of Katello errata. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of errata to return. 6.128.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.128.1.2. max Sets the maximum number of errata to return. If not specified all the errata are returned. 6.129. KatelloErratum A service to manage a Katello erratum. Table 6.393. Methods summary Name Summary get Retrieves a Katello erratum. 6.129.1. get GET Retrieves a Katello erratum. You will receive response in XML like this one: <katello_erratum href="/ovirt-engine/api/katelloerrata/123" id="123"> <name>RHBA-2013:XYZ</name> <description>The description of the erratum</description> <title>some bug fix update</title> <type>bugfix</type> <issued>2013-11-20T02:00:00.000+02:00</issued> <solution>Few guidelines regarding the solution</solution> <summary>Updated packages that fix one bug are now available for XYZ</summary> <packages> <package> <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name> </package> ... </packages> </katello_erratum> Table 6.394. Parameters summary Name Type Direction Summary erratum KatelloErratum Out Retrieves the representation of the Katello erratum. follow String In Indicates which inner links should be followed . 6.129.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.130. LinkLayerDiscoveryProtocol A service to fetch information elements received by Link Layer Discovery Protocol (LLDP). Table 6.395. Methods summary Name Summary list Fetches information elements received by LLDP. 6.130.1. list GET Fetches information elements received by LLDP. Table 6.396. Parameters summary Name Type Direction Summary elements LinkLayerDiscoveryProtocolElement[] Out Retrieves a list of information elements received by LLDP. follow String In Indicates which inner links should be followed . 6.130.1.1. elements Retrieves a list of information elements received by LLDP. For example, to retrieve the information elements received on the NIC 321 on host 123 , send a request like this: It will return a response like this: <link_layer_discovery_protocol_elements> ... <link_layer_discovery_protocol_element> <name>Port Description</name> <properties> <property> <name>port description</name> <value>Summit300-48-Port 1001</value> </property> </properties> <type>4</type> </link_layer_discovery_protocol_element> ... <link_layer_discovery_protocol_elements> 6.130.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.131. MacPool Table 6.397. Methods summary Name Summary get remove Removes a MAC address pool. update Updates a MAC address pool. 6.131.1. get GET Table 6.398. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . pool MacPool Out 6.131.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.131.2. remove DELETE Removes a MAC address pool. For example, to remove the MAC address pool having id 123 send a request like this: Table 6.399. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.131.3. update PUT Updates a MAC address pool. The name , description , allow_duplicates , and ranges attributes can be updated. For example, to update the MAC address pool of id 123 send a request like this: With a request body like this: <mac_pool> <name>UpdatedMACPool</name> <description>An updated MAC address pool</description> <allow_duplicates>false</allow_duplicates> <ranges> <range> <from>00:1A:4A:16:01:51</from> <to>00:1A:4A:16:01:e6</to> </range> <range> <from>02:1A:4A:01:00:00</from> <to>02:1A:4A:FF:FF:FF</to> </range> </ranges> </mac_pool> Table 6.400. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. pool MacPool In/Out 6.132. MacPools Table 6.401. Methods summary Name Summary add Creates a new MAC address pool. list Return the list of MAC address pools of the system. 6.132.1. add POST Creates a new MAC address pool. Creation of a MAC address pool requires values for the name and ranges attributes. For example, to create MAC address pool send a request like this: With a request body like this: <mac_pool> <name>MACPool</name> <description>A MAC address pool</description> <allow_duplicates>true</allow_duplicates> <default_pool>false</default_pool> <ranges> <range> <from>00:1A:4A:16:01:51</from> <to>00:1A:4A:16:01:e6</to> </range> </ranges> </mac_pool> Table 6.402. Parameters summary Name Type Direction Summary pool MacPool In/Out 6.132.2. list GET Return the list of MAC address pools of the system. The returned list of MAC address pools isn't guaranteed. Table 6.403. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of pools to return. pools MacPool[] Out 6.132.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.132.2.2. max Sets the maximum number of pools to return. If not specified all the pools are returned. 6.133. Measurable 6.134. Moveable Table 6.404. Methods summary Name Summary move 6.134.1. move POST Table 6.405. Parameters summary Name Type Direction Summary async Boolean In Indicates if the move should be performed asynchronously. 6.135. Network A service managing a network Table 6.406. Methods summary Name Summary get Gets a logical network. remove Removes a logical network, or the association of a logical network to a data center. update Updates a logical network. 6.135.1. get GET Gets a logical network. For example: Will respond: <network href="/ovirt-engine/api/networks/123" id="123"> <name>ovirtmgmt</name> <description>Default Management Network</description> <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/> <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/> <mtu>0</mtu> <stp>false</stp> <usages> <usage>vm</usage> </usages> <data_center href="/ovirt-engine/api/datacenters/456" id="456"/> </network> Table 6.407. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . network Network Out 6.135.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.135.2. remove DELETE Removes a logical network, or the association of a logical network to a data center. For example, to remove the logical network 123 send a request like this: Each network is bound exactly to one data center. So if we disassociate network with data center it has the same result as if we would just remove that network. However it might be more specific to say we're removing network 456 of data center 123 . For example, to remove the association of network 456 to data center 123 send a request like this: Note To remove an external logical network, the network has to be removed directly from its provider by OpenStack Networking API . The entity representing the external network inside Red Hat Virtualization is removed automatically, if auto_sync is enabled for the provider, otherwise the entity has to be removed using this method. Table 6.408. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.135.3. update PUT Updates a logical network. The name , description , ip , vlan , stp and display attributes can be updated. For example, to update the description of the logical network 123 send a request like this: With a request body like this: <network> <description>My updated description</description> </network> The maximum transmission unit of a network is set using a PUT request to specify the integer value of the mtu attribute. For example, to set the maximum transmission unit send a request like this: With a request body like this: <network> <mtu>1500</mtu> </network> Table 6.409. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. network Network In/Out 6.136. NetworkAttachment Table 6.410. Methods summary Name Summary get remove update Update the specified network attachment on the host. 6.136.1. get GET Table 6.411. Parameters summary Name Type Direction Summary attachment NetworkAttachment Out follow String In Indicates which inner links should be followed . 6.136.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.136.2. remove DELETE Table 6.412. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.136.3. update PUT Update the specified network attachment on the host. Table 6.413. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. attachment NetworkAttachment In/Out 6.137. NetworkAttachments Manages the set of network attachments of a host or host NIC. Table 6.414. Methods summary Name Summary add Add a new network attachment to the network interface. list Returns the list of network attachments of the host or host NIC. 6.137.1. add POST Add a new network attachment to the network interface. Table 6.415. Parameters summary Name Type Direction Summary attachment NetworkAttachment In/Out 6.137.2. list GET Returns the list of network attachments of the host or host NIC. The order of the returned list of network attachments isn't guaranteed. Table 6.416. Parameters summary Name Type Direction Summary attachments NetworkAttachment[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of attachments to return. 6.137.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.137.2.2. max Sets the maximum number of attachments to return. If not specified all the attachments are returned. 6.138. NetworkFilter Manages a network filter. <network_filter id="00000019-0019-0019-0019-00000000026b"> <name>example-network-filter-b</name> <version> <major>4</major> <minor>0</minor> <build>-1</build> <revision>-1</revision> </version> </network_filter> Please note that version is referring to the minimal support version for the specific filter. Table 6.417. Methods summary Name Summary get Retrieves a representation of the network filter. 6.138.1. get GET Retrieves a representation of the network filter. Table 6.418. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . network_filter NetworkFilter Out 6.138.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.139. NetworkFilters Represents a readonly network filters sub-collection. The network filter enables to filter packets send to/from the VM's nic according to defined rules. For more information please refer to NetworkFilter service documentation Network filters are supported in different versions, starting from version 3.0. A network filter is defined for each vnic profile. A vnic profile is defined for a specific network. A network can be assigned to several different clusters. In the future, each network will be defined in cluster level. Currently, each network is being defined at data center level. Potential network filters for each network are determined by the network's data center compatibility version V. V must be >= the network filter version in order to configure this network filter for a specific network. Please note, that if a network is assigned to cluster with a version supporting a network filter, the filter may not be available due to the data center version being smaller then the network filter's version. Example of listing all of the supported network filters for a specific cluster: Output: <network_filters> <network_filter id="00000019-0019-0019-0019-00000000026c"> <name>example-network-filter-a</name> <version> <major>4</major> <minor>0</minor> <build>-1</build> <revision>-1</revision> </version> </network_filter> <network_filter id="00000019-0019-0019-0019-00000000026b"> <name>example-network-filter-b</name> <version> <major>4</major> <minor>0</minor> <build>-1</build> <revision>-1</revision> </version> </network_filter> <network_filter id="00000019-0019-0019-0019-00000000026a"> <name>example-network-filter-a</name> <version> <major>3</major> <minor>0</minor> <build>-1</build> <revision>-1</revision> </version> </network_filter> </network_filters> Table 6.419. Methods summary Name Summary list Retrieves the representations of the network filters. 6.139.1. list GET Retrieves the representations of the network filters. The order of the returned list of network filters isn't guaranteed. Table 6.420. Parameters summary Name Type Direction Summary filters NetworkFilter[] Out follow String In Indicates which inner links should be followed . 6.139.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.140. NetworkLabel Table 6.421. Methods summary Name Summary get remove Removes a label from a logical network. 6.140.1. get GET Table 6.422. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . label NetworkLabel Out 6.140.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.140.2. remove DELETE Removes a label from a logical network. For example, to remove the label exemplary from a logical network having id 123 send the following request: Table 6.423. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.141. NetworkLabels Manages the ser of labels attached to a network or to a host NIC. Table 6.424. Methods summary Name Summary add Attaches label to logical network. list Returns the list of labels attached to the network or host NIC. 6.141.1. add POST Attaches label to logical network. You can attach labels to a logical network to automate the association of that logical network with physical host network interfaces to which the same label has been attached. For example, to attach the label mylabel to a logical network having id 123 send a request like this: With a request body like this: <label id="mylabel"/> Table 6.425. Parameters summary Name Type Direction Summary label NetworkLabel In/Out 6.141.2. list GET Returns the list of labels attached to the network or host NIC. The order of the returned list of labels isn't guaranteed. Table 6.426. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . labels NetworkLabel[] Out max Integer In Sets the maximum number of labels to return. 6.141.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.141.2.2. max Sets the maximum number of labels to return. If not specified all the labels are returned. 6.142. Networks Manages logical networks. The engine creates a default ovirtmgmt network on installation. This network acts as the management network for access to hypervisor hosts. This network is associated with the Default cluster and is a member of the Default data center. Table 6.427. Methods summary Name Summary add Creates a new logical network, or associates an existing network with a data center. list List logical networks. 6.142.1. add POST Creates a new logical network, or associates an existing network with a data center. Creation of a new network requires the name and data_center elements. For example, to create a network named mynetwork for data center 123 send a request like this: With a request body like this: <network> <name>mynetwork</name> <data_center id="123"/> </network> To associate the existing network 456 with the data center 123 send a request like this: With a request body like this: <network> <name>ovirtmgmt</name> </network> To create a network named exnetwork on top of an external OpenStack network provider 456 send a request like this: <network> <name>exnetwork</name> <external_provider id="456"/> <data_center id="123"/> </network> Table 6.428. Parameters summary Name Type Direction Summary network Network In/Out 6.142.2. list GET List logical networks. For example: Will respond: <networks> <network href="/ovirt-engine/api/networks/123" id="123"> <name>ovirtmgmt</name> <description>Default Management Network</description> <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/> <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/> <mtu>0</mtu> <stp>false</stp> <usages> <usage>vm</usage> </usages> <data_center href="/ovirt-engine/api/datacenters/456" id="456"/> </network> ... </networks> The order of the returned list of networks is guaranteed only if the sortby clause is included in the search parameter. Table 6.429. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of networks to return. networks Network[] Out search String In A query string used to restrict the returned networks. 6.142.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.142.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.142.2.3. max Sets the maximum number of networks to return. If not specified all the networks are returned. 6.143. NicNetworkFilterParameter This service manages a parameter for a network filter. Table 6.430. Methods summary Name Summary get Retrieves a representation of the network filter parameter. remove Removes the filter parameter. update Updates the network filter parameter. 6.143.1. get GET Retrieves a representation of the network filter parameter. Table 6.431. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . parameter NetworkFilterParameter Out The representation of the network filter parameter. 6.143.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.143.2. remove DELETE Removes the filter parameter. For example, to remove the filter parameter with id 123 on NIC 456 of virtual machine 789 send a request like this: 6.143.3. update PUT Updates the network filter parameter. For example, to update the network filter parameter having with with id 123 on NIC 456 of virtual machine 789 send a request like this: With a request body like this: <network_filter_parameter> <name>updatedName</name> <value>updatedValue</value> </network_filter_parameter> Table 6.432. Parameters summary Name Type Direction Summary parameter NetworkFilterParameter In/Out The network filter parameter that is being updated. 6.144. NicNetworkFilterParameters This service manages a collection of parameters for network filters. Table 6.433. Methods summary Name Summary add Add a network filter parameter. list Retrieves the representations of the network filter parameters. 6.144.1. add POST Add a network filter parameter. For example, to add the parameter for the network filter on NIC 456 of virtual machine 789 send a request like this: With a request body like this: <network_filter_parameter> <name>IP</name> <value>10.0.1.2</value> </network_filter_parameter> Table 6.434. Parameters summary Name Type Direction Summary parameter NetworkFilterParameter In/Out The network filter parameter that is being added. 6.144.2. list GET Retrieves the representations of the network filter parameters. The order of the returned list of network filters isn't guaranteed. Table 6.435. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . parameters NetworkFilterParameter[] Out The list of the network filter parameters. 6.144.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.145. OpenstackImage Table 6.436. Methods summary Name Summary get import Imports a virtual machine from a Glance image storage domain. 6.145.1. get GET Table 6.437. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . image OpenStackImage Out 6.145.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.145.2. import POST Imports a virtual machine from a Glance image storage domain. For example, to import the image with identifier 456 from the storage domain with identifier 123 send a request like this: With a request body like this: <action> <storage_domain> <name>images0</name> </storage_domain> <cluster> <name>images0</name> </cluster> </action> Table 6.438. Parameters summary Name Type Direction Summary async Boolean In Indicates if the import should be performed asynchronously. cluster Cluster In This parameter is mandatory in case of using import_as_template and indicates which cluster should be used for import glance image as template. disk Disk In import_as_template Boolean In Indicates whether the image should be imported as a template. storage_domain StorageDomain In template Template In 6.146. OpenstackImageProvider Table 6.439. Methods summary Name Summary get importcertificates Import the SSL certificates of the external host provider. remove testconnectivity In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. update Update the specified OpenStack image provider in the system. 6.146.1. get GET Table 6.440. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . provider OpenStackImageProvider Out 6.146.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.146.2. importcertificates POST Import the SSL certificates of the external host provider. Table 6.441. Parameters summary Name Type Direction Summary certificates Certificate[] In 6.146.3. remove DELETE Table 6.442. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.146.4. testconnectivity POST In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. Table 6.443. Parameters summary Name Type Direction Summary async Boolean In Indicates if the test should be performed asynchronously. 6.146.5. update PUT Update the specified OpenStack image provider in the system. Table 6.444. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. provider OpenStackImageProvider In/Out 6.147. OpenstackImageProviders Table 6.445. Methods summary Name Summary add Adds a new OpenStack image provider to the system. list Returns the list of providers. 6.147.1. add POST Adds a new OpenStack image provider to the system. Table 6.446. Parameters summary Name Type Direction Summary provider OpenStackImageProvider In/Out 6.147.2. list GET Returns the list of providers. The order of the returned list of providers is not guaranteed. Table 6.447. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of providers to return. providers OpenStackImageProvider[] Out search String In A query string used to restrict the returned OpenStack image providers. 6.147.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.147.2.2. max Sets the maximum number of providers to return. If not specified, all the providers are returned. 6.148. OpenstackImages Table 6.448. Methods summary Name Summary list Lists the images of a Glance image storage domain. 6.148.1. list GET Lists the images of a Glance image storage domain. The order of the returned list of images isn't guaranteed. Table 6.449. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . images OpenStackImage[] Out max Integer In Sets the maximum number of images to return. 6.148.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.148.1.2. max Sets the maximum number of images to return. If not specified all the images are returned. 6.149. OpenstackNetwork Table 6.450. Methods summary Name Summary get import This operation imports an external network into Red Hat Virtualization. 6.149.1. get GET Table 6.451. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . network OpenStackNetwork Out 6.149.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.149.2. import POST This operation imports an external network into Red Hat Virtualization. The network will be added to the specified data center. Table 6.452. Parameters summary Name Type Direction Summary async Boolean In Indicates if the import should be performed asynchronously. data_center DataCenter In The data center into which the network is to be imported. 6.149.2.1. data_center The data center into which the network is to be imported. Data center is mandatory, and can be specified using the id or name attributes. The rest of the attributes will be ignored. Note If auto_sync is enabled for the provider, the network might be imported automatically. To prevent this, automatic import can be disabled by setting the auto_sync to false, and enabling it again after importing the network. 6.150. OpenstackNetworkProvider This service manages the OpenStack network provider. Table 6.453. Methods summary Name Summary get Returns the representation of the object managed by this service. importcertificates Import the SSL certificates of the external host provider. remove Removes the provider. testconnectivity In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. update Updates the provider. 6.150.1. get GET Returns the representation of the object managed by this service. For example, to get the OpenStack network provider with identifier 1234 , send a request like this: Table 6.454. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . provider OpenStackNetworkProvider Out 6.150.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.150.2. importcertificates POST Import the SSL certificates of the external host provider. Table 6.455. Parameters summary Name Type Direction Summary certificates Certificate[] In 6.150.3. remove DELETE Removes the provider. For example, to remove the OpenStack network provider with identifier 1234 , send a request like this: Table 6.456. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.150.4. testconnectivity POST In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. Table 6.457. Parameters summary Name Type Direction Summary async Boolean In Indicates if the test should be performed asynchronously. 6.150.5. update PUT Updates the provider. For example, to update provider_name , requires_authentication , url , tenant_name and type properties, for the OpenStack network provider with identifier 1234 , send a request like this: With a request body like this: <openstack_network_provider> <name>ovn-network-provider</name> <requires_authentication>false</requires_authentication> <url>http://some_server_url.domain.com:9696</url> <tenant_name>oVirt</tenant_name> <type>external</type> </openstack_network_provider> Table 6.458. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. provider OpenStackNetworkProvider In/Out The provider to update. 6.151. OpenstackNetworkProviders This service manages OpenStack network providers. Table 6.459. Methods summary Name Summary add Adds a new network provider to the system. list Returns the list of providers. 6.151.1. add POST Adds a new network provider to the system. If the type property is not present, a default value of NEUTRON will be used. Table 6.460. Parameters summary Name Type Direction Summary provider OpenStackNetworkProvider In/Out 6.151.2. list GET Returns the list of providers. The order of the returned list of providers is not guaranteed. Table 6.461. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of providers to return. providers OpenStackNetworkProvider[] Out search String In A query string used to restrict the returned OpenStack network providers. 6.151.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.151.2.2. max Sets the maximum number of providers to return. If not specified, all the providers are returned. 6.152. OpenstackNetworks Table 6.462. Methods summary Name Summary list Returns the list of networks. 6.152.1. list GET Returns the list of networks. The order of the returned list of networks isn't guaranteed. Table 6.463. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of networks to return. networks OpenStackNetwork[] Out 6.152.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.152.1.2. max Sets the maximum number of networks to return. If not specified all the networks are returned. 6.153. OpenstackSubnet Table 6.464. Methods summary Name Summary get remove 6.153.1. get GET Table 6.465. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . subnet OpenStackSubnet Out 6.153.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.153.2. remove DELETE Table 6.466. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.154. OpenstackSubnets Table 6.467. Methods summary Name Summary add list Returns the list of sub-networks. 6.154.1. add POST Table 6.468. Parameters summary Name Type Direction Summary subnet OpenStackSubnet In/Out 6.154.2. list GET Returns the list of sub-networks. The order of the returned list of sub-networks isn't guaranteed. Table 6.469. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of sub-networks to return. subnets OpenStackSubnet[] Out 6.154.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.154.2.2. max Sets the maximum number of sub-networks to return. If not specified all the sub-networks are returned. 6.155. OpenstackVolumeAuthenticationKey Table 6.470. Methods summary Name Summary get remove update Update the specified authentication key. 6.155.1. get GET Table 6.471. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . key OpenstackVolumeAuthenticationKey Out 6.155.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.155.2. remove DELETE Table 6.472. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.155.3. update PUT Update the specified authentication key. Table 6.473. Parameters summary Name Type Direction Summary key OpenstackVolumeAuthenticationKey In/Out 6.156. OpenstackVolumeAuthenticationKeys Table 6.474. Methods summary Name Summary add Add a new authentication key to the OpenStack volume provider. list Returns the list of authentication keys. 6.156.1. add POST Add a new authentication key to the OpenStack volume provider. Table 6.475. Parameters summary Name Type Direction Summary key OpenstackVolumeAuthenticationKey In/Out 6.156.2. list GET Returns the list of authentication keys. The order of the returned list of authentication keys isn't guaranteed. Table 6.476. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . keys OpenstackVolumeAuthenticationKey[] Out max Integer In Sets the maximum number of keys to return. 6.156.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.156.2.2. max Sets the maximum number of keys to return. If not specified all the keys are returned. 6.157. OpenstackVolumeProvider Table 6.477. Methods summary Name Summary get importcertificates Import the SSL certificates of the external host provider. remove testconnectivity In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. update Update the specified OpenStack volume provider in the system. 6.157.1. get GET Table 6.478. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . provider OpenStackVolumeProvider Out 6.157.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.157.2. importcertificates POST Import the SSL certificates of the external host provider. Table 6.479. Parameters summary Name Type Direction Summary certificates Certificate[] In 6.157.3. remove DELETE Table 6.480. 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 provider removed from the database, even if something fails during the operation. 6.157.3.1. force Indicates if the operation should succeed, and the provider removed from the database, even if something fails during the operation. This parameter is optional, and the default value is false . 6.157.4. testconnectivity POST In order to test connectivity for external provider we need to run following request where 123 is an id of a provider. Table 6.481. Parameters summary Name Type Direction Summary async Boolean In Indicates if the test should be performed asynchronously. 6.157.5. update PUT Update the specified OpenStack volume provider in the system. Table 6.482. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. provider OpenStackVolumeProvider In/Out 6.158. OpenstackVolumeProviders Table 6.483. Methods summary Name Summary add Adds a new volume provider. list Retrieves the list of volume providers. 6.158.1. add POST Adds a new volume provider. For example: With a request body like this: <openstack_volume_provider> <name>mycinder</name> <url>https://mycinder.example.com:8776</url> <data_center> <name>mydc</name> </data_center> <requires_authentication>true</requires_authentication> <username>admin</username> <password>mypassword</password> <tenant_name>mytenant</tenant_name> </openstack_volume_provider> Table 6.484. Parameters summary Name Type Direction Summary provider OpenStackVolumeProvider In/Out 6.158.2. list GET Retrieves the list of volume providers. The order of the returned list of volume providers is not guaranteed. Table 6.485. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of providers to return. providers OpenStackVolumeProvider[] Out search String In A query string used to restrict the returned volume providers. 6.158.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.158.2.2. max Sets the maximum number of providers to return. If not specified, all the providers are returned. 6.159. OpenstackVolumeType Table 6.486. Methods summary Name Summary get 6.159.1. get GET Table 6.487. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . type OpenStackVolumeType Out 6.159.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.160. OpenstackVolumeTypes Table 6.488. Methods summary Name Summary list Returns the list of volume types. 6.160.1. list GET Returns the list of volume types. The order of the returned list of volume types isn't guaranteed. Table 6.489. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of volume types to return. types OpenStackVolumeType[] Out 6.160.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.160.1.2. max Sets the maximum number of volume types to return. If not specified all the volume types are returned. 6.161. OperatingSystem Table 6.490. Methods summary Name Summary get 6.161.1. get GET Table 6.491. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . operating_system OperatingSystemInfo Out 6.161.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.162. OperatingSystems Manages the set of types of operating systems available in the system. Table 6.492. Methods summary Name Summary list Returns the list of types of operating system available in the system. 6.162.1. list GET Returns the list of types of operating system available in the system. The order of the returned list of operating systems isn't guaranteed. Table 6.493. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of networks to return. operating_system OperatingSystemInfo[] Out 6.162.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.162.1.2. max Sets the maximum number of networks to return. If not specified all the networks are returned. 6.163. Permission Table 6.494. Methods summary Name Summary get remove 6.163.1. get GET Table 6.495. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . permission Permission Out 6.163.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.163.2. remove DELETE Table 6.496. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.164. Permit A service to manage a specific permit of the role. Table 6.497. Methods summary Name Summary get Gets the information about the permit of the role. remove Removes the permit from the role. 6.164.1. get GET Gets the information about the permit of the role. For example to retrieve the information about the permit with the id 456 of the role with the id 123 send a request like this: <permit href="/ovirt-engine/api/roles/123/permits/456" id="456"> <name>change_vm_cd</name> <administrative>false</administrative> <role href="/ovirt-engine/api/roles/123" id="123"/> </permit> Table 6.498. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . permit Permit Out The permit of the role. 6.164.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.164.2. remove DELETE Removes the permit from the role. For example to remove the permit with id 456 from the role with id 123 send a request like this: Table 6.499. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.165. Permits Represents a permits sub-collection of the specific role. Table 6.500. Methods summary Name Summary add Adds a permit to the role. list List the permits of the role. 6.165.1. add POST Adds a permit to the role. The permit name can be retrieved from the Section 6.39, "ClusterLevels" service. For example to assign a permit create_vm to the role with id 123 send a request like this: With a request body like this: <permit> <name>create_vm</name> </permit> Table 6.501. Parameters summary Name Type Direction Summary permit Permit In/Out The permit to add. 6.165.2. list GET List the permits of the role. For example to list the permits of the role with the id 123 send a request like this: <permits> <permit href="/ovirt-engine/api/roles/123/permits/5" id="5"> <name>change_vm_cd</name> <administrative>false</administrative> <role href="/ovirt-engine/api/roles/123" id="123"/> </permit> <permit href="/ovirt-engine/api/roles/123/permits/7" id="7"> <name>connect_to_vm</name> <administrative>false</administrative> <role href="/ovirt-engine/api/roles/123" id="123"/> </permit> </permits> The order of the returned list of permits isn't guaranteed. Table 6.502. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of permits to return. permits Permit[] Out List of permits. 6.165.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.165.2.2. max Sets the maximum number of permits to return. If not specified all the permits are returned. 6.166. Qos Table 6.503. Methods summary Name Summary get Get specified QoS in the data center. remove Remove specified QoS from datacenter. update Update the specified QoS in the dataCenter. 6.166.1. get GET Get specified QoS in the data center. You will get response like this one below: <qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123"> <name>123</name> <description>123</description> <max_iops>1</max_iops> <max_throughput>1</max_throughput> <type>storage</type> <data_center href="/ovirt-engine/api/datacenters/123" id="123"/> </qos> Table 6.504. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . qos Qos Out Queried QoS object. 6.166.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.166.2. remove DELETE Remove specified QoS from datacenter. Table 6.505. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.166.3. update PUT Update the specified QoS in the dataCenter. For example with curl: You will receive response like this: <qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123"> <name>321</name> <description>321</description> <max_iops>10</max_iops> <max_throughput>1</max_throughput> <type>storage</type> <data_center href="/ovirt-engine/api/datacenters/123" id="123"/> </qos> Table 6.506. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. qos Qos In/Out Updated QoS object. 6.167. Qoss Manages the set of quality of service configurations available in a data center. Table 6.507. Methods summary Name Summary add Add a new QoS to the dataCenter. list Returns the list of quality of service configurations available in the data center. 6.167.1. add POST Add a new QoS to the dataCenter. The response will look as follows: <qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123"> <name>123</name> <description>123</description> <max_iops>10</max_iops> <type>storage</type> <data_center href="/ovirt-engine/api/datacenters/123" id="123"/> </qos> Table 6.508. Parameters summary Name Type Direction Summary qos Qos In/Out Added QoS object. 6.167.2. list GET Returns the list of quality of service configurations available in the data center. You will get response which will look like this: <qoss> <qos href="/ovirt-engine/api/datacenters/123/qoss/1" id="1">...</qos> <qos href="/ovirt-engine/api/datacenters/123/qoss/2" id="2">...</qos> <qos href="/ovirt-engine/api/datacenters/123/qoss/3" id="3">...</qos> </qoss> The returned list of quality of service configurations isn't guaranteed. Table 6.509. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of QoS descriptors to return. qoss Qos[] Out List of queried QoS objects. 6.167.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.167.2.2. max Sets the maximum number of QoS descriptors to return. If not specified all the descriptors are returned. 6.168. Quota Table 6.510. Methods summary Name Summary get Retrieves a quota. remove Delete a quota. update Updates a quota. 6.168.1. get GET Retrieves a quota. An example of retrieving a quota: <quota id="456"> <name>myquota</name> <description>My new quota for virtual machines</description> <cluster_hard_limit_pct>20</cluster_hard_limit_pct> <cluster_soft_limit_pct>80</cluster_soft_limit_pct> <storage_hard_limit_pct>20</storage_hard_limit_pct> <storage_soft_limit_pct>80</storage_soft_limit_pct> </quota> Table 6.511. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . quota Quota Out 6.168.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.168.2. remove DELETE Delete a quota. An example of deleting a quota: Table 6.512. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.168.3. update PUT Updates a quota. An example of updating a quota: <quota> <cluster_hard_limit_pct>30</cluster_hard_limit_pct> <cluster_soft_limit_pct>70</cluster_soft_limit_pct> <storage_hard_limit_pct>20</storage_hard_limit_pct> <storage_soft_limit_pct>80</storage_soft_limit_pct> </quota> Table 6.513. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. quota Quota In/Out 6.169. QuotaClusterLimit Table 6.514. Methods summary Name Summary get remove 6.169.1. get GET Table 6.515. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . limit QuotaClusterLimit Out 6.169.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.169.2. remove DELETE Table 6.516. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.170. QuotaClusterLimits Manages the set of quota limits configured for a cluster. Table 6.517. Methods summary Name Summary add Add a cluster limit to a specified Quota. list Returns the set of quota limits configured for the cluster. 6.170.1. add POST Add a cluster limit to a specified Quota. Table 6.518. Parameters summary Name Type Direction Summary limit QuotaClusterLimit In/Out 6.170.2. list GET Returns the set of quota limits configured for the cluster. The returned list of quota limits isn't guaranteed. Table 6.519. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . limits QuotaClusterLimit[] Out max Integer In Sets the maximum number of limits to return. 6.170.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.170.2.2. max Sets the maximum number of limits to return. If not specified all the limits are returned. 6.171. QuotaStorageLimit Table 6.520. Methods summary Name Summary get remove 6.171.1. get GET Table 6.521. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . limit QuotaStorageLimit Out 6.171.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.171.2. remove DELETE Table 6.522. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. 6.172. QuotaStorageLimits Manages the set of storage limits configured for a quota. Table 6.523. Methods summary Name Summary add Adds a storage limit to a specified quota. list Returns the list of storage limits configured for the quota. 6.172.1. add POST Adds a storage limit to a specified quota. To create a 100GiB storage limit for all storage domains in a data center, send a request like this: With a request body like this: <quota_storage_limit> <limit>100</limit> </quota_storage_limit> To create a 50GiB storage limit for a storage domain with the ID 000 , send a request like this: With a request body like this: <quota_storage_limit> <limit>50</limit> <storage_domain id="000"/> </quota_storage_limit> Table 6.524. Parameters summary Name Type Direction Summary limit QuotaStorageLimit In/Out 6.172.2. list GET Returns the list of storage limits configured for the quota. The order of the returned list of storage limits is not guaranteed. Table 6.525. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . limits QuotaStorageLimit[] Out max Integer In Sets the maximum number of limits to return. 6.172.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.172.2.2. max Sets the maximum number of limits to return. If not specified, all the limits are returned. 6.173. Quotas Manages the set of quotas configured for a data center. Table 6.526. Methods summary Name Summary add Creates a new quota. list Lists quotas of a data center. 6.173.1. add POST Creates a new quota. An example of creating a new quota: <quota> <name>myquota</name> <description>My new quota for virtual machines</description> </quota> Table 6.527. Parameters summary Name Type Direction Summary quota Quota In/Out 6.173.2. list GET Lists quotas of a data center. The order of the returned list of quotas isn't guaranteed. Table 6.528. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of quota descriptors to return. quotas Quota[] Out 6.173.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.173.2.2. max Sets the maximum number of quota descriptors to return. If not specified all the descriptors are returned. 6.174. Role Table 6.529. Methods summary Name Summary get Get the role. remove Removes the role. update Updates a role. 6.174.1. get GET Get the role. You will receive XML response like this one: <role id="123"> <name>MyRole</name> <description>MyRole description</description> <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/> <administrative>true</administrative> <mutable>false</mutable> </role> Table 6.530. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . role Role Out Retrieved role. 6.174.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.174.2. remove DELETE Removes the role. To remove the role you need to know its id, then send request like this: Table 6.531. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.174.3. update PUT Updates a role. You are allowed to update name , description and administrative attributes after role is created. Within this endpoint you can't add or remove roles permits you need to use service that manages permits of role. For example to update role's name , description and administrative attributes send a request like this: With a request body like this: <role> <name>MyNewRoleName</name> <description>My new description of the role</description> <administrative>true</administrative> </group> Table 6.532. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. role Role In/Out Updated role. 6.175. Roles Provides read-only access to the global set of roles Table 6.533. Methods summary Name Summary add Create a new role. list List roles. 6.175.1. add POST Create a new role. The role can be administrative or non-administrative and can have different permits. For example, to add the MyRole non-administrative role with permits to login and create virtual machines send a request like this (note that you have to pass permit id): With a request body like this: <role> <name>MyRole</name> <description>My custom role to create virtual machines</description> <administrative>false</administrative> <permits> <permit id="1"/> <permit id="1300"/> </permits> </group> Table 6.534. Parameters summary Name Type Direction Summary role Role In/Out Role that will be added. 6.175.2. list GET List roles. You will receive response in XML like this one: <roles> <role id="123"> <name>SuperUser</name> <description>Roles management administrator</description> <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/> <administrative>true</administrative> <mutable>false</mutable> </role> ... </roles> The order of the returned list of roles isn't guaranteed. Table 6.535. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of roles to return. roles Role[] Out Retrieved list of roles. 6.175.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.175.2.2. max Sets the maximum number of roles to return. If not specified all the roles are returned. 6.176. SchedulingPolicies Manages the set of scheduling policies available in the system. Table 6.536. Methods summary Name Summary add Add a new scheduling policy to the system. list Returns the list of scheduling policies available in the system. 6.176.1. add POST Add a new scheduling policy to the system. Table 6.537. Parameters summary Name Type Direction Summary policy SchedulingPolicy In/Out 6.176.2. list GET Returns the list of scheduling policies available in the system. The order of the returned list of scheduling policies isn't guaranteed. Table 6.538. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of policies to return. policies SchedulingPolicy[] Out 6.176.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.176.2.2. max Sets the maximum number of policies to return. If not specified all the policies are returned. 6.177. SchedulingPolicy Table 6.539. Methods summary Name Summary get remove update Update the specified user defined scheduling policy in the system. 6.177.1. get GET Table 6.540. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . policy SchedulingPolicy Out 6.177.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.177.2. remove DELETE Table 6.541. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.177.3. update PUT Update the specified user defined scheduling policy in the system. Table 6.542. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. policy SchedulingPolicy In/Out 6.178. SchedulingPolicyUnit Table 6.543. Methods summary Name Summary get remove 6.178.1. get GET Table 6.544. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . unit SchedulingPolicyUnit Out 6.178.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.178.2. remove DELETE Table 6.545. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.179. SchedulingPolicyUnits Manages the set of scheduling policy units available in the system. Table 6.546. Methods summary Name Summary list Returns the list of scheduling policy units available in the system. 6.179.1. list GET Returns the list of scheduling policy units available in the system. The order of the returned list of scheduling policy units isn't guaranteed. Table 6.547. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of policy units to return. units SchedulingPolicyUnit[] Out 6.179.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.179.1.2. max Sets the maximum number of policy units to return. If not specified all the policy units are returned. 6.180. Snapshot Table 6.548. Methods summary Name Summary get remove restore Restores a virtual machine snapshot. 6.180.1. get GET Table 6.549. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . snapshot Snapshot Out 6.180.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.180.2. remove DELETE Table 6.550. Parameters summary Name Type Direction Summary all_content Boolean In Indicates if all the attributes of the virtual machine snapshot should be included in the response. async Boolean In Indicates if the remove should be performed asynchronously. 6.180.2.1. all_content Indicates if all the attributes of the virtual machine snapshot should be included in the response. By default the attribute initialization.configuration.data is excluded. For example, to retrieve the complete representation of the snapshot with id 456 of the virtual machine with id 123 send a request like this: 6.180.3. restore POST Restores a virtual machine snapshot. For example, to restore the snapshot with identifier 456 of virtual machine with identifier 123 send a request like this: With an empty action in the body: <action/> Note Confirm that the commit operation is finished and the virtual machine is down before running the virtual machine. Table 6.551. Parameters summary Name Type Direction Summary async Boolean In Indicates if the restore should be performed asynchronously. disks Disk[] In Specify the disks included in the snapshot's restore. restore_memory Boolean In 6.180.3.1. disks Specify the disks included in the snapshot's restore. For each disk parameter, it is also required to specify its image_id . For example, to restore a snapshot with an identifier 456 of a virtual machine with identifier 123 , including a disk with identifier 111 and image_id of 222 , send a request like this: Request body: <action> <disks> <disk id="111"> <image_id>222</image_id> </disk> </disks> </action> 6.181. SnapshotCdrom Table 6.552. Methods summary Name Summary get 6.181.1. get GET Table 6.553. Parameters summary Name Type Direction Summary cdrom Cdrom Out follow String In Indicates which inner links should be followed . 6.181.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.182. SnapshotCdroms Manages the set of CD-ROM devices of a virtual machine snapshot. Table 6.554. Methods summary Name Summary list Returns the list of CD-ROM devices of the snapshot. 6.182.1. list GET Returns the list of CD-ROM devices of the snapshot. The order of the returned list of CD-ROM devices isn't guaranteed. Table 6.555. Parameters summary Name Type Direction Summary cdroms Cdrom[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of CDROMS to return. 6.182.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.182.1.2. max Sets the maximum number of CDROMS to return. If not specified all the CDROMS are returned. 6.183. SnapshotDisk Table 6.556. Methods summary Name Summary get 6.183.1. get GET Table 6.557. Parameters summary Name Type Direction Summary disk Disk Out follow String In Indicates which inner links should be followed . 6.183.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.184. SnapshotDisks Manages the set of disks of an snapshot. Table 6.558. Methods summary Name Summary list Returns the list of disks of the snapshot. 6.184.1. list GET Returns the list of disks of the snapshot. The order of the returned list of disks isn't guaranteed. Table 6.559. Parameters summary Name Type Direction Summary disks Disk[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of disks to return. 6.184.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.184.1.2. max Sets the maximum number of disks to return. If not specified all the disks are returned. 6.185. SnapshotNic Table 6.560. Methods summary Name Summary get 6.185.1. get GET Table 6.561. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . nic Nic Out 6.185.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.186. SnapshotNics Manages the set of NICs of an snapshot. Table 6.562. Methods summary Name Summary list Returns the list of NICs of the snapshot. 6.186.1. list GET Returns the list of NICs of the snapshot. The order of the returned list of NICs isn't guaranteed. Table 6.563. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of NICs to return. nics Nic[] Out 6.186.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.186.1.2. max Sets the maximum number of NICs to return. If not specified all the NICs are returned. 6.187. Snapshots Manages the set of snapshots of a storage domain or virtual machine. Table 6.564. Methods summary Name Summary add Creates a virtual machine snapshot. list Returns the list of snapshots of the storage domain or virtual machine. 6.187.1. add POST Creates a virtual machine snapshot. For example, to create a new snapshot for virtual machine 123 send a request like this: With a request body like this: <snapshot> <description>My snapshot</description> </snapshot> For including only a sub-set of disks in the snapshots, add disk_attachments element to the request body. Note that disks which are not specified in disk_attachments element will not be a part of the snapshot. If an empty disk_attachments element is passed, the snapshot will include only the virtual machine configuration. If no disk_attachments element is passed, then all the disks will be included in the snapshot. For each disk, image_id element can be specified for setting the new active image id. This is used in order to restore a chain of images from backup. I.e. when restoring a disk with snapshots, the relevant image_id should be specified for each snapshot (so the identifiers of the disk snapshots are identical to the backup). <snapshot> <description>My snapshot</description> <disk_attachments> <disk_attachment> <disk id="123"> <image_id>456</image_id> </disk> </disk_attachment> </disk_attachments> </snapshot> Important When a snapshot is created the default value for the persist_memorystate attribute is true . That means that the content of the memory of the virtual machine will be included in the snapshot, and it also means that the virtual machine will be paused for a longer time. That can negatively affect applications that are very sensitive to timing (NTP servers, for example). In those cases make sure that you set the attribute to false : <snapshot> <description>My snapshot</description> <persist_memorystate>false</persist_memorystate> </snapshot> Table 6.565. Parameters summary Name Type Direction Summary snapshot Snapshot In/Out 6.187.2. list GET Returns the list of snapshots of the storage domain or virtual machine. The order of the returned list of snapshots isn't guaranteed. Table 6.566. Parameters summary Name Type Direction Summary all_content Boolean In Indicates if all the attributes of the virtual machine snapshot should be included in the response. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of snapshots to return. snapshots Snapshot[] Out 6.187.2.1. all_content Indicates if all the attributes of the virtual machine snapshot should be included in the response. By default the attribute initialization.configuration.data is excluded. For example, to retrieve the complete representation of the virtual machine with id 123 snapshots send a request like this: 6.187.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.187.2.3. max Sets the maximum number of snapshots to return. If not specified all the snapshots are returned. 6.188. SshPublicKey Table 6.567. Methods summary Name Summary get remove update 6.188.1. get GET Table 6.568. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . key SshPublicKey Out 6.188.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.188.2. remove DELETE Table 6.569. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.188.3. update PUT Table 6.570. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. key SshPublicKey In/Out 6.189. SshPublicKeys Table 6.571. Methods summary Name Summary add list Returns a list of SSH public keys of the user. 6.189.1. add POST Table 6.572. Parameters summary Name Type Direction Summary key SshPublicKey In/Out 6.189.2. list GET Returns a list of SSH public keys of the user. For example, to retrieve the list of SSH keys of user with identifier 123 , send a request like this: The result will be the following XML document: <ssh_public_keys> <ssh_public_key href="/ovirt-engine/api/users/123/sshpublickeys/456" id="456"> <content>ssh-rsa ...</content> <user href="/ovirt-engine/api/users/123" id="123"/> </ssh_public_key> </ssh_public_keys> Or the following JSON object { "ssh_public_key": [ { "content": "ssh-rsa ...", "user": { "href": "/ovirt-engine/api/users/123", "id": "123" }, "href": "/ovirt-engine/api/users/123/sshpublickeys/456", "id": "456" } ] } The order of the returned list of keys is not guaranteed. Table 6.573. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . keys SshPublicKey[] Out max Integer In Sets the maximum number of keys to return. 6.189.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.189.2.2. max Sets the maximum number of keys to return. If not specified all the keys are returned. 6.190. Statistic Table 6.574. Methods summary Name Summary get 6.190.1. get GET Table 6.575. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . statistic Statistic Out 6.190.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.191. Statistics Table 6.576. Methods summary Name Summary list Retrieves a list of statistics. 6.191.1. list GET Retrieves a list of statistics. For example, to retrieve the statistics for virtual machine 123 send a request like this: The result will be like this: <statistics> <statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456"> <name>memory.installed</name> <description>Total memory configured</description> <kind>gauge</kind> <type>integer</type> <unit>bytes</unit> <values> <value> <datum>1073741824</datum> </value> </values> <vm href="/ovirt-engine/api/vms/123" id="123"/> </statistic> ... </statistics> Just a single part of the statistics can be retrieved by specifying its id at the end of the URI. That means: Outputs: <statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456"> <name>memory.installed</name> <description>Total memory configured</description> <kind>gauge</kind> <type>integer</type> <unit>bytes</unit> <values> <value> <datum>1073741824</datum> </value> </values> <vm href="/ovirt-engine/api/vms/123" id="123"/> </statistic> The order of the returned list of statistics isn't guaranteed. Table 6.577. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of statistics to return. statistics Statistic[] Out 6.191.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.191.1.2. max Sets the maximum number of statistics to return. If not specified all the statistics are returned. 6.192. Step A service to manage a step. Table 6.578. Methods summary Name Summary end Marks an external step execution as ended. get Retrieves a step. 6.192.1. end POST Marks an external step execution as ended. For example, to terminate a step with identifier 456 which belongs to a job with identifier 123 send the following request: With the following request body: <action> <force>true</force> <succeeded>true</succeeded> </action> Table 6.579. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. force Boolean In Indicates if the step should be forcibly terminated. succeeded Boolean In Indicates if the step should be marked as successfully finished or as failed. 6.192.1.1. succeeded Indicates if the step should be marked as successfully finished or as failed. This parameter is optional, and the default value is true . 6.192.2. get GET Retrieves a step. You will receive response in XML like this one: <step href="/ovirt-engine/api/jobs/123/steps/456" id="456"> <actions> <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/> </actions> <description>Validating</description> <end_time>2016-12-12T23:07:26.627+02:00</end_time> <external>false</external> <number>0</number> <start_time>2016-12-12T23:07:26.605+02:00</start_time> <status>finished</status> <type>validating</type> <job href="/ovirt-engine/api/jobs/123" id="123"/> </step> Table 6.580. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . step Step Out Retrieves the representation of the step. 6.192.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.193. Steps A service to manage steps. Table 6.581. Methods summary Name Summary add Add an external step to an existing job or to an existing step. list Retrieves the representation of the steps. 6.193.1. add POST Add an external step to an existing job or to an existing step. For example, to add a step to job with identifier 123 send the following request: With the following request body: <step> <description>Validating</description> <start_time>2016-12-12T23:07:26.605+02:00</start_time> <status>started</status> <type>validating</type> </step> The response should look like: <step href="/ovirt-engine/api/jobs/123/steps/456" id="456"> <actions> <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/> </actions> <description>Validating</description> <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/> <external>true</external> <number>2</number> <start_time>2016-12-13T01:06:15.380+02:00</start_time> <status>started</status> <type>validating</type> <job href="/ovirt-engine/api/jobs/123" id="123"/> </step> Table 6.582. Parameters summary Name Type Direction Summary step Step In/Out Step that will be added. 6.193.2. list GET Retrieves the representation of the steps. You will receive response in XML like this one: <steps> <step href="/ovirt-engine/api/jobs/123/steps/456" id="456"> <actions> <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/> </actions> <description>Validating</description> <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/> <external>true</external> <number>2</number> <start_time>2016-12-13T01:06:15.380+02:00</start_time> <status>started</status> <type>validating</type> <job href="/ovirt-engine/api/jobs/123" id="123"/> </step> ... </steps> The order of the returned list of steps isn't guaranteed. Table 6.583. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of steps to return. steps Step[] Out A representation of steps. 6.193.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.193.2.2. max Sets the maximum number of steps to return. If not specified all the steps are returned. 6.194. Storage Table 6.584. Methods summary Name Summary get 6.194.1. get GET Table 6.585. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . report_status Boolean In Indicates if the status of the LUNs in the storage should be checked. storage HostStorage Out 6.194.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.194.1.2. 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="360014051136c20574f743bdbd28177fd"> <logical_units> <logical_unit id="360014051136c20574f743bdbd28177fd"> <lun_mapping>0</lun_mapping> <paths>1</paths> <product_id>lun0</product_id> <serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial> <size>10737418240</size> <status>used</status> <vendor_id>LIO-ORG</vendor_id> <volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-MNzIBZ</volume_group_id> </logical_unit> </logical_units> <type>iscsi</type> <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/> </host_storage> Here an example without the LUN status : <host_storage id="360014051136c20574f743bdbd28177fd"> <logical_units> <logical_unit id="360014051136c20574f743bdbd28177fd"> <lun_mapping>0</lun_mapping> <paths>1</paths> <product_id>lun0</product_id> <serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial> <size>10737418240</size> <vendor_id>LIO-ORG</vendor_id> <volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-MNzIBZ</volume_group_id> </logical_unit> </logical_units> <type>iscsi</type> <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/> </host_storage> 6.195. StorageDomain Table 6.586. Methods summary Name Summary get Retrieves the description of the storage domain. isattached Used for querying if the storage domain is already attached to a data center using the is_attached boolean field, which is part of the storage server. reduceluns This operation reduces logical units from the storage domain. refreshluns This operation refreshes the LUN size. remove Removes the storage domain. update Updates a storage domain. updateovfstore This operation forces the update of the OVF_STORE of this storage domain. 6.195.1. get GET Retrieves the description of the storage domain. Table 6.587. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . storage_domain StorageDomain Out The description of the storage domain. 6.195.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.195.2. isattached POST Used for querying if the storage domain is already attached to a data center using the is_attached boolean field, which is part of the storage server. IMPORTANT: Executing this API will cause the host to disconnect from the storage domain. Table 6.588. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. host Host In Indicates the data center's host. is_attached Boolean Out Indicates whether the storage domain is attached to the data center. 6.195.3. reduceluns POST This operation reduces logical units from the storage domain. In order to do so the data stored on the provided logical units will be moved to other logical units of the storage domain and only then they will be reduced from the storage domain. For example, in order to reduce two logical units from a storage domain send a request like this: With a request body like this: <action> <logical_units> <logical_unit id="1IET_00010001"/> <logical_unit id="1IET_00010002"/> </logical_units> </action> Table 6.589. Parameters summary Name Type Direction Summary logical_units LogicalUnit[] In The logical units that need to be reduced from the storage domain. 6.195.4. refreshluns POST This operation refreshes the LUN size. After increasing the size of the underlying LUN on the storage server, the user can refresh the LUN size. This action forces a rescan of the provided LUNs and updates the database with the new size, if required. For example, in order to refresh the size of two LUNs send a request like this: With a request body like this: <action> <logical_units> <logical_unit id="1IET_00010001"/> <logical_unit id="1IET_00010002"/> </logical_units> </action> Table 6.590. Parameters summary Name Type Direction Summary async Boolean In Indicates if the refresh should be performed asynchronously. logical_units LogicalUnit[] In The LUNs that need to be refreshed. 6.195.5. remove DELETE Removes the storage domain. Without any special parameters, the storage domain is detached from the system and removed from the database. The storage domain can then be imported to the same or to a different setup, with all the data on it. If the storage is not accessible the operation will fail. If the destroy parameter is true then the operation will always succeed, even if the storage is not accessible, the failure is just ignored and the storage domain is removed from the database anyway. If the format parameter is true then the actual storage is formatted, and the metadata is removed from the LUN or directory, so it can no longer be imported to the same or to a different setup. Table 6.591. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. destroy Boolean In Indicates if the operation should succeed, and the storage domain removed from the database, even if the storage is not accessible. format Boolean In Indicates if the actual storage should be formatted, removing all the metadata from the underlying LUN or directory: [source] ---- DELETE /ovirt-engine/api/storagedomains/123?format=true ---- This parameter is optional, and the default value is false . host String In Indicates which host should be used to remove the storage domain. 6.195.5.1. destroy Indicates if the operation should succeed, and the storage domain removed from the database, even if the storage is not accessible. This parameter is optional, and the default value is false . When the value of destroy is true the host parameter will be ignored. 6.195.5.2. host Indicates which host should be used to remove the storage domain. This parameter is mandatory, except if the destroy parameter is included and its value is true , in that case the host parameter will be ignored. The value should contain the name or the identifier of the host. For example, to use the host named myhost to remove the storage domain with identifier 123 send a request like this: 6.195.6. update PUT Updates a storage domain. Not all of the StorageDomain 's attributes are updatable after creation. Those that can be updated are: name , description , comment , warning_low_space_indicator , critical_space_action_blocker and wipe_after_delete. (Note that changing the wipe_after_delete attribute will not change the wipe after delete property of disks that already exist). To update the name and wipe_after_delete attributes of a storage domain with an identifier 123 , send a request as follows: With a request body as follows: <storage_domain> <name>data2</name> <wipe_after_delete>true</wipe_after_delete> </storage_domain> Table 6.592. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. storage_domain StorageDomain In/Out The updated storage domain. 6.195.7. updateovfstore POST This operation forces the update of the OVF_STORE of this storage domain. The OVF_STORE is a disk image that contains the metadata of virtual machines and disks that reside in the storage domain. This metadata is used in case the domain is imported or exported to or from a different data center or a different installation. By default the OVF_STORE is updated periodically (set by default to 60 minutes) but users might want to force an update after an important change, or when the they believe the OVF_STORE is corrupt. When initiated by the user, OVF_STORE update will be performed whether an update is needed or not. Table 6.593. Parameters summary Name Type Direction Summary async Boolean In Indicates if the OVF_STORE update should be performed asynchronously. 6.196. StorageDomainContentDisk Table 6.594. Methods summary Name Summary get 6.196.1. get GET Table 6.595. Parameters summary Name Type Direction Summary disk Disk Out filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . 6.196.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.197. StorageDomainContentDisks Manages the set of disks available in a storage domain. Table 6.596. Methods summary Name Summary list Returns the list of disks available in the storage domain. 6.197.1. list GET Returns the list of disks available in the storage domain. The order of the returned list of disks is guaranteed only if the sortby clause is included in the search parameter. Table 6.597. 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 follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of disks to return. search String In A query string used to restrict the returned disks. 6.197.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.197.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.197.1.3. max Sets the maximum number of disks to return. If not specified all the disks are returned. 6.198. StorageDomainDisk Manages a single disk available in a storage domain. Important Since version 4.2 of the engine this service is intended only to list disks available in the storage domain, and to register unregistered disks. All the other operations, like copying a disk, moving a disk, etc, have been deprecated and will be removed in the future. To perform those operations use the service that manages all the disks of the system , or the service that manages an specific disk . Table 6.598. Methods summary Name Summary copy Copies a disk to the specified storage domain. export Exports a disk to an export storage domain. get Retrieves the description of the disk. move Moves a disk to another storage domain. reduce Reduces the size of the disk image. remove Removes a disk. sparsify Sparsify the disk. update Updates the disk. 6.198.1. copy POST Copies a disk to the specified storage domain. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To copy a disk use the copy operation of the service that manages that disk. Table 6.599. Parameters summary Name Type Direction Summary disk Disk In Description of the resulting disk. storage_domain StorageDomain In The storage domain where the new disk will be created. 6.198.2. export POST Exports a disk to an export storage domain. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To export a disk use the export operation of the service that manages that disk. Table 6.600. Parameters summary Name Type Direction Summary storage_domain StorageDomain In The export storage domain where the disk should be exported to. 6.198.3. get GET Retrieves the description of the disk. Table 6.601. Parameters summary Name Type Direction Summary disk Disk Out The description of the disk. follow String In Indicates which inner links should be followed . 6.198.3.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.198.4. move POST Moves a disk to another storage domain. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To move a disk use the move operation of the service that manages that disk. Table 6.602. Parameters summary Name Type Direction Summary async Boolean In Indicates if the move should be performed asynchronously. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. storage_domain StorageDomain In The storage domain where the disk will be moved to. 6.198.5. reduce POST Reduces the size of the disk image. Invokes reduce on the logical volume (i.e. this is only applicable for block storage domains). This is applicable for floating disks and disks attached to non-running virtual machines. There is no need to specify the size as the optimal size is calculated automatically. Table 6.603. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.198.6. remove DELETE Removes a disk. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk. 6.198.7. sparsify POST Sparsify the disk. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To remove a disk use the remove operation of the service that manages that disk. 6.198.8. update PUT Updates the disk. Important Since version 4.2 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To update a disk use the update operation of the service that manages that disk. Table 6.604. Parameters summary Name Type Direction Summary disk Disk In/Out The update to apply to the disk. 6.199. StorageDomainDisks Manages the collection of disks available inside a specific storage domain. Table 6.605. Methods summary Name Summary add Adds or registers a disk. list Retrieves the list of disks that are available in the storage domain. 6.199.1. add POST Adds or registers a disk. Important Since version 4.2 of the Red Hat Virtualization Manager this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. To add a new disk use the add operation of the service that manages the disks of the system. To register an unregistered disk use the register operation of the service that manages that disk. Table 6.606. Parameters summary Name Type Direction Summary disk Disk In/Out The disk to add or register. unregistered Boolean In Indicates if a new disk should be added or if an existing unregistered disk should be registered. 6.199.1.1. unregistered Indicates if a new disk should be added or if an existing unregistered disk should be registered. If the value is true then the identifier of the disk to register needs to be provided. For example, to register the disk with ID 456 send a request like this: With a request body like this: <disk id="456"/> If the value is false then a new disk will be created in the storage domain. In that case the provisioned_size , format , and name attributes are mandatory. For example, to create a new copy on write disk of 1 GiB, send a request like this: With a request body like this: <disk> <name>mydisk</name> <format>cow</format> <provisioned_size>1073741824</provisioned_size> </disk> The default value is false . This parameter has been deprecated since version 4.2 of the Red Hat Virtualization Manager. 6.199.2. list GET Retrieves the list of disks that are available in the storage domain. The order of the returned list of disks is not guaranteed. Table 6.607. Parameters summary Name Type Direction Summary disks Disk[] Out The list of retrieved disks. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of disks to return. unregistered Boolean In Indicates whether to retrieve a list of registered or unregistered disks in the storage domain. 6.199.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.199.2.2. max Sets the maximum number of disks to return. If not specified, all the disks are returned. 6.199.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: The default value of the unregistered flag is false . The request only applies to storage domains that are attached. 6.200. StorageDomainServerConnection Table 6.608. Methods summary Name Summary get remove Detaches a storage connection from storage. 6.200.1. get GET Table 6.609. Parameters summary Name Type Direction Summary connection StorageConnection Out follow String In Indicates which inner links should be followed . 6.200.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.200.2. remove DELETE Detaches a storage connection from storage. Table 6.610. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.201. StorageDomainServerConnections Manages the set of connections to storage servers that exist in a storage domain. Table 6.611. Methods summary Name Summary add list Returns the list of connections to storage servers that existin the storage domain. 6.201.1. add POST Table 6.612. Parameters summary Name Type Direction Summary connection StorageConnection In/Out 6.201.2. list GET Returns the list of connections to storage servers that existin the storage domain. The order of the returned list of connections isn't guaranteed. Table 6.613. Parameters summary Name Type Direction Summary connections StorageConnection[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of connections to return. 6.201.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.201.2.2. max Sets the maximum number of connections to return. If not specified all the connections are returned. 6.202. StorageDomainTemplate Table 6.614. Methods summary Name Summary get import Action to import a template from an export storage domain. register Register the Template means importing the Template from the data domain by inserting the configuration of the Template and disks into the database without the copy process. remove 6.202.1. get GET Table 6.615. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . template Template Out 6.202.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.202.2. import POST Action to import a template from an export storage domain. For example, to import the template 456 from the storage domain 123 send the following request: With the following request body: <action> <storage_domain> <name>myexport</name> </storage_domain> <cluster> <name>mycluster</name> </cluster> </action> If you register an entity without specifying the cluster ID or name, the cluster name from the entity's OVF will be used (unless the register request also includes the cluster mapping). Table 6.616. Parameters summary Name Type Direction Summary async Boolean In Indicates if the import should be performed asynchronously. clone Boolean In Use the optional clone parameter to generate new UUIDs for the imported template and its entities. cluster Cluster In exclusive Boolean In storage_domain StorageDomain In template Template In vm Vm In 6.202.2.1. clone Use the optional clone parameter to generate new UUIDs for the imported template and its entities. You can import a template with the clone parameter set to false when importing a template from an export domain, with templates that were exported by a different Red Hat Virtualization environment. 6.202.3. register POST Register the Template means importing the Template from the data domain by inserting the configuration of the Template and disks into the database without the copy process. Table 6.617. Parameters summary Name Type Direction Summary allow_partial_import Boolean In Indicates whether a template is allowed to be registered with only some of its disks. async Boolean In Indicates if the registration should be performed asynchronously. clone Boolean In cluster Cluster In exclusive Boolean In registration_configuration RegistrationConfiguration In This parameter describes how the template should be registered. template Template In vnic_profile_mappings VnicProfileMapping[] In Deprecated attribute describing mapping rules for virtual NIC profiles that will be applied during the import\register process. 6.202.3.1. allow_partial_import Indicates whether a template is allowed to be registered with only some of its disks. If this flag is true , the system will not fail in the validation process if an image is not found, but instead it will allow the template to be registered without the missing disks. This is mainly used during registration of a template when some of the storage domains are not available. The default value is false . 6.202.3.2. registration_configuration This parameter describes how the template should be registered. This parameter is optional. If the parameter is not specified, the template will be registered with the same configuration that it had in the original environment where it was created. 6.202.3.3. vnic_profile_mappings Deprecated attribute describing mapping rules for virtual NIC profiles that will be applied during the import\register process. Warning Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future. To specify vnic_profile_mappings use the vnic_profile_mappings attribute inside the RegistrationConfiguration type. 6.202.4. remove DELETE Table 6.618. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.203. StorageDomainTemplates Manages the set of templates available in a storage domain. Table 6.619. Methods summary Name Summary list Returns the list of templates availalbe in the storage domain. 6.203.1. list GET Returns the list of templates availalbe in the storage domain. The order of the returned list of templates isn't guaranteed. Table 6.620. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of templates to return. templates Template[] Out unregistered Boolean In Indicates whether to retrieve a list of registered or unregistered templates which contain disks on the storage domain. 6.203.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.203.1.2. max Sets the maximum number of templates to return. If not specified all the templates are returned. 6.203.1.3. unregistered Indicates whether to retrieve a list of registered or unregistered templates which contain disks on the storage domain. To get a list of unregistered templates the call should indicate the unregistered flag. For example, to get a list of unregistered templates the REST API call should look like this: The default value of the unregisterd flag is false . The request only apply to storage domains that are attached. 6.204. StorageDomainVm Table 6.621. Methods summary Name Summary get import Imports a virtual machine from an export storage domain. register remove Deletes a virtual machine from an export storage domain. 6.204.1. get GET Table 6.622. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . vm Vm Out 6.204.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.204.2. import POST Imports a virtual machine from an export storage domain. For example, send a request like this: With a request body like this: <action> <storage_domain> <name>mydata</name> </storage_domain> <cluster> <name>mycluster</name> </cluster> </action> To import a virtual machine as a new entity add the clone parameter: <action> <storage_domain> <name>mydata</name> </storage_domain> <cluster> <name>mycluster</name> </cluster> <clone>true</clone> <vm> <name>myvm</name> </vm> </action> Include an optional disks parameter to choose which disks to import. For example, to import the disks of the template that have the identifiers 123 and 456 send the following request body: <action> <cluster> <name>mycluster</name> </cluster> <vm> <name>myvm</name> </vm> <disks> <disk id="123"/> <disk id="456"/> </disks> </action> If you register an entity without specifying the cluster ID or name, the cluster name from the entity's OVF will be used (unless the register request also includes the cluster mapping). Table 6.623. Parameters summary Name Type Direction Summary async Boolean In Indicates if the import should be performed asynchronously. clone Boolean In Indicates if the identifiers of the imported virtual machine should be regenerated. cluster Cluster In collapse_snapshots Boolean In Indicates of the snapshots of the virtual machine that is imported should be collapsed, so that the result will be a virtual machine without snapshots. exclusive Boolean In storage_domain StorageDomain In vm Vm In 6.204.2.1. clone Indicates if the identifiers of the imported virtual machine should be regenerated. By default when a virtual machine is imported the identifiers are preserved. This means that the same virtual machine can't be imported multiple times, as that identifiers needs to be unique. To allow importing the same machine multiple times set this parameter to true , as the default is false . 6.204.2.2. collapse_snapshots Indicates of the snapshots of the virtual machine that is imported should be collapsed, so that the result will be a virtual machine without snapshots. This parameter is optional, and if it isn't explicitly specified the default value is false . 6.204.3. register POST Table 6.624. Parameters summary Name Type Direction Summary allow_partial_import Boolean In Indicates whether a virtual machine is allowed to be registered with only some of its disks. async Boolean In Indicates if the registration should be performed asynchronously. clone Boolean In cluster Cluster In reassign_bad_macs Boolean In Indicates if the problematic MAC addresses should be re-assigned during the import process by the engine. registration_configuration RegistrationConfiguration In This parameter describes how the virtual machine should be registered. vm Vm In vnic_profile_mappings VnicProfileMapping[] In Deprecated attribute describing mapping rules for virtual NIC profiles that will be applied during the import\register process. 6.204.3.1. allow_partial_import Indicates whether a virtual machine is allowed to be registered with only some of its disks. If this flag is true , the engine will not fail in the validation process if an image is not found, but instead it will allow the virtual machine to be registered without the missing disks. This is mainly used during registration of a virtual machine when some of the storage domains are not available. The default value is false . 6.204.3.2. reassign_bad_macs Indicates if the problematic MAC addresses should be re-assigned during the import process by the engine. A MAC address would be considered as a problematic one if one of the following is true: It conflicts with a MAC address that is already allocated to a virtual machine in the target environment. It's out of the range of the target MAC address pool. 6.204.3.3. registration_configuration This parameter describes how the virtual machine should be registered. This parameter is optional. If the parameter is not specified, the virtual machine will be registered with the same configuration that it had in the original environment where it was created. 6.204.3.4. vnic_profile_mappings Deprecated attribute describing mapping rules for virtual NIC profiles that will be applied during the import\register process. Warning Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future. To specify vnic_profile_mappings use the vnic_profile_mappings attribute inside the RegistrationConfiguration type. 6.204.4. remove DELETE Deletes a virtual machine from an export storage domain. For example, to delete the virtual machine 456 from the storage domain 123 , send a request like this: Table 6.625. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.205. StorageDomainVmDiskAttachment Returns the details of the disks attached to a virtual machine in the export domain. Table 6.626. Methods summary Name Summary get Returns the details of the attachment with all its properties and a link to the disk. 6.205.1. get GET Returns the details of the attachment with all its properties and a link to the disk. Table 6.627. Parameters summary Name Type Direction Summary attachment DiskAttachment Out The disk attachment. follow String In Indicates which inner links should be followed . 6.205.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.206. StorageDomainVmDiskAttachments Returns the details of a disk attached to a virtual machine in the export domain. Table 6.628. Methods summary Name Summary list List the disks that are attached to the virtual machine. 6.206.1. list GET List the disks that are attached to the virtual machine. The order of the returned list of disk attachments isn't guaranteed. Table 6.629. Parameters summary Name Type Direction Summary attachments DiskAttachment[] Out follow String In Indicates which inner links should be followed . 6.206.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.207. StorageDomainVms Lists the virtual machines of an export storage domain. For example, to retrieve the virtual machines that are available in the storage domain with identifier 123 send the following request: This will return the following response body: <vms> <vm id="456" href="/api/storagedomains/123/vms/456"> <name>vm1</name> ... <storage_domain id="123" href="/api/storagedomains/123"/> <actions> <link rel="import" href="/api/storagedomains/123/vms/456/import"/> </actions> </vm> </vms> Virtual machines and templates in these collections have a similar representation to their counterparts in the top-level Vm and Template collections, except they also contain a StorageDomain reference and an import action. Table 6.630. Methods summary Name Summary list Returns the list of virtual machines of the export storage domain. 6.207.1. list GET Returns the list of virtual machines of the export storage domain. The order of the returned list of virtual machines isn't guaranteed. Table 6.631. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of virtual machines to return. unregistered Boolean In Indicates whether to retrieve a list of registered or unregistered virtual machines which contain disks on the storage domain. vm Vm[] Out 6.207.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.207.1.2. max Sets the maximum number of virtual machines to return. If not specified all the virtual machines are returned. 6.207.1.3. unregistered Indicates whether to retrieve a list of registered or unregistered virtual machines which contain disks on the storage domain. To get a list of unregistered virtual machines the call should indicate the unregistered flag. For example, to get a list of unregistered virtual machines the REST API call should look like this: The default value of the unregisterd flag is false . The request only apply to storage domains that are attached. 6.208. StorageDomains Manages the set of storage domains in the system. Table 6.632. Methods summary Name Summary add Adds a new storage domain. list Returns the list of storage domains in the system. 6.208.1. add POST Adds a new storage domain. Creation of a new StorageDomain requires the name , type , host , and storage attributes. Identify the host attribute with the id or name attributes. In Red Hat Virtualization 3.6 and later you can enable the wipe after delete option by default on the storage domain. To configure this, specify wipe_after_delete in the POST request. This option can be edited after the domain is created, but doing so will not change the wipe after delete property of disks that already exist. To add a new storage domain with specified name , type , storage.type , storage.address , and storage.path , and using a host with an id 123 , send a request like this: With a request body like this: <storage_domain> <name>mydata</name> <type>data</type> <storage> <type>nfs</type> <address>mynfs.example.com</address> <path>/exports/mydata</path> </storage> <host> <name>myhost</name> </host> </storage_domain> To create a new NFS ISO storage domain send a request like this: <storage_domain> <name>myisos</name> <type>iso</type> <storage> <type>nfs</type> <address>mynfs.example.com</address> <path>/export/myisos</path> </storage> <host> <name>myhost</name> </host> </storage_domain> To create a new iSCSI storage domain send a request like this: <storage_domain> <name>myiscsi</name> <type>data</type> <storage> <type>iscsi</type> <logical_units> <logical_unit id="3600144f09dbd050000004eedbd340001"/> <logical_unit id="3600144f09dbd050000004eedbd340002"/> </logical_units> </storage> <host> <name>myhost</name> </host> </storage_domain> Table 6.633. Parameters summary Name Type Direction Summary storage_domain StorageDomain In/Out The storage domain to add. 6.208.2. list GET Returns the list of storage domains in the system. The order of the returned list of storage domains is guaranteed only if the sortby clause is included in the search parameter. Table 6.634. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search should be performed taking case into account. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of storage domains to return. search String In A query string used to restrict the returned storage domains. storage_domains StorageDomain[] Out A list of the storage domains in the system. 6.208.2.1. case_sensitive Indicates if the search should be performed taking case into account. The default value is true , which means that case is taken into account. If you want to search ignoring case, set it to false . 6.208.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.208.2.3. max Sets the maximum number of storage domains to return. If not specified, all the storage domains are returned. 6.209. StorageServerConnection Table 6.635. Methods summary Name Summary get remove Removes a storage connection. update Updates the storage connection. 6.209.1. get GET Table 6.636. Parameters summary Name Type Direction Summary conection StorageConnection Out follow String In Indicates which inner links should be followed . 6.209.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.209.2. remove DELETE Removes a storage connection. A storage connection can only be deleted if neither storage domain nor LUN disks reference it. The host name or id is optional; providing it disconnects (unmounts) the connection from that host. Table 6.637. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. host String In The name or identifier of the host from which the connection would be unmounted (disconnected). 6.209.2.1. host The name or identifier of the host from which the connection would be unmounted (disconnected). If not provided, no host will be disconnected. For example, to use the host with identifier 456 to delete the storage connection with identifier 123 send a request like this: 6.209.3. update PUT Updates the storage connection. For example, to change the address of an NFS storage server, send a request like this: PUT /ovirt-engine/api/storageconnections/123 With a request body like this: <storage_connection> <address>mynewnfs.example.com</address> </storage_connection> To change the connection of an iSCSI storage server, send a request like this: PUT /ovirt-engine/api/storageconnections/123 With a request body like this: <storage_connection> <port>3260</port> <target>iqn.2017-01.com.myhost:444</target> </storage_connection> Table 6.638. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. connection StorageConnection In/Out force Boolean In Indicates if the operation should succeed regardless to the relevant storage domain's status (i. 6.209.3.1. force Indicates if the operation should succeed regardless to the relevant storage domain's status (i.e. updating is also applicable when storage domain's status is not maintenance). This parameter is optional, and the default value is false . 6.210. StorageServerConnectionExtension Table 6.639. Methods summary Name Summary get remove update Update a storage server connection extension for the given host. 6.210.1. get GET Table 6.640. Parameters summary Name Type Direction Summary extension StorageConnectionExtension Out follow String In Indicates which inner links should be followed . 6.210.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.210.2. remove DELETE Table 6.641. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.210.3. update PUT Update a storage server connection extension for the given host. To update the storage connection 456 of host 123 send a request like this: With a request body like this: <storage_connection_extension> <target>iqn.2016-01.com.example:mytarget</target> <username>myuser</username> <password>mypassword</password> </storage_connection_extension> Table 6.642. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. extension StorageConnectionExtension In/Out 6.211. StorageServerConnectionExtensions Table 6.643. Methods summary Name Summary add Creates a new storage server connection extension for the given host. list Returns the list os storage connection extensions. 6.211.1. add POST Creates a new storage server connection extension for the given host. The extension lets the user define credentials for an iSCSI target for a specific host. For example to use myuser and mypassword as the credentials when connecting to the iSCSI target from host 123 send a request like this: With a request body like this: <storage_connection_extension> <target>iqn.2016-01.com.example:mytarget</target> <username>myuser</username> <password>mypassword</password> </storage_connection_extension> Table 6.644. Parameters summary Name Type Direction Summary extension StorageConnectionExtension In/Out 6.211.2. list GET Returns the list os storage connection extensions. The order of the returned list of storage connections isn't guaranteed. Table 6.645. Parameters summary Name Type Direction Summary extensions StorageConnectionExtension[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of extensions to return. 6.211.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.211.2.2. max Sets the maximum number of extensions to return. If not specified all the extensions are returned. 6.212. StorageServerConnections Table 6.646. Methods summary Name Summary add Creates a new storage connection. list Returns the list of storage connections. 6.212.1. add POST Creates a new storage connection. For example, to create a new storage connection for the NFS server mynfs.example.com and NFS share /export/mydata send a request like this: With a request body like this: <storage_connection> <type>nfs</type> <address>mynfs.example.com</address> <path>/export/mydata</path> <host> <name>myhost</name> </host> </storage_connection> Table 6.647. Parameters summary Name Type Direction Summary connection StorageConnection In/Out 6.212.2. list GET Returns the list of storage connections. The order of the returned list of connections isn't guaranteed. Table 6.648. Parameters summary Name Type Direction Summary connections StorageConnection[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of connections to return. 6.212.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.212.2.2. max Sets the maximum number of connections to return. If not specified all the connections are returned. 6.213. System Table 6.649. Methods summary Name Summary get Returns basic information describing the API, like the product name, the version number and a summary of the number of relevant objects. reloadconfigurations 6.213.1. get GET Returns basic information describing the API, like the product name, the version number and a summary of the number of relevant objects. We get following response: <api> <link rel="capabilities" href="/api/capabilities"/> <link rel="clusters" href="/api/clusters"/> <link rel="clusters/search" href="/api/clusters?search={query}"/> <link rel="datacenters" href="/api/datacenters"/> <link rel="datacenters/search" href="/api/datacenters?search={query}"/> <link rel="events" href="/api/events"/> <link rel="events/search" href="/api/events?search={query}"/> <link rel="hosts" href="/api/hosts"/> <link rel="hosts/search" href="/api/hosts?search={query}"/> <link rel="networks" href="/api/networks"/> <link rel="roles" href="/api/roles"/> <link rel="storagedomains" href="/api/storagedomains"/> <link rel="storagedomains/search" href="/api/storagedomains?search={query}"/> <link rel="tags" href="/api/tags"/> <link rel="templates" href="/api/templates"/> <link rel="templates/search" href="/api/templates?search={query}"/> <link rel="users" href="/api/users"/> <link rel="groups" href="/api/groups"/> <link rel="domains" href="/api/domains"/> <link rel="vmpools" href="/api/vmpools"/> <link rel="vmpools/search" href="/api/vmpools?search={query}"/> <link rel="vms" href="/api/vms"/> <link rel="vms/search" href="/api/vms?search={query}"/> <product_info> <name>oVirt Engine</name> <vendor>ovirt.org</vendor> <version> <build>4</build> <full_version>4.0.4</full_version> <major>4</major> <minor>0</minor> <revision>0</revision> </version> </product_info> <special_objects> <blank_template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/> <root_tag href="/ovirt-engine/api/tags/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/> </special_objects> <summary> <hosts> <active>0</active> <total>0</total> </hosts> <storage_domains> <active>0</active> <total>1</total> </storage_domains> <users> <active>1</active> <total>1</total> </users> <vms> <active>0</active> <total>0</total> </vms> </summary> <time>2016-09-14T12:00:48.132+02:00</time> </api> The entry point provides a user with links to the collections in a virtualization environment. The rel attribute of each collection link provides a reference point for each link. The entry point also contains other data such as product_info , special_objects and summary . Table 6.650. Parameters summary Name Type Direction Summary api Api Out follow String In Indicates which inner links should be followed . 6.213.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.213.2. reloadconfigurations POST Table 6.651. Parameters summary Name Type Direction Summary async Boolean In Indicates if the reload should be performed asynchronously. 6.214. SystemOption A service that provides values of specific configuration option of the system. Table 6.652. Methods summary Name Summary get Get the values of specific configuration option. 6.214.1. get GET Get the values of specific configuration option. For example to retrieve the values of configuration option MigrationPoliciesSupported send a request like this: The response to that request will be the following: <system_option href="/ovirt-engine/api/options/MigrationPoliciesSupported" id="MigrationPoliciesSupported"> <name>MigrationPoliciesSupported</name> <values> <system_option_value> <value>true</value> <version>4.0</version> </system_option_value> <system_option_value> <value>true</value> <version>4.1</version> </system_option_value> <system_option_value> <value>true</value> <version>4.2</version> </system_option_value> <system_option_value> <value>false</value> <version>3.6</version> </system_option_value> </values> </system_option> Note The appropriate permissions are required to query configuration options. Some options can be queried only by users with administrator permissions. Important There is NO backward compatibility and no guarantee about the names or values of the options. Options may be removed and their meaning can be changed at any point. We strongly discourage the use of this service for applications other than the ones that are released simultaneously with the engine. Usage by other applications is not supported. Therefore there will be no documentation listing accessible configuration options. Table 6.653. Parameters summary Name Type Direction Summary option SystemOption Out The returned configuration option of the system. version String In Optional version parameter that specifies that only particular version of the configuration option should be returned. 6.214.1.1. version Optional version parameter that specifies that only particular version of the configuration option should be returned. If this parameter isn't used then all the versions will be returned. For example, to get the value of the MigrationPoliciesSupported option but only for version 4.2 send a request like this: The response to that request will be like this: <system_option href="/ovirt-engine/api/options/MigrationPoliciesSupported" id="MigrationPoliciesSupported"> <name>MigrationPoliciesSupported</name> <values> <system_option_value> <value>true</value> <version>4.2</version> </system_option_value> </values> </system_option> 6.215. SystemOptions Service that provides values of configuration options of the system. 6.216. SystemPermissions This service doesn't add any new methods, it is just a placeholder for the annotation that specifies the path of the resource that manages the permissions assigned to the system object. Table 6.654. 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.216.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: 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: 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: With a request body like this: <permission> <role> <name>UserRole</name> </role> <group id="789"/> </permission> Table 6.655. Parameters summary Name Type Direction Summary permission Permission In/Out The permission. 6.216.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: <permissions> <permission id="456"> <cluster id="123"/> <role id="789"/> <user id="451"/> </permission> <permission id="654"> <cluster id="123"/> <role id="789"/> <group id="127"/> </permission> </permissions> The order of the returned permissions isn't guaranteed. Table 6.656. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . permissions Permission[] Out The list of permissions. 6.216.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.217. Tag A service to manage a specific tag in the system. Table 6.657. Methods summary Name Summary get Gets the information about the tag. remove Removes the tag from the system. update Updates the tag entity. 6.217.1. get GET Gets the information about the tag. For example to retrieve the information about the tag with the id 123 send a request like this: <tag href="/ovirt-engine/api/tags/123" id="123"> <name>root</name> <description>root</description> </tag> Table 6.658. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . tag Tag Out The tag. 6.217.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.217.2. remove DELETE Removes the tag from the system. For example to remove the tag with id 123 send a request like this: Table 6.659. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.217.3. update PUT Updates the tag entity. For example to update parent tag to tag with id 456 of the tag with id 123 send a request like this: With request body like: <tag> <parent id="456"/> </tag> You may also specify a tag name instead of id. For example to update parent tag to tag with name mytag of the tag with id 123 send a request like this: <tag> <parent> <name>mytag</name> </parent> </tag> Table 6.660. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. tag Tag In/Out The updated tag. 6.218. Tags Represents a service to manage collection of the tags in the system. Table 6.661. Methods summary Name Summary add Add a new tag to the system. list List the tags in the system. 6.218.1. add POST Add a new tag to the system. For example, to add new tag with name mytag to the system send a request like this: With a request body like this: <tag> <name>mytag</name> </tag> Note The root tag is a special pseudo-tag assumed as the default parent tag if no parent tag is specified. The root tag cannot be deleted nor assigned a parent tag. To create new tag with specific parent tag send a request body like this: <tag> <name>mytag</name> <parent> <name>myparenttag</name> </parent> </tag> Table 6.662. Parameters summary Name Type Direction Summary tag Tag In/Out The added tag. 6.218.2. list GET List the tags in the system. For example to list the full hierarchy of the tags in the system send a request like this: <tags> <tag href="/ovirt-engine/api/tags/222" id="222"> <name>root2</name> <description>root2</description> <parent href="/ovirt-engine/api/tags/111" id="111"/> </tag> <tag href="/ovirt-engine/api/tags/333" id="333"> <name>root3</name> <description>root3</description> <parent href="/ovirt-engine/api/tags/222" id="222"/> </tag> <tag href="/ovirt-engine/api/tags/111" id="111"> <name>root</name> <description>root</description> </tag> </tags> In the XML output you can see the following hierarchy of the tags: The order of the returned list of tags isn't guaranteed. Table 6.663. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of tags to return. tags Tag[] Out List of all tags in the system. 6.218.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.218.2.2. max Sets the maximum number of tags to return. If not specified all the tags are returned. 6.219. Template Manages the virtual machine template and template versions. Table 6.664. Methods summary Name Summary export Exports a template to the data center export domain. get Returns the information about this template or template version. remove Removes a virtual machine template. update Updates the template. 6.219.1. export POST Exports a template to the data center export domain. For example, send the following request: With a request body like this: <action> <storage_domain id="456"/> <exclusive>true<exclusive/> </action> Table 6.665. Parameters summary Name Type Direction Summary exclusive Boolean In Indicates if the existing templates with the same name should be overwritten. storage_domain StorageDomain In Specifies the destination export storage domain. 6.219.1.1. exclusive Indicates if the existing templates with the same name should be overwritten. The export action reports a failed action if a template of the same name exists in the destination domain. Set this parameter to true to change this behavior and overwrite any existing template. 6.219.2. get GET Returns the information about this template or template version. Table 6.666. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . template Template Out The information about the template or template version. 6.219.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.219.3. remove DELETE Removes a virtual machine template. Table 6.667. Parameters summary Name Type Direction Summary async Boolean In Indicates if the removal should be performed asynchronously. 6.219.4. update PUT Updates the template. The name , description , type , memory , cpu , topology , os , high_availability , display , stateless , usb , and timezone elements can be updated after a template has been created. For example, to update a template so that it has 1 GiB of memory send a request like this: With the following request body: <template> <memory>1073741824</memory> </template> The version_name name attribute is the only one that can be updated within the version attribute used for template versions: <template> <version> <version_name>mytemplate_2</version_name> </version> </template> Table 6.668. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. template Template In/Out 6.220. TemplateCdrom A service managing a CD-ROM device on templates. Table 6.669. Methods summary Name Summary get Returns the information about this CD-ROM device. 6.220.1. get GET Returns the information about this CD-ROM device. For example, to get information about the CD-ROM device of template 123 send a request like: Table 6.670. Parameters summary Name Type Direction Summary cdrom Cdrom Out The information about the CD-ROM device. follow String In Indicates which inner links should be followed . 6.220.1.1. cdrom The information about the CD-ROM device. The information consists of cdrom attribute containing reference to the CD-ROM device, the template, and optionally the inserted disk. If there is a disk inserted then the file attribute will contain a reference to the ISO image: <cdrom href="..." id="00000000-0000-0000-0000-000000000000"> <template href="/ovirt-engine/api/templates/123" id="123"/> <file id="mycd.iso"/> </cdrom> If there is no disk inserted then the file attribute won't be reported: <cdrom href="..." id="00000000-0000-0000-0000-000000000000"> <template href="/ovirt-engine/api/templates/123" id="123"/> </cdrom> 6.220.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.221. TemplateCdroms Lists the CD-ROM devices of a template. Table 6.671. Methods summary Name Summary list Returns the list of CD-ROM devices of the template. 6.221.1. list GET Returns the list of CD-ROM devices of the template. The order of the returned list of CD-ROM devices isn't guaranteed. Table 6.672. Parameters summary Name Type Direction Summary cdroms Cdrom[] Out The list of CD-ROM devices of the template. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of CD-ROMs to return. 6.221.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.221.1.2. max Sets the maximum number of CD-ROMs to return. If not specified all the CD-ROMs are returned. 6.222. TemplateDisk Table 6.673. Methods summary Name Summary copy Copy the specified disk attached to the template to a specific storage domain. export get remove 6.222.1. copy POST Copy the specified disk attached to the template to a specific storage domain. Table 6.674. Parameters summary Name Type Direction Summary async Boolean In Indicates if the copy should be performed asynchronously. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. storage_domain StorageDomain In 6.222.2. export POST Table 6.675. 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.222.3. get GET Table 6.676. Parameters summary Name Type Direction Summary disk Disk Out follow String In Indicates which inner links should be followed . 6.222.3.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.222.4. remove DELETE Table 6.677. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.223. TemplateDiskAttachment This service manages the attachment of a disk to a template. Table 6.678. Methods summary Name Summary get Returns the details of the attachment. remove Removes the disk from the template. 6.223.1. get GET Returns the details of the attachment. Table 6.679. Parameters summary Name Type Direction Summary attachment DiskAttachment Out follow String In Indicates which inner links should be followed . 6.223.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.223.2. remove DELETE Removes the disk from the template. The disk will only be removed if there are other existing copies of the disk on other storage domains. A storage domain has to be specified to determine which of the copies should be removed (template disks can have copies on multiple storage domains). Table 6.680. Parameters summary Name Type Direction Summary force Boolean In storage_domain String In Specifies the identifier of the storage domain the image to be removed resides on. 6.224. TemplateDiskAttachments This service manages the set of disks attached to a template. Each attached disk is represented by a DiskAttachment . Table 6.681. Methods summary Name Summary list List the disks that are attached to the template. 6.224.1. list GET List the disks that are attached to the template. The order of the returned list of attachments isn't guaranteed. Table 6.682. Parameters summary Name Type Direction Summary attachments DiskAttachment[] Out follow String In Indicates which inner links should be followed . 6.224.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.225. TemplateDisks Table 6.683. Methods summary Name Summary list Returns the list of disks of the template. 6.225.1. list GET Returns the list of disks of the template. The order of the returned list of disks isn't guaranteed. Table 6.684. Parameters summary Name Type Direction Summary disks Disk[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of disks to return. 6.225.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.225.1.2. max Sets the maximum number of disks to return. If not specified all the disks are returned. 6.226. TemplateGraphicsConsole Table 6.685. Methods summary Name Summary get Gets graphics console configuration of the template. remove Remove the graphics console from the template. 6.226.1. get GET Gets graphics console configuration of the template. Table 6.686. Parameters summary Name Type Direction Summary console GraphicsConsole Out The information about the graphics console of the template. follow String In Indicates which inner links should be followed . 6.226.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.226.2. remove DELETE Remove the graphics console from the template. Table 6.687. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.227. TemplateGraphicsConsoles Table 6.688. Methods summary Name Summary add Add new graphics console to the template. list Lists all the configured graphics consoles of the template. 6.227.1. add POST Add new graphics console to the template. Table 6.689. Parameters summary Name Type Direction Summary console GraphicsConsole In/Out 6.227.2. list GET Lists all the configured graphics consoles of the template. The order of the returned list of graphics consoles isn't guaranteed. Table 6.690. Parameters summary Name Type Direction Summary consoles GraphicsConsole[] Out The list of graphics consoles of the template. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of consoles to return. 6.227.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.227.2.2. max Sets the maximum number of consoles to return. If not specified all the consoles are returned. 6.228. TemplateNic Table 6.691. Methods summary Name Summary get remove update Update the specified network interface card attached to the template. 6.228.1. get GET Table 6.692. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . nic Nic Out 6.228.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.228.2. remove DELETE Table 6.693. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.228.3. update PUT Update the specified network interface card attached to the template. Table 6.694. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. nic Nic In/Out 6.229. TemplateNics Table 6.695. Methods summary Name Summary add Add a new network interface card to the template. list Returns the list of NICs of the template. 6.229.1. add POST Add a new network interface card to the template. Table 6.696. Parameters summary Name Type Direction Summary nic Nic In/Out 6.229.2. list GET Returns the list of NICs of the template. The order of the returned list of NICs isn't guaranteed. Table 6.697. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of NICs to return. nics Nic[] Out 6.229.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.229.2.2. max Sets the maximum number of NICs to return. If not specified all the NICs are returned. 6.230. TemplateWatchdog Table 6.698. Methods summary Name Summary get remove update Update the watchdog for the template identified by the given id. 6.230.1. get GET Table 6.699. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . watchdog Watchdog Out 6.230.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.230.2. remove DELETE Table 6.700. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.230.3. update PUT Update the watchdog for the template identified by the given id. Table 6.701. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. watchdog Watchdog In/Out 6.231. TemplateWatchdogs Table 6.702. Methods summary Name Summary add Add a watchdog to the template identified by the given id. list Returns the list of watchdogs. 6.231.1. add POST Add a watchdog to the template identified by the given id. Table 6.703. Parameters summary Name Type Direction Summary watchdog Watchdog In/Out 6.231.2. list GET Returns the list of watchdogs. The order of the returned list of watchdogs isn't guaranteed. Table 6.704. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of watchdogs to return. watchdogs Watchdog[] Out 6.231.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.231.2.2. max Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned. 6.232. Templates This service manages the virtual machine templates available in the system. Table 6.705. Methods summary Name Summary add Creates a new template. list Returns the list of virtual machine templates. 6.232.1. add POST Creates a new template. This requires the name and vm elements. To identify the virtual machine use the vm.id or vm.name attributes. For example, to create a template from a virtual machine with the identifier 123 send a request like this: With a request body like this: <template> <name>mytemplate</name> <vm id="123"/> </template> The disks of the template can be customized, making some of their characteristics different from the disks of the original virtual machine. To do so use the vm.disk_attachments attribute, specifying the identifier of the disk of the original virtual machine and the characteristics that you want to change. For example, if the original virtual machine has a disk with the identifier 456 , and, for that disk, you want to change the name to mydisk the format to Copy On Write and make it sparse , send a request body like this: <template> <name>mytemplate</name> <vm id="123"> <disk_attachments> <disk_attachment> <disk id="456"> <name>mydisk</name> <format>cow</format> <sparse>true</sparse> </disk> </disk_attachment> </disk_attachments> </vm> </template> The template can be created as a sub-version of an existing template. This requires the name and vm attributes for the new template, and the base_template and version_name attributes for the new template version. The base_template and version_name attributes must be specified within a version section enclosed in the template section. Identify the virtual machine with the id or name attributes. <template> <name>mytemplate</name> <vm id="123"/> <version> <base_template id="456"/> <version_name>mytemplate_001</version_name> </version> </template> The destination storage domain of the template can be customized, in one of two ways: Globally, at the request level. The request must list the desired disk attachments to be created on the storage domain. If the disk attachments are not listed, the global storage domain parameter will be ignored. <template> <name>mytemplate</name> <storage_domain id="123"/> <vm id="456"> <disk_attachments> <disk_attachment> <disk id="789"> <format>cow</format> <sparse>true</sparse> </disk> </disk_attachment> </disk_attachments> </vm> </template> Per each disk attachment. Specify the desired storage domain for each disk attachment. Specifying the global storage definition will override the storage domain per disk attachment specification. <template> <name>mytemplate</name> <vm id="123"> <disk_attachments> <disk_attachment> <disk id="456"> <format>cow</format> <sparse>true</sparse> <storage_domains> <storage_domain id="789"/> </storage_domains> </disk> </disk_attachment> </disk_attachments> </vm> </template> Table 6.706. Parameters summary Name Type Direction Summary clone_permissions Boolean In Specifies if the permissions of the virtual machine should be copied to the template. seal Boolean In Seals the template. template Template In/Out The information about the template or template version. 6.232.1.1. clone_permissions Specifies if the permissions of the virtual machine should be copied to the template. If this optional parameter is provided, and its value is true , then the permissions of the virtual machine (only the direct ones, not the inherited ones) will be copied to the created template. For example, to create a template from the myvm virtual machine copying its permissions, send a request like this: With a request body like this: <template> <name>mytemplate<name> <vm> <name>myvm<name> </vm> </template> 6.232.1.2. seal Seals the template. If this optional parameter is provided and its value is true , then the template is sealed after creation. Sealing erases all host-specific configuration from the filesystem: SSH keys, UDEV rules, MAC addresses, system ID, hostname, and so on, thus making it easier to use the template to create multiple virtual machines without manual intervention. Currently, sealing is supported only for Linux operating systems. 6.232.2. list GET Returns the list of virtual machine templates. For example: Will return the list of virtual machines and virtual machine templates. The order of the returned list of templates is not guaranteed. Table 6.707. 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. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of templates to return. search String In A query string used to restrict the returned templates. templates Template[] Out The list of virtual machine templates. 6.232.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.232.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.232.2.3. max Sets the maximum number of templates to return. If not specified, all the templates are returned. 6.233. UnmanagedNetwork Table 6.708. Methods summary Name Summary get remove 6.233.1. get GET Table 6.709. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . network UnmanagedNetwork Out 6.233.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.233.2. remove DELETE Table 6.710. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.234. UnmanagedNetworks Table 6.711. Methods summary Name Summary list Returns the list of unmanaged networks of the host. 6.234.1. list GET Returns the list of unmanaged networks of the host. The order of the returned list of networks isn't guaranteed. Table 6.712. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of networks to return. networks UnmanagedNetwork[] Out 6.234.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.234.1.2. max Sets the maximum number of networks to return. If not specified all the networks are returned. 6.235. User A service to manage a user in the system. Use this service to either get users details or remove users. In order to add new users please use Section 6.236, "Users" . Table 6.713. Methods summary Name Summary get Gets the system user information. remove Removes the system user. 6.235.1. get GET Gets the system user information. Usage: Will return the user information: <user href="/ovirt-engine/api/users/1234" id="1234"> <name>admin</name> <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/> <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/> <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/> <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/> <department></department> <domain_entry_id>23456</domain_entry_id> <email>user1@domain.com</email> <last_name>Lastname</last_name> <namespace>*</namespace> <principal>user1</principal> <user_name>user1@domain-authz</user_name> <domain href="/ovirt-engine/api/domains/45678" id="45678"> <name>domain-authz</name> </domain> </user> Table 6.714. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . user User Out The system user. 6.235.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.235.2. remove DELETE Removes the system user. Usage: Table 6.715. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.236. Users A service to manage the users in the system. Table 6.716. Methods summary Name Summary add Add user from a directory service. list List all the users in the system. 6.236.1. add POST Add user from a directory service. For example, to add the myuser user from the myextension-authz authorization provider send a request like this: With a request body like this: <user> <user_name>myuser@myextension-authz</user_name> <domain> <name>myextension-authz</name> </domain> </user> In case you are working with Active Directory you have to pass user principal name (UPN) as username , followed by authorization provider name. Due to bug 1147900 you need to provide also principal parameter set to UPN of the user. For example, to add the user with UPN myuser@mysubdomain.mydomain.com from the myextension-authz authorization provider send a request body like this: <user> <principal>myuser@mysubdomain.mydomain.com</principal> <user_name>myuser@mysubdomain.mydomain.com@myextension-authz</user_name> <domain> <name>myextension-authz</name> </domain> </user> Table 6.717. Parameters summary Name Type Direction Summary user User In/Out 6.236.2. list GET List all the users in the system. Usage: Will return the list of users: <users> <user href="/ovirt-engine/api/users/1234" id="1234"> <name>admin</name> <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/> <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/> <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/> <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/> <domain_entry_id>23456</domain_entry_id> <namespace>*</namespace> <principal>user1</principal> <user_name>user1@domain-authz</user_name> <domain href="/ovirt-engine/api/domains/45678" id="45678"> <name>domain-authz</name> </domain> </user> </users> The order of the returned list of users isn't guaranteed. Table 6.718. Parameters summary Name Type Direction Summary case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of users to return. search String In A query string used to restrict the returned users. users User[] Out The list of users. 6.236.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.236.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.236.2.3. max Sets the maximum number of users to return. If not specified all the users are returned. 6.237. VirtualFunctionAllowedNetwork Table 6.719. Methods summary Name Summary get remove 6.237.1. get GET Table 6.720. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . network Network Out 6.237.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.237.2. remove DELETE Table 6.721. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.238. VirtualFunctionAllowedNetworks Table 6.722. Methods summary Name Summary add list Returns the list of networks. 6.238.1. add POST Table 6.723. Parameters summary Name Type Direction Summary network Network In/Out 6.238.2. list GET Returns the list of networks. The order of the returned list of networks isn't guaranteed. Table 6.724. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of networks to return. networks Network[] Out 6.238.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.238.2.2. max Sets the maximum number of networks to return. If not specified all the networks are returned. 6.239. Vm Table 6.725. Methods summary Name Summary cancelmigration This operation stops any migration of a virtual machine to another physical host. clone commitsnapshot Permanently restores the virtual machine to the state of the previewed snapshot. detach Detaches a virtual machine from a pool. export Exports the virtual machine. freezefilesystems Freezes virtual machine file systems. get Retrieves the description of the virtual machine. logon Initiates the automatic user logon to access a virtual machine from an external console. maintenance Sets the global maintenance mode on the hosted engine virtual machine. migrate Migrates a virtual machine to another physical host. previewsnapshot Temporarily restores the virtual machine to the state of a snapshot. reboot Sends a reboot request to a virtual machine. remove Removes the virtual machine, including the virtual disks attached to it. reordermacaddresses shutdown This operation sends a shutdown request to a virtual machine. start Starts the virtual machine. stop This operation forces a virtual machine to power-off. suspend This operation saves the virtual machine state to disk and stops it. thawfilesystems Thaws virtual machine file systems. ticket Generates a time-sensitive authentication token for accessing a virtual machine's display. undosnapshot Restores the virtual machine to the state it had before previewing the snapshot. update Update the virtual machine in the system for the given virtual machine id. 6.239.1. cancelmigration POST This operation stops any migration of a virtual machine to another physical host. The cancel migration action does not take any action specific parameters; therefore, the request body should contain an empty action : <action/> Table 6.726. Parameters summary Name Type Direction Summary async Boolean In Indicates if the migration should cancelled asynchronously. 6.239.2. clone POST Table 6.727. Parameters summary Name Type Direction Summary async Boolean In Indicates if the clone should be performed asynchronously. vm Vm In 6.239.3. commitsnapshot POST Permanently restores the virtual machine to the state of the previewed snapshot. See the preview_snapshot operation for details. Table 6.728. Parameters summary Name Type Direction Summary async Boolean In Indicates if the snapshots should be committed asynchronously. 6.239.4. detach POST Detaches a virtual machine from a pool. The detach action does not take any action specific parameters; therefore, the request body should contain an empty action : <action/> Table 6.729. Parameters summary Name Type Direction Summary async Boolean In Indicates if the detach action should be performed asynchronously. 6.239.5. export POST Exports the virtual machine. A virtual machine can be exported to an export domain. For example, to export virtual machine 123 to the export domain myexport : With a request body like this: <action> <storage_domain> <name>myexport</name> </storage_domain> <exclusive>true</exclusive> <discard_snapshots>true</discard_snapshots> </action> Since version 4.2 of the engine it is also possible to export a virtual machine as a virtual appliance (OVA). For example, to export virtual machine 123 as an OVA file named myvm.ova that is placed in the directory /home/ovirt/ on host myhost : With a request body like this: <action> <host> <name>myhost</name> </host> <directory>/home/ovirt</directory> <filename>myvm.ova</filename> </action> Note Confirm that the export operation has completed before attempting any actions on the export domain. Table 6.730. Parameters summary Name Type Direction Summary async Boolean In Indicates if the export should be performed asynchronously. discard_snapshots Boolean In Use the discard_snapshots parameter when the virtual machine should be exported with all of its snapshots collapsed. exclusive Boolean In Use the exclusive parameter when the virtual machine should be exported even if another copy of it already exists in the export domain (override). storage_domain StorageDomain In The (export) storage domain to export the virtual machine to. 6.239.6. freezefilesystems POST Freezes virtual machine file systems. This operation freezes a virtual machine's file systems using the QEMU guest agent when taking a live snapshot of a running virtual machine. Normally, this is done automatically by Manager, but this must be executed manually with the API for virtual machines using OpenStack Volume (Cinder) disks. Example: <action/> Table 6.731. Parameters summary Name Type Direction Summary async Boolean In Indicates if the freeze should be performed asynchronously. 6.239.7. get GET Retrieves the description of the virtual machine. Table 6.732. Parameters summary Name Type Direction Summary all_content Boolean In Indicates if all of the attributes of the virtual machine should be included in the response. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . next_run Boolean In Indicates if the returned result describes the virtual machine as it is currently running or if describes the virtual machine with the modifications that have already been performed but that will only come into effect when the virtual machine is restarted. vm Vm Out Description of the virtual machine. 6.239.7.1. all_content Indicates if all of the attributes of the virtual machine should be included in the response. By default the following attributes are excluded: console initialization.configuration.data - The OVF document describing the virtual machine. rng_source soundcard virtio_scsi For example, to retrieve the complete representation of the virtual machine '123': Note These attributes are not included by default as they reduce performance. These attributes are seldom used and require additional queries to the database. Only use this parameter when required as it will reduce performance. 6.239.7.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.239.7.3. next_run Indicates if the returned result describes the virtual machine as it is currently running or if describes the virtual machine with the modifications that have already been performed but that will only come into effect when the virtual machine is restarted. By default the value is false . If the parameter is included in the request, but without a value, it is assumed that the value is true . The the following request: Is equivalent to using the value true : 6.239.8. logon POST Initiates the automatic user logon to access a virtual machine from an external console. This action requires the ovirt-guest-agent-gdm-plugin and the ovirt-guest-agent-pam-module packages to be installed and the ovirt-guest-agent service to be running on the virtual machine. Users require the appropriate user permissions for the virtual machine in order to access the virtual machine from an external console. For example: Request body: <action/> Table 6.733. Parameters summary Name Type Direction Summary async Boolean In Indicates if the logon should be performed asynchronously. 6.239.9. maintenance POST Sets the global maintenance mode on the hosted engine virtual machine. This action has no effect on other virtual machines. Example: <action> <maintenance_enabled>true<maintenance_enabled/> </action> Table 6.734. Parameters summary Name Type Direction Summary async Boolean In Indicates if the global maintenance action should be performed asynchronously. maintenance_enabled Boolean In Indicates if global maintenance should be enabled or disabled. 6.239.10. migrate POST Migrates a virtual machine to another physical host. Example: To specify a specific host to migrate the virtual machine to: <action> <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/> </action> Table 6.735. Parameters summary Name Type Direction Summary async Boolean In Indicates if the migration should be performed asynchronously. cluster Cluster In Specifies the cluster the virtual machine should migrate to. force Boolean In Specifies that the virtual machine should migrate even if the virtual machine is defined as non-migratable. host Host In Specifies a specific host that the virtual machine should migrate to. 6.239.10.1. cluster Specifies the cluster the virtual machine should migrate to. This is an optional parameter. By default, the virtual machine is migrated to another host within the same cluster. Warning Live migration to another cluster is not supported. Strongly consider the target cluster's hardware architecture and network architecture before attempting a migration. 6.239.10.2. force Specifies that the virtual machine should migrate even if the virtual machine is defined as non-migratable. This is an optional parameter. By default, it is set to false . 6.239.10.3. host Specifies a specific host that the virtual machine should migrate to. This is an optional parameter. By default, the Red Hat Virtualization Manager automatically selects a default host for migration within the same cluster. If an API user requires a specific host, the user can specify the host with either an id or name parameter. 6.239.11. previewsnapshot POST Temporarily restores the virtual machine to the state of a snapshot. The snapshot is indicated with the snapshot.id parameter. It is restored temporarily, so that the content can be inspected. Once that inspection is finished, the state of the virtual machine can be made permanent, using the commit_snapshot method, or discarded using the undo_snapshot method. Table 6.736. Parameters summary Name Type Direction Summary async Boolean In Indicates if the preview should be performed asynchronously. disks Disk[] In Specify the disks included in the snapshot's preview. lease StorageDomainLease In Specify the lease storage domain ID to use in the preview of the snapshot. restore_memory Boolean In snapshot Snapshot In vm Vm In 6.239.11.1. disks Specify the disks included in the snapshot's preview. For each disk parameter, it is also required to specify its image_id . For example, to preview a snapshot with identifier 456 which includes a disk with identifier 111 and its image_id as 222 , send a request like this: Request body: <action> <disks> <disk id="111"> <image_id>222</image_id> </disk> </disks> <snapshot id="456"/> </action> 6.239.11.2. lease Specify the lease storage domain ID to use in the preview of the snapshot. If lease parameter is not passed, then the previewed snapshot lease storage domain will be used. If lease parameter is passed with empty storage domain parameter, then no lease will be used for the snapshot preview. If lease parameter is passed with storage domain parameter then the storage domain ID can be only one of the leases domain IDs that belongs to one of the virtual machine snapshots. This is an optional parameter, set by default to null 6.239.12. reboot POST Sends a reboot request to a virtual machine. For example: The reboot action does not take any action specific parameters; therefore, the request body should contain an empty action : <action/> Table 6.737. Parameters summary Name Type Direction Summary async Boolean In Indicates if the reboot should be performed asynchronously. 6.239.13. remove DELETE Removes the virtual machine, including the virtual disks attached to it. For example, to remove the virtual machine with identifier 123 : Table 6.738. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. detach_only Boolean In Indicates if the attached virtual disks should be detached first and preserved instead of being removed. force Boolean In Indicates if the virtual machine should be forcibly removed. 6.239.13.1. force Indicates if the virtual machine should be forcibly removed. Locked virtual machines and virtual machines with locked disk images cannot be removed without this flag set to true. 6.239.14. reordermacaddresses POST Table 6.739. Parameters summary Name Type Direction Summary async Boolean In Indicates if the action should be performed asynchronously. 6.239.15. shutdown POST This operation sends a shutdown request to a virtual machine. For example: The shutdown action does not take any action specific parameters; therefore, the request body should contain an empty action : <action/> Table 6.740. Parameters summary Name Type Direction Summary async Boolean In Indicates if the shutdown should be performed asynchronously. 6.239.16. start POST Starts the virtual machine. If the virtual environment is complete and the virtual machine contains all necessary components to function, it can be started. This example starts the virtual machine: With a request body: <action/> Table 6.741. Parameters summary Name Type Direction Summary async Boolean In Indicates if the start action should be performed asynchronously. authorized_key AuthorizedKey In filter Boolean In Indicates if the results should be filtered according to the permissions of the user. pause Boolean In If set to true , start the virtual machine in paused mode. use_cloud_init Boolean In If set to true , the initialization type is set to cloud-init . use_sysprep Boolean In If set to true , the initialization type is set to Sysprep . vm Vm In The definition of the virtual machine for this specific run. volatile Boolean In Indicates that this run configuration will be discarded even in the case of guest-initiated reboot. 6.239.16.1. pause If set to true , start the virtual machine in paused mode. The default is false . 6.239.16.2. use_cloud_init If set to true , the initialization type is set to cloud-init . The default value is false . See this for details. 6.239.16.3. use_sysprep If set to true , the initialization type is set to Sysprep . The default value is false . See this for details. 6.239.16.4. vm The definition of the virtual machine for this specific run. For example: <action> <vm> <os> <boot> <devices> <device>cdrom</device> </devices> </boot> </os> </vm> </action> This will set the boot device to the CDROM only for this specific start. After the virtual machine is powered off, this definition will be reverted. 6.239.16.5. volatile Indicates that this run configuration will be discarded even in the case of guest-initiated reboot. The default value is false . 6.239.17. stop POST This operation forces a virtual machine to power-off. For example: The stop action does not take any action specific parameters; therefore, the request body should contain an empty action : <action/> Table 6.742. Parameters summary Name Type Direction Summary async Boolean In Indicates if the stop action should be performed asynchronously. 6.239.18. suspend POST This operation saves the virtual machine state to disk and stops it. Start a suspended virtual machine and restore the virtual machine state with the start action. For example: The suspend action does not take any action specific parameters; therefore, the request body should contain an empty action : <action/> Table 6.743. Parameters summary Name Type Direction Summary async Boolean In Indicates if the suspend action should be performed asynchronously. 6.239.19. thawfilesystems POST Thaws virtual machine file systems. This operation thaws a virtual machine's file systems using the QEMU guest agent when taking a live snapshot of a running virtual machine. Normally, this is done automatically by Manager, but this must be executed manually with the API for virtual machines using OpenStack Volume (Cinder) disks. Example: <action/> Table 6.744. Parameters summary Name Type Direction Summary async Boolean In Indicates if the thaw file systems action should be performed asynchronously. 6.239.20. ticket POST Generates a time-sensitive authentication token for accessing a virtual machine's display. For example: The client-provided action optionally includes a desired ticket value and/or an expiry time in seconds. The response specifies the actual ticket value and expiry used. <action> <ticket> <value>abcd12345</value> <expiry>120</expiry> </ticket> </action> Important If the virtual machine is configured to support only one graphics protocol then the generated authentication token will be valid for that protocol. But if the virtual machine is configured to support multiple protocols, VNC and SPICE, then the authentication token will only be valid for the SPICE protocol. In order to obtain an authentication token for a specific protocol, for example for VNC, use the ticket method of the service , which manages the graphics consoles of the virtual machine, by sending a request: Table 6.745. Parameters summary Name Type Direction Summary async Boolean In Indicates if the generation of the ticket should be performed asynchronously. ticket Ticket In/Out 6.239.21. undosnapshot POST Restores the virtual machine to the state it had before previewing the snapshot. See the preview_snapshot operation for details. Table 6.746. Parameters summary Name Type Direction Summary async Boolean In Indicates if the undo snapshot action should be performed asynchronously. 6.239.22. update PUT Update the virtual machine in the system for the given virtual machine id. Table 6.747. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. next_run Boolean In Indicates if the update should be applied to the virtual machine immediately or if it should be applied only when the virtual machine is restarted. vm Vm In/Out 6.239.22.1. next_run Indicates if the update should be applied to the virtual machine immediately or if it should be applied only when the virtual machine is restarted. The default value is false , so by default changes are applied immediately. 6.240. VmApplication A service that provides information about an application installed in a virtual machine. Table 6.748. Methods summary Name Summary get Returns the information about the application. 6.240.1. get GET Returns the information about the application. Table 6.749. Parameters summary Name Type Direction Summary application Application Out The information about the application. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . 6.240.1.1. application The information about the application. The information consists of name attribute containing the name of the application (which is an arbitrary string that may also contain additional information such as version) and vm attribute identifying the virtual machine. For example, a request like this: May return information like this: <application href="/ovirt-engine/api/vms/123/applications/789" id="789"> <name>ovirt-guest-agent-common-1.0.12-3.el7</name> <vm href="/ovirt-engine/api/vms/123" id="123"/> </application> 6.240.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.241. VmApplications A service that provides information about applications installed in a virtual machine. Table 6.750. Methods summary Name Summary list Returns a list of applications installed in the virtual machine. 6.241.1. list GET Returns a list of applications installed in the virtual machine. The order of the returned list of applications isn't guaranteed. Table 6.751. Parameters summary Name Type Direction Summary applications Application[] Out A list of applications installed in the virtual machine. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of applications to return. 6.241.1.1. applications A list of applications installed in the virtual machine. For example, a request like this: May return a list like this: <applications> <application href="/ovirt-engine/api/vms/123/applications/456" id="456"> <name>kernel-3.10.0-327.36.1.el7</name> <vm href="/ovirt-engine/api/vms/123" id="123"/> </application> <application href="/ovirt-engine/api/vms/123/applications/789" id="789"> <name>ovirt-guest-agent-common-1.0.12-3.el7</name> <vm href="/ovirt-engine/api/vms/123" id="123"/> </application> </applications> 6.241.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.241.1.3. max Sets the maximum number of applications to return. If not specified all the applications are returned. 6.242. VmCdrom Manages a CDROM device of a virtual machine. Changing and ejecting the disk is done using always the update method, to change the value of the file attribute. Table 6.752. Methods summary Name Summary get Returns the information about this CDROM device. update Updates the information about this CDROM device. 6.242.1. get GET Returns the information about this CDROM device. The information consists of cdrom attribute containing reference to the CDROM device, the virtual machine, and optionally the inserted disk. If there is a disk inserted then the file attribute will contain a reference to the ISO image: <cdrom href="..." id="00000000-0000-0000-0000-000000000000"> <file id="mycd.iso"/> <vm href="/ovirt-engine/api/vms/123" id="123"/> </cdrom> If there is no disk inserted then the file attribute won't be reported: <cdrom href="..." id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> </cdrom> Table 6.753. Parameters summary Name Type Direction Summary cdrom Cdrom Out The information about the CDROM device. current Boolean In Indicates if the operation should return the information for the currently running virtual machine. follow String In Indicates which inner links should be followed . 6.242.1.1. current Indicates if the operation should return the information for the currently running virtual machine. This parameter is optional, and the default value is false . 6.242.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.242.2. update PUT Updates the information about this CDROM device. It allows to change or eject the disk by changing the value of the file attribute. For example, to insert or change the disk send a request like this: The body should contain the new value for the file attribute: <cdrom> <file id="mycd.iso"/> </cdrom> The value of the id attribute, mycd.iso in this example, should correspond to a file available in an attached ISO storage domain. To eject the disk use a file with an empty id : <cdrom> <file id=""/> </cdrom> By default the above operations change permanently the disk that will be visible to the virtual machine after the boot, but they don't have any effect on the currently running virtual machine. If you want to change the disk that is visible to the current running virtual machine, add the current=true parameter. For example, to eject the current disk send a request like this: With a request body like this: <cdrom> <file id=""/> </cdrom> Important The changes made with the current=true parameter are never persisted, so they won't have any effect after the virtual machine is rebooted. Table 6.754. Parameters summary Name Type Direction Summary cdrom Cdrom In/Out The information about the CDROM device. current Boolean In Indicates if the update should apply to the currently running virtual machine, or to the virtual machine after the boot. 6.242.2.1. current Indicates if the update should apply to the currently running virtual machine, or to the virtual machine after the boot. This parameter is optional, and the default value is false , which means that by default the update will have effect only after the boot. 6.243. VmCdroms Manages the CDROM devices of a virtual machine. Currently virtual machines have exactly one CDROM device. No new devices can be added, and the existing one can't be removed, thus there are no add or remove methods. Changing and ejecting CDROM disks is done with the update method of the service that manages the CDROM device. Table 6.755. Methods summary Name Summary add Add a cdrom to a virtual machine identified by the given id. list Returns the list of CDROM devices of the virtual machine. 6.243.1. add POST Add a cdrom to a virtual machine identified by the given id. Table 6.756. Parameters summary Name Type Direction Summary cdrom Cdrom In/Out 6.243.2. list GET Returns the list of CDROM devices of the virtual machine. The order of the returned list of CD-ROM devices isn't guaranteed. Table 6.757. Parameters summary Name Type Direction Summary cdroms Cdrom[] Out The list of CDROM devices of the virtual machine. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of CDROMs to return. 6.243.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.243.2.2. max Sets the maximum number of CDROMs to return. If not specified all the CDROMs are returned. 6.244. VmDisk Table 6.758. Methods summary Name Summary activate deactivate export get move reduce Reduces the size of the disk image. remove Detach the disk from the virtual machine. update 6.244.1. activate POST Table 6.759. Parameters summary Name Type Direction Summary async Boolean In Indicates if the activation should be performed asynchronously. 6.244.2. deactivate POST Table 6.760. Parameters summary Name Type Direction Summary async Boolean In Indicates if the deactivation should be performed asynchronously. 6.244.3. export POST Table 6.761. 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. 6.244.4. get GET Table 6.762. Parameters summary Name Type Direction Summary disk Disk Out follow String In Indicates which inner links should be followed . 6.244.4.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.244.5. move POST Table 6.763. 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. 6.244.6. reduce POST Reduces the size of the disk image. Invokes reduce on the logical volume (i.e. this is only applicable for block storage domains). This is applicable for floating disks and disks attached to non-running virtual machines. There is no need to specify the size as the optimal size is calculated automatically. Table 6.764. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.244.7. remove DELETE Detach the disk from the virtual machine. Note In version 3 of the API this used to also remove the disk completely from the system, but starting with version 4 it doesn't. If you need to remove it completely use the remove method of the top level disk service . Table 6.765. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.244.8. update PUT Table 6.766. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. disk Disk In/Out 6.245. VmDisks Table 6.767. Methods summary Name Summary add list Returns the list of disks of the virtual machine. 6.245.1. add POST Table 6.768. Parameters summary Name Type Direction Summary disk Disk In/Out 6.245.2. list GET Returns the list of disks of the virtual machine. The order of the returned list of disks isn't guaranteed. Table 6.769. Parameters summary Name Type Direction Summary disks Disk[] Out follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of disks to return. 6.245.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.245.2.2. max Sets the maximum number of disks to return. If not specified all the disks are returned. 6.246. VmGraphicsConsole Table 6.770. Methods summary Name Summary get Retrieves the graphics console configuration of the virtual machine. proxyticket remoteviewerconnectionfile Generates the file which is compatible with remote-viewer client. remove Remove the graphics console from the virtual machine. ticket Generates a time-sensitive authentication token for accessing this virtual machine's console. 6.246.1. get GET Retrieves the graphics console configuration of the virtual machine. Important By default, when the current parameter is not specified, the data returned corresponds to the execution of the virtual machine. In the current implementation of the system this means that the address and port attributes will not be populated because the system does not know what address and port will be used for the execution. Since in most cases those attributes are needed, it is strongly advised to aways explicitly include the current parameter with the value true . Table 6.771. Parameters summary Name Type Direction Summary console GraphicsConsole Out The information about the graphics console of the virtual machine. current Boolean In Specifies if the data returned should correspond to the execution of the virtual machine, or to the current execution. follow String In Indicates which inner links should be followed . 6.246.1.1. current Specifies if the data returned should correspond to the execution of the virtual machine, or to the current execution. Important The address and port attributes will not be populated unless the value is true . For example, to get data for the current execution of the virtual machine, including the address and port attributes, send a request like this: The default value is false . 6.246.1.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.246.2. proxyticket POST Table 6.772. Parameters summary Name Type Direction Summary async Boolean In Indicates if the generation of the ticket should be performed asynchronously. proxy_ticket ProxyTicket Out 6.246.3. remoteviewerconnectionfile POST Generates the file which is compatible with remote-viewer client. Use the following request to generate remote viewer connection file of the graphics console. Note that this action generates the file only if virtual machine is running. The remoteviewerconnectionfile action does not take any action specific parameters, so the request body should contain an empty action : <action/> The response contains the file, which can be used with remote-viewer client. <action> <remote_viewer_connection_file> [virt-viewer] type=spice host=192.168.1.101 port=-1 password=123456789 delete-this-file=1 fullscreen=0 toggle-fullscreen=shift+f11 release-cursor=shift+f12 secure-attention=ctrl+alt+end tls-port=5900 enable-smartcard=0 enable-usb-autoshare=0 usb-filter=null tls-ciphers=DEFAULT host-subject=O=local,CN=example.com ca=... </remote_viewer_connection_file> </action> E.g., to fetch the content of remote viewer connection file and save it into temporary file, user can use oVirt Python SDK as follows: # Find the virtual machine: vm = vms_service.list(search='name=myvm')[0] # Locate the service that manages the virtual machine, as that is where # the locators are defined: vm_service = vms_service.vm_service(vm.id) # Find the graphic console of the virtual machine: graphics_consoles_service = vm_service.graphics_consoles_service() graphics_console = graphics_consoles_service.list()[0] # Generate the remote viewer connection file: console_service = graphics_consoles_service.console_service(graphics_console.id) remote_viewer_connection_file = console_service.remote_viewer_connection_file() # Write the content to file "/tmp/remote_viewer_connection_file.vv" path = "/tmp/remote_viewer_connection_file.vv" with open(path, "w") as f: f.write(remote_viewer_connection_file) When you create the remote viewer connection file, then you can connect to virtual machine graphic console, as follows: #!/bin/sh -ex remote-viewer --ovirt-ca-file=/etc/pki/ovirt-engine/ca.pem /tmp/remote_viewer_connection_file.vv Table 6.773. Parameters summary Name Type Direction Summary remote_viewer_connection_file String Out Contains the file which is compatible with remote-viewer client. 6.246.3.1. remote_viewer_connection_file Contains the file which is compatible with remote-viewer client. User can use the content of this attribute to create a file, which can be passed to remote-viewer client to connect to virtual machine graphic console. 6.246.4. remove DELETE Remove the graphics console from the virtual machine. Table 6.774. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.246.5. ticket POST Generates a time-sensitive authentication token for accessing this virtual machine's console. The client-provided action optionally includes a desired ticket value and/or an expiry time in seconds. In any case, the response specifies the actual ticket value and expiry used. <action> <ticket> <value>abcd12345</value> <expiry>120</expiry> </ticket> </action> Table 6.775. Parameters summary Name Type Direction Summary ticket Ticket In/Out The generated ticket that can be used to access this console. 6.247. VmGraphicsConsoles Table 6.776. Methods summary Name Summary add Add new graphics console to the virtual machine. list Lists all the configured graphics consoles of the virtual machine. 6.247.1. add POST Add new graphics console to the virtual machine. Table 6.777. Parameters summary Name Type Direction Summary console GraphicsConsole In/Out 6.247.2. list GET Lists all the configured graphics consoles of the virtual machine. Important By default, when the current parameter is not specified, the data returned corresponds to the execution of the virtual machine. In the current implementation of the system this means that the address and port attributes will not be populated because the system does not know what address and port will be used for the execution. Since in most cases those attributes are needed, it is strongly advised to aways explicitly include the current parameter with the value true . The order of the returned list of graphics consoles is not guaranteed. Table 6.778. Parameters summary Name Type Direction Summary consoles GraphicsConsole[] Out The list of graphics consoles of the virtual machine. current Boolean In Specifies if the data returned should correspond to the execution of the virtual machine, or to the current execution. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of consoles to return. 6.247.2.1. current Specifies if the data returned should correspond to the execution of the virtual machine, or to the current execution. Important The address and port attributes will not be populated unless the value is true . For example, to get data for the current execution of the virtual machine, including the address and port attributes, send a request like this: The default value is false . 6.247.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.247.2.3. max Sets the maximum number of consoles to return. If not specified all the consoles are returned. 6.248. VmHostDevice A service to manage individual host device attached to a virtual machine. Table 6.779. Methods summary Name Summary get Retrieve information about particular host device attached to given virtual machine. remove Remove the attachment of this host device from given virtual machine. 6.248.1. get GET Retrieve information about particular host device attached to given virtual machine. Example: <host_device href="/ovirt-engine/api/hosts/543/devices/456" id="456"> <name>pci_0000_04_00_0</name> <capability>pci</capability> <iommu_group>30</iommu_group> <placeholder>true</placeholder> <product id="0x13ba"> <name>GM107GL [Quadro K2200]</name> </product> <vendor id="0x10de"> <name>NVIDIA Corporation</name> </vendor> <host href="/ovirt-engine/api/hosts/543" id="543"/> <parent_device href="/ovirt-engine/api/hosts/543/devices/456" id="456"> <name>pci_0000_00_03_0</name> </parent_device> <vm href="/ovirt-engine/api/vms/123" id="123"/> </host_device> Table 6.780. Parameters summary Name Type Direction Summary device HostDevice Out Retrieved information about the host device attached to given virtual machine. follow String In Indicates which inner links should be followed . 6.248.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.248.2. remove DELETE Remove the attachment of this host device from given virtual machine. Note In case this device serves as an IOMMU placeholder, it cannot be removed (remove will result only in setting its placeholder flag to true ). Note that all IOMMU placeholder devices will be removed automatically as soon as there will be no more non-placeholder devices (all devices from given IOMMU group are detached). Table 6.781. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.249. VmHostDevices A service to manage host devices attached to a virtual machine. Table 6.782. Methods summary Name Summary add Attach target device to given virtual machine. list List the host devices assigned to given virtual machine. 6.249.1. add POST Attach target device to given virtual machine. Example: With request body of type HostDevice , for example <host_device id="123" /> Note A necessary precondition for a successful host device attachment is that the virtual machine must be pinned to exactly one host. The device ID is then taken relative to this host. Note Attachment of a PCI device that is part of a bigger IOMMU group will result in attachment of the remaining devices from that IOMMU group as "placeholders". These devices are then identified using the placeholder attribute of the HostDevice type set to true . In case you want attach a device that already serves as an IOMMU placeholder, simply issue an explicit Add operation for it, and its placeholder flag will be cleared, and the device will be accessible to the virtual machine. Table 6.783. Parameters summary Name Type Direction Summary device HostDevice In/Out The host device to be attached to given virtual machine. 6.249.2. list GET List the host devices assigned to given virtual machine. The order of the returned list of devices isn't guaranteed. Table 6.784. Parameters summary Name Type Direction Summary device HostDevice[] Out Retrieved list of host devices attached to given virtual machine. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of devices to return. 6.249.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.249.2.2. max Sets the maximum number of devices to return. If not specified all the devices are returned. 6.250. VmNic Table 6.785. Methods summary Name Summary activate deactivate get remove Removes the NIC. update Updates the NIC. 6.250.1. activate POST Table 6.786. Parameters summary Name Type Direction Summary async Boolean In Indicates if the activation should be performed asynchronously. 6.250.2. deactivate POST Table 6.787. Parameters summary Name Type Direction Summary async Boolean In Indicates if the deactivation should be performed asynchronously. 6.250.3. get GET Table 6.788. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . nic Nic Out 6.250.3.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.250.4. remove DELETE Removes the NIC. For example, to remove the NIC with id 456 from the virtual machine with id 123 send a request like this: Important The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include: Red Hat Enterprise Linux 6 Red Hat Enterprise Linux 5 Windows Server 2008 and Windows Server 2003 Table 6.789. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.250.5. update PUT Updates the NIC. For example, to update the NIC having with 456 belonging to virtual the machine with id 123 send a request like this: With a request body like this: <nic> <name>mynic</name> <interface>e1000</interface> <vnic_profile id='789'/> </nic> Important The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include: Red Hat Enterprise Linux 6 Red Hat Enterprise Linux 5 Windows Server 2008 and Windows Server 2003 Table 6.790. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. nic Nic In/Out 6.251. VmNics Table 6.791. Methods summary Name Summary add Adds a NIC to the virtual machine. list Returns the list of NICs of the virtual machine. 6.251.1. add POST Adds a NIC to the virtual machine. The following example adds to the virtual machine 123 a network interface named mynic using virtio and the NIC profile 456 . <nic> <name>mynic</name> <interface>virtio</interface> <vnic_profile id="456"/> </nic> The following example sends that request using curl : curl \ --request POST \ --header "Version: 4" \ --header "Content-Type: application/xml" \ --header "Accept: application/xml" \ --user "admin@internal:mypassword" \ --cacert /etc/pki/ovirt-engine/ca.pem \ --data ' <nic> <name>mynic</name> <interface>virtio</interface> <vnic_profile id="456"/> </nic> ' \ https://myengine.example.com/ovirt-engine/api/vms/123/nics Important The hotplugging feature only supports virtual machine operating systems with hotplugging operations. Example operating systems include: Red Hat Enterprise Linux 6 Red Hat Enterprise Linux 5 Windows Server 2008 and Windows Server 2003 Table 6.792. Parameters summary Name Type Direction Summary nic Nic In/Out 6.251.2. list GET Returns the list of NICs of the virtual machine. The order of the returned list of NICs isn't guaranteed. Table 6.793. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of NICs to return. nics Nic[] Out 6.251.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.251.2.2. max Sets the maximum number of NICs to return. If not specified all the NICs are returned. 6.252. VmNumaNode Table 6.794. Methods summary Name Summary get remove Removes a virtual NUMA node. update Updates a virtual NUMA node. 6.252.1. get GET Table 6.795. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . node VirtualNumaNode Out 6.252.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.252.2. remove DELETE Removes a virtual NUMA node. An example of removing a virtual NUMA node: Note It's required to remove the numa nodes from the highest index first. Table 6.796. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.252.3. update PUT Updates a virtual NUMA node. An example of pinning a virtual NUMA node to a physical NUMA node on the host: The request body should contain the following: <vm_numa_node> <numa_node_pins> <numa_node_pin> <index>0</index> </numa_node_pin> </numa_node_pins> </vm_numa_node> Table 6.797. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. node VirtualNumaNode In/Out 6.253. VmNumaNodes Table 6.798. Methods summary Name Summary add Creates a new virtual NUMA node for the virtual machine. list Lists virtual NUMA nodes of a virtual machine. 6.253.1. add POST Creates a new virtual NUMA node for the virtual machine. An example of creating a NUMA node: The request body can contain the following: <vm_numa_node> <cpu> <cores> <core> <index>0</index> </core> </cores> </cpu> <index>0</index> <memory>1024</memory> </vm_numa_node> Table 6.799. Parameters summary Name Type Direction Summary node VirtualNumaNode In/Out 6.253.2. list GET Lists virtual NUMA nodes of a virtual machine. The order of the returned list of NUMA nodes isn't guaranteed. Table 6.800. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of nodes to return. nodes VirtualNumaNode[] Out 6.253.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.253.2.2. max Sets the maximum number of nodes to return. If not specified all the nodes are returned. 6.254. VmPool A service to manage a virtual machines pool. Table 6.801. Methods summary Name Summary allocatevm This operation allocates a virtual machine in the virtual machine pool. get Get the virtual machine pool. remove Removes a virtual machine pool. update Update the virtual machine pool. 6.254.1. allocatevm POST This operation allocates a virtual machine in the virtual machine pool. The allocate virtual machine action does not take any action specific parameters, so the request body should contain an empty action : <action/> Table 6.802. Parameters summary Name Type Direction Summary async Boolean In Indicates if the allocation should be performed asynchronously. 6.254.2. get GET Get the virtual machine pool. You will get a XML response like that one: <vm_pool id="123"> <actions>...</actions> <name>MyVmPool</name> <description>MyVmPool description</description> <link href="/ovirt-engine/api/vmpools/123/permissions" rel="permissions"/> <max_user_vms>1</max_user_vms> <prestarted_vms>0</prestarted_vms> <size>100</size> <stateful>false</stateful> <type>automatic</type> <use_latest_template_version>false</use_latest_template_version> <cluster id="123"/> <template id="123"/> <vm id="123">...</vm> ... </vm_pool> Table 6.803. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . pool VmPool Out Retrieved virtual machines pool. 6.254.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.254.3. remove DELETE Removes a virtual machine pool. Table 6.804. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.254.4. update PUT Update the virtual machine pool. The name , description , size , prestarted_vms and max_user_vms attributes can be updated after the virtual machine pool has been created. <vmpool> <name>VM_Pool_B</name> <description>Virtual Machine Pool B</description> <size>3</size> <prestarted_vms>1</size> <max_user_vms>2</size> </vmpool> Table 6.805. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. pool VmPool In/Out The virtual machine pool that is being updated. 6.255. VmPools Provides read-write access to virtual machines pools. Table 6.806. Methods summary Name Summary add Creates a new virtual machine pool. list Get a list of available virtual machines pools. 6.255.1. add POST Creates a new virtual machine pool. A new pool requires the name , cluster and template attributes. Identify the cluster and template with the id or name nested attributes: With the following body: <vmpool> <name>mypool</name> <cluster id="123"/> <template id="456"/> </vmpool> Table 6.807. Parameters summary Name Type Direction Summary pool VmPool In/Out Pool to add. 6.255.2. list GET Get a list of available virtual machines pools. You will receive the following response: <vm_pools> <vm_pool id="123"> ... </vm_pool> ... </vm_pools> The order of the returned list of pools is guaranteed only if the sortby clause is included in the search parameter. Table 6.808. 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. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of pools to return. pools VmPool[] Out Retrieved pools. search String In A query string used to restrict the returned pools. 6.255.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.255.2.2. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.255.2.3. max Sets the maximum number of pools to return. If this value is not specified, all of the pools are returned. 6.256. VmReportedDevice Table 6.809. Methods summary Name Summary get 6.256.1. get GET Table 6.810. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . reported_device ReportedDevice Out 6.256.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.257. VmReportedDevices Table 6.811. Methods summary Name Summary list Returns the list of reported devices of the virtual machine. 6.257.1. list GET Returns the list of reported devices of the virtual machine. The order of the returned list of devices isn't guaranteed. Table 6.812. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of devices to return. reported_device ReportedDevice[] Out 6.257.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.257.1.2. max Sets the maximum number of devices to return. If not specified all the devices are returned. 6.258. VmSession Table 6.813. Methods summary Name Summary get 6.258.1. get GET Table 6.814. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . session Session Out 6.258.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.259. VmSessions Provides information about virtual machine user sessions. Table 6.815. Methods summary Name Summary list Lists all user sessions for this virtual machine. 6.259.1. list GET Lists all user sessions for this virtual machine. For example, to retrieve the session information for virtual machine 123 send a request like this: The response body will contain something like this: <sessions> <session href="/ovirt-engine/api/vms/123/sessions/456" id="456"> <console_user>true</console_user> <ip> <address>192.168.122.1</address> </ip> <user href="/ovirt-engine/api/users/789" id="789"/> <vm href="/ovirt-engine/api/vms/123" id="123"/> </session> ... </sessions> The order of the returned list of sessions isn't guaranteed. Table 6.816. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of sessions to return. sessions Session[] Out 6.259.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.259.1.2. max Sets the maximum number of sessions to return. If not specified all the sessions are returned. 6.260. VmWatchdog A service managing a watchdog on virtual machines. Table 6.817. Methods summary Name Summary get Returns the information about the watchdog. remove Removes the watchdog from the virtual machine. update Updates the information about the watchdog. 6.260.1. get GET Returns the information about the watchdog. Table 6.818. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . watchdog Watchdog Out The information about the watchdog. 6.260.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.260.1.2. watchdog The information about the watchdog. The information consists of model element, action element and the reference to the virtual machine. It may look like this: <watchdogs> <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> <action>poweroff</action> <model>i6300esb</model> </watchdog> </watchdogs> 6.260.2. remove DELETE Removes the watchdog from the virtual machine. For example, to remove a watchdog from a virtual machine, send a request like this: Table 6.819. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.260.3. update PUT Updates the information about the watchdog. You can update the information using action and model elements. For example, to update a watchdog, send a request like this: with response body: <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> <action>reset</action> <model>i6300esb</model> </watchdog> Table 6.820. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. watchdog Watchdog In/Out The information about the watchdog. 6.260.3.1. watchdog The information about the watchdog. The request data must contain at least one of model and action elements. The response data contains complete information about the updated watchdog. 6.261. VmWatchdogs Lists the watchdogs of a virtual machine. Table 6.821. Methods summary Name Summary add Adds new watchdog to the virtual machine. list The list of watchdogs of the virtual machine. 6.261.1. add POST Adds new watchdog to the virtual machine. For example, to add a watchdog to a virtual machine, send a request like this: with response body: <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> <action>poweroff</action> <model>i6300esb</model> </watchdog> Table 6.822. Parameters summary Name Type Direction Summary watchdog Watchdog In/Out The information about the watchdog. 6.261.1.1. watchdog The information about the watchdog. The request data must contain model element (such as i6300esb ) and action element (one of none , reset , poweroff , dump , pause ). The response data additionally contains references to the added watchdog and to the virtual machine. 6.261.2. list GET The list of watchdogs of the virtual machine. The order of the returned list of watchdogs isn't guaranteed. Table 6.823. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of watchdogs to return. watchdogs Watchdog[] Out The information about the watchdog. 6.261.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.261.2.2. max Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned. 6.261.2.3. watchdogs The information about the watchdog. The information consists of model element, action element and the reference to the virtual machine. It may look like this: <watchdogs> <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> <action>poweroff</action> <model>i6300esb</model> </watchdog> </watchdogs> 6.262. Vms Table 6.824. Methods summary Name Summary add Creates a new virtual machine. list Returns the list of virtual machines of the system. 6.262.1. add POST Creates a new virtual machine. The virtual machine can be created in different ways: From a template. In this case the identifier or name of the template must be provided. For example, using a plain shell script and XML: #!/bin/sh -ex url="https://engine.example.com/ovirt-engine/api" user="admin@internal" password="..." curl \ --verbose \ --cacert /etc/pki/ovirt-engine/ca.pem \ --user "USD{user}:USD{password}" \ --request POST \ --header "Version: 4" \ --header "Content-Type: application/xml" \ --header "Accept: application/xml" \ --data ' <vm> <name>myvm</name> <template> <name>Blank</name> </template> <cluster> <name>mycluster</name> </cluster> </vm> ' \ "USD{url}/vms" From a snapshot. In this case the identifier of the snapshot has to be provided. For example, using a plain shel script and XML: #!/bin/sh -ex url="https://engine.example.com/ovirt-engine/api" user="admin@internal" password="..." curl \ --verbose \ --cacert /etc/pki/ovirt-engine/ca.pem \ --user "USD{user}:USD{password}" \ --request POST \ --header "Content-Type: application/xml" \ --header "Accept: application/xml" \ --data ' <vm> <name>myvm</name> <snapshots> <snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/> </snapshots> <cluster> <name>mycluster</name> </cluster> </vm> ' \ "USD{url}/vms" When creating a virtual machine from a template or from a snapshot it is usually useful to explicitly indicate in what storage domain to create the disks for the virtual machine. If the virtual machine is created from a template then this is achieved passing a set of disk_attachment elements that indicate the mapping: <vm> ... <disk_attachments> <disk_attachment> <disk id="8d4bd566-6c86-4592-a4a7-912dbf93c298"> <storage_domains> <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/> </storage_domains> </disk> <disk_attachment> </disk_attachments> </vm> When the virtual machine is created from a snapshot this set of disks is slightly different, it uses the image_id attribute instead of id . <vm> ... <disk_attachments> <disk_attachment> <disk> <image_id>8d4bd566-6c86-4592-a4a7-912dbf93c298</image_id> <storage_domains> <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/> </storage_domains> </disk> <disk_attachment> </disk_attachments> </vm> It is possible to specify additional virtual machine parameters in the XML description, e.g. a virtual machine of desktop type, with 2 GiB of RAM and additional description can be added sending a request body like the following: <vm> <name>myvm</name> <description>My Desktop Virtual Machine</description> <type>desktop</type> <memory>2147483648</memory> ... </vm> A bootable CDROM device can be set like this: <vm> ... <os> <boot dev="cdrom"/> </os> </vm> In order to boot from CDROM, you first need to insert a disk, as described in the CDROM service . Then booting from that CDROM can be specified using the os.boot.devices attribute: <vm> ... <os> <boot> <devices> <device>cdrom</device> </devices> </boot> </os> </vm> In all cases the name or identifier of the cluster where the virtual machine will be created is mandatory. Table 6.825. Parameters summary Name Type Direction Summary clone Boolean In Specifies if the virtual machine should be independent of the template. clone_permissions Boolean In Specifies if the permissions of the template should be copied to the virtual machine. vm Vm In/Out 6.262.1.1. clone Specifies if the virtual machine should be independent of the template. When a virtual machine is created from a template by default the disks of the virtual machine depend on the disks of the template, they are using the copy on write mechanism so that only the differences from the template take up real storage space. If this parameter is specified and the value is true then the disks of the created virtual machine will be cloned , and independent of the template. For example, to create an independent virtual machine, send a request like this: With a request body like this: <vm> <name>myvm<name> <template> <name>mytemplate<name> </template> <cluster> <name>mycluster<name> </cluster> </vm> Note When this parameter is true the permissions of the template will also be copied, as when using clone_permissions=true . 6.262.1.2. clone_permissions Specifies if the permissions of the template should be copied to the virtual machine. If this optional parameter is provided, and its values is true then the permissions of the template (only the direct ones, not the inherited ones) will be copied to the created virtual machine. For example, to create a virtual machine from the mytemplate template copying its permissions, send a request like this: With a request body like this: <vm> <name>myvm<name> <template> <name>mytemplate<name> </template> <cluster> <name>mycluster<name> </cluster> </vm> 6.262.2. list GET Returns the list of virtual machines of the system. The order of the returned list of virtual machines is guaranteed only if the sortby clause is included in the search parameter. Table 6.826. Parameters summary Name Type Direction Summary all_content Boolean In Indicates if all the attributes of the virtual machines should be included in the response. case_sensitive Boolean In Indicates if the search performed using the search parameter should be performed taking case into account. filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In The maximum number of results to return. search String In A query string used to restrict the returned virtual machines. vms Vm[] Out 6.262.2.1. all_content Indicates if all the attributes of the virtual machines should be included in the response. By default the following attributes are excluded: console initialization.configuration.data - The OVF document describing the virtual machine. rng_source soundcard virtio_scsi For example, to retrieve the complete representation of the virtual machines send a request like this: Note The reason for not including these attributes is performance: they are seldom used and they require additional queries to the database. So try to use the this parameter only when it is really needed. 6.262.2.2. 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.262.2.3. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.263. VnicProfile This service manages a vNIC profile. Table 6.827. Methods summary Name Summary get Retrieves details about a vNIC profile. remove Removes the vNIC profile. update Updates details of a vNIC profile. 6.263.1. get GET Retrieves details about a vNIC profile. Table 6.828. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . profile VnicProfile Out 6.263.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.263.2. remove DELETE Removes the vNIC profile. Table 6.829. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.263.3. update PUT Updates details of a vNIC profile. Table 6.830. Parameters summary Name Type Direction Summary async Boolean In Indicates if the update should be performed asynchronously. profile VnicProfile In/Out The vNIC profile that is being updated. 6.264. VnicProfiles This service manages the collection of all vNIC profiles. Table 6.831. Methods summary Name Summary add Add a vNIC profile. list List all vNIC profiles. 6.264.1. add POST Add a vNIC profile. For example to add vNIC profile 123 to network 456 send a request to: With the following body: <vnic_profile id="123"> <name>new_vNIC_name</name> <pass_through> <mode>disabled</mode> </pass_through> <port_mirroring>false</port_mirroring> </vnic_profile> Please note that there is a default network filter to each VNIC profile. For more details of how the default network filter is calculated please refer to the documentation in NetworkFilters . Note The automatically created vNIC profile for the external network will be without network filter. The output of creating a new VNIC profile depends in the body arguments that were given. In case no network filter was given, the default network filter will be configured. For example: <vnic_profile href="/ovirt-engine/api/vnicprofiles/123" id="123"> <name>new_vNIC_name</name> <link href="/ovirt-engine/api/vnicprofiles/123/permissions" rel="permissions"/> <pass_through> <mode>disabled</mode> </pass_through> <port_mirroring>false</port_mirroring> <network href="/ovirt-engine/api/networks/456" id="456"/> <network_filter href="/ovirt-engine/api/networkfilters/789" id="789"/> </vnic_profile> In case an empty network filter was given, no network filter will be configured for the specific VNIC profile regardless of the VNIC profile's default network filter. For example: <vnic_profile> <name>no_network_filter</name> <network_filter/> </vnic_profile> In case that a specific valid network filter id was given, the VNIC profile will be configured with the given network filter regardless of the VNIC profiles's default network filter. For example: <vnic_profile> <name>user_choice_network_filter</name> <network_filter id= "0000001b-001b-001b-001b-0000000001d5"/> </vnic_profile> Table 6.832. Parameters summary Name Type Direction Summary profile VnicProfile In/Out The vNIC profile that is being added. 6.264.2. list GET List all vNIC profiles. The order of the returned list of vNIC profiles isn't guaranteed. Table 6.833. Parameters summary Name Type Direction Summary follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of profiles to return. profiles VnicProfile[] Out The list of all vNIC profiles. 6.264.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.264.2.2. max Sets the maximum number of profiles to return. If not specified all the profiles are returned. 6.265. Weight Table 6.834. Methods summary Name Summary get remove 6.265.1. get GET Table 6.835. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . weight Weight Out 6.265.1.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.265.2. remove DELETE Table 6.836. Parameters summary Name Type Direction Summary async Boolean In Indicates if the remove should be performed asynchronously. 6.266. Weights Table 6.837. Methods summary Name Summary add Add a weight to a specified user defined scheduling policy. list Returns the list of weights. 6.266.1. add POST Add a weight to a specified user defined scheduling policy. Table 6.838. Parameters summary Name Type Direction Summary weight Weight In/Out 6.266.2. list GET Returns the list of weights. The order of the returned list of weights isn't guaranteed. Table 6.839. Parameters summary Name Type Direction Summary filter Boolean In Indicates if the results should be filtered according to the permissions of the user. follow String In Indicates which inner links should be followed . max Integer In Sets the maximum number of weights to return. weights Weight[] Out 6.266.2.1. follow Indicates which inner links should be followed . The objects referenced by these links will be fetched as part of the current request. See here for details. 6.266.2.2. max Sets the maximum number of weights to return. If not specified all the weights are returned.

Commands:
<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>
DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456
POST /ovirt-engine/api/clusters/123/affinitygroups/456/vms
<vm id="789"/>
POST /ovirt-engine/api/clusters/000-000/affinitygroups
<affinity_group> <name>AF_GROUP_001</name> <hosts_rule> <enforcing>true</enforcing> <positive>true</positive> </hosts_rule> <vms_rule> <enabled>false</enabled> </vms_rule> </affinity_group>
POST /ovirt-engine/api/vms/123/permissions
<permission> <role> <name>UserVmManager</name> </role> <user id="456"/> </permission>
POST /ovirt-engine/api/permissions
<permission> <role> <name>SuperUser</name> </role> <user id="456"/> </permission>
POST /ovirt-engine/api/clusters/123/permissions
<permission> <role> <name>UserRole</name> </role> <group id="789"/> </permission>
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>
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>
DELETE /ovirt-engine/api/vms/123/tags/456
POST /ovirt-engine/api/vms/123/tags
<tag> <name>mytag</name> </tag>
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>
POST /ovirt-engine/api/datacenters/123/storagedomains/456/activate
<action/>
POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate
<action/>
POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate
<action> <force>true</force> <action>
POST /ovirt-engine/api/storagedomains/123/disks?unregistered=true
<disk id="456"/>
POST /ovirt-engine/api/storagedomains/123/disks
<disk> <name>mydisk</name> <format>cow</format> <provisioned_size>1073741824</provisioned_size> </disk>
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>
DELETE /ovirt-engine/api/bookmarks/123
PUT /ovirt-engine/api/bookmarks/123
<bookmark> <name>new_example_vm</name> <value>vm: name=new_example*</value> </bookmark>
POST /ovirt-engine/api/bookmarks
<bookmark> <name>new_example_vm</name> <value>vm: name=new_example*</value> </bookmark>
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>
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>
DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
POST /ovirt-engine/api/clusters/123/syncallnetworks
<action/>
PUT /ovirt-engine/api/clusters/123
<cluster> <cpu> <type>Intel Haswell-noTSX Family</type> </cpu> </cluster>
GET /ovirt-engine/api/clusters/123/enabledfeatures/456
<cluster_feature id="456"> <name>libgfapi_supported</name> </cluster_feature>
DELETE /ovirt-engine/api/clusters/123/enabledfeatures/456
POST /ovirt-engine/api/clusters/123/enabledfeatures
<cluster_feature id="456"/>
GET /ovirt-engine/api/clusters/123/enabledfeatures
<enabled_features> <cluster_feature id="123"> <name>test_feature</name> </cluster_feature> </enabled_features>
GET /ovirt-engine/api/clusterlevels/4.1/clusterfeatures/456
<cluster_feature id="456"> <name>libgfapi_supported</name> </cluster_feature>
GET /ovirt-engine/api/clusterlevels/4.1/clusterfeatures
<cluster_features> <cluster_feature id="123"> <name>test_feature</name> </cluster_feature> </cluster_features>
GET /ovirt-engine/api/clusterlevels/3.6
<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>
GET /ovirt-engine/api/clusterlevels
<cluster_levels> <cluster_level id="4.0"> </cluster_level> </cluster_levels>
POST /ovirt-engine/api/clusters/123/networks
<network id="123" />
POST /ovirt-engine/api/clusters
<cluster> <name>mycluster</name> <cpu> <type>Intel Penryn Family</type> </cpu> <data_center id="123"/> </cluster>
POST /ovirt-engine/api/clusters
<cluster> <name>mycluster</name> <cpu> <type>Intel Penryn Family</type> </cpu> <data_center id="123"/> <external_network_providers> <external_provider name="ovirt-provider-ovn"/> </external_network_providers> </cluster>
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>
DELETE /ovirt-engine/api/datacenters/123
PUT /ovirt-engine/api/datacenters/123
<data_center> <name>myupdatedname</name> <description>An updated description for the data center</description> </data_center>
POST /ovirt-engine/api/datacenters/123/networks
<network> <name>mynetwork</name> </network>
POST /ovirt-engine/api/datacenters
<data_center> <name>mydc</name> <local>false</local> </data_center>
GET /ovirt-engine/api/datacenters
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
<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>
POST /ovirt-engine/api/disks/123/copy
<action> <storage_domain id="456"/> <disk> <name>mydisk</name> </disk> </action>
<action> <storage_domain id="456"/> <disk_profile id="987"/> <quota id="753"/> </action>
POST /ovirt-engine/api/storagedomains/123/disks/789
<action> <storage_domain> <name>mydata</name> </storage_domain> </action>
GET /ovirt-engine/api/disks/123?all_content=true
POST /ovirt-engine/api/disks/123/move
<action> <storage_domain id="456"/> </action>
<action> <storage_domain id="456"/> <disk_profile id="987"/> <quota id="753"/> </action>
POST /ovirt-engine/api/disks/123/refreshlun
<action> <host id='456'/> </action>
PUT /ovirt-engine/api/disks/123
<disk> <qcow_version>qcow2_v3</qcow_version> </disk>
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>
DELETE /ovirt-engine/api/vms/123/diskattachments/456?detach_only=true
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>
<disk_attachment> <bootable>true</bootable> <pass_discard>true</pass_discard> <interface>ide</interface> <active>true</active> <disk id="123"/> </disk_attachment>
<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>
POST /ovirt-engine/api/vms/345/diskattachments
POST /ovirt-engine/api/disks
<disk> <storage_domains> <storage_domain id="123"/> </storage_domains> <name>mydisk</name> <provisioned_size>1048576</provisioned_size> <format>cow</format> </disk>
POST /ovirt-engine/api/disks
<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>
POST /ovirt-engine/api/disks
<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>
qemu-img info b7a4c6c5-443b-47c5-967f-6abc79675e8b/myimage.img image: b548366b-fb51-4b41-97be-733c887fe305 file format: qcow2 virtual size: 1.0G (1073741824 bytes) disk size: 196K cluster_size: 65536 backing file: ad58716a-1fe9-481f-815e-664de1df04eb backing file format: raw
POST /ovirt-engine/api/disks
<disk id="b7a4c6c5-443b-47c5-967f-6abc79675e8b"> <image_id>b548366b-fb51-4b41-97be-733c887fe305</image_id> <storage_domains> <storage_domain id="123"/> </storage_domains> <name>mydisk</name> <provisioned_size>1048576</provisioned_size> <format>cow</format> </disk>
GET /ovirt-engine/api/disks
<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>
GET /ovirt-engine/api/domains/5678
<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>
GET /ovirt-engine/api/domains/5678/users/1234
<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>
GET /ovirt-engine/api/domains/5678/users
<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>
GET /ovirt-engine/api/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>
GET /ovirt-engine/api/katelloerrata
<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>
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>
DELETE /ovirt-engine/api/events/123
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>
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>
GET /ovirt-engine/api/events
<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>
GET /ovirt-engine/api/events?max=1
GET /ovirt-engine/api/events?from=123
GET /ovirt-engine/api/events?search=severity%3Dnormal
<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>
sortby time asc page 1
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202
GET /ovirt-engine/api/externalhostproviders/123/computeresources/234
<external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234"> <name>hostname</name> <provider>oVirt</provider> <url>https://hostname/api</url> <user>admin@internal</user> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_compute_resource>
GET /ovirt-engine/api/externalhostproviders/123/computeresources
<external_compute_resources> <external_compute_resource href="/ovirt-engine/api/externalhostproviders/123/computeresources/234" id="234"> <name>hostname</name> <provider>oVirt</provider> <url>https://address/api</url> <user>admin@internal</user> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_compute_resource> </external_compute_resources>
GET /ovirt-engine/api/externalhostproviders/123/discoveredhosts/234
<external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/234" id="234"> <name>mac001a4ad04040</name> <ip>10.34.67.43</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:40</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host>
GET /ovirt-engine/api/externalhostproviders/123/discoveredhost
<external_discovered_hosts> <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/456" id="456"> <name>mac001a4ad04031</name> <ip>10.34.67.42</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:31</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host> <external_discovered_host href="/ovirt-engine/api/externalhostproviders/123/discoveredhosts/789" id="789"> <name>mac001a4ad04040</name> <ip>10.34.67.43</ip> <last_report>2017-04-24 11:05:41 UTC</last_report> <mac>00:1a:4a:d0:40:40</mac> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_discovered_host> </external_discovered_hosts>
GET /ovirt-engine/api/externalhostproviders/123/hostgroups/234
<external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234"> <name>rhel7</name> <architecture_name>x86_64</architecture_name> <domain_name>s.com</domain_name> <operating_system_name>RedHat 7.3</operating_system_name> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_host_group>
GET /ovirt-engine/api/externalhostproviders/123/hostgroups
<external_host_groups> <external_host_group href="/ovirt-engine/api/externalhostproviders/123/hostgroups/234" id="234"> <name>rhel7</name> <architecture_name>x86_64</architecture_name> <domain_name>example.com</domain_name> <operating_system_name>RedHat 7.3</operating_system_name> <subnet_name>sat0</subnet_name> <external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"/> </external_host_group> </external_host_groups>
GET /ovirt-engine/api/externalhostproviders/123
<external_host_provider href="/ovirt-engine/api/externalhostproviders/123" id="123"> <name>mysatellite</name> <requires_authentication>true</requires_authentication> <url>https://mysatellite.example.com</url> <username>admin</username> </external_host_provider>
POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
GET /ovirt-engine/api/externalhostproviders/123/certificate/0
<certificate id="0"> <organization>provider.example.com</organization> <subject>CN=provider.example.com</subject> <content>...</content> </certificate>
GET /ovirt-engine/api/externalhostproviders/123/certificates
<certificates> <certificate id="789">...</certificate> </certificates>
POST /externalvmimports
<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>
GET /ovirt-engine/api/hosts/123/fenceagents/0
<agent id="0"> <type>apc</type> <order>1</order> <ip>192.168.1.101</ip> <user>user</user> <password>xxx</password> <port>9</port> <options>name1=value1, name2=value2</options> </agent>
DELETE /ovirt-engine/api/hosts/123/fenceagents/0
GET /ovirt-engine/api/hosts/123/fenceagents
<agents> <agent id="0"> <type>apc</type> <order>1</order> <ip>192.168.1.101</ip> <user>user</user> <password>xxx</password> <port>9</port> <options>name1=value1, name2=value2</options> </agent> </agents>
engine-config -s ForceRefreshDomainFilesByDefault=false
GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234
<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>
DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/234
POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/activate
<action> <bricks> <brick> <name>host1:/rhgs/brick1</name> </brick> </bricks> </action>
POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
<bricks> <brick> <server_id>111</server_id> <brick_dir>/export/data/brick3</brick_dir> </brick> </bricks>
GET /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
<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>
POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/migrate
<action> <bricks> <brick> <name>host1:/rhgs/brick1</name> </brick> </bricks> </action>
DELETE /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks
<bricks> <brick> <name>host:brick_directory</name> </brick> </bricks>
POST /ovirt-engine/api/clusters/567/glustervolumes/123/glusterbricks/stopmigrate
<bricks> <brick> <name>host:brick_directory</name> </brick> </bricks>
GET /ovirt-engine/api/clusters/456/glustervolumes/123
<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>
POST /ovirt-engine/api/clusters/456/glustervolumes/123/getprofilestatistics
POST /ovirt-engine/api/clusters/456/glustervolumes/123/rebalance
DELETE /ovirt-engine/api/clusters/456/glustervolumes/123
POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetalloptions
POST /ovirt-engine/api/clusters/456/glustervolumes/123/resetoption
<action> <option name="option1"/> </action>
POST /ovirt-engine/api/clusters/456/glustervolumes/123/setoption
<action> <option name="option1" value="value1"/> </action>
POST /ovirt-engine/api/clusters/456/glustervolumes/123/start
POST /ovirt-engine/api/clusters/456/glustervolumes/123/startprofile
POST /ovirt-engine/api/clusters/456/glustervolumes/123/stop
POST /ovirt-engine/api/clusters/456/glustervolumes/123/stopprofile
POST /ovirt-engine/api/clusters/456/glustervolumes/123/stoprebalance
POST /ovirt-engine/api/clusters/123/glustervolumes
<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>
GET /ovirt-engine/api/clusters/456/glustervolumes
GET /ovirt-engine/api/groups/123
<group href="/ovirt-engine/api/groups/123" id="123"> <name>mygroup</name> <link href="/ovirt-engine/api/groups/123/roles" rel="roles"/> <link href="/ovirt-engine/api/groups/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/groups/123/tags" rel="tags"/> <domain_entry_id>476652557A382F67696B6D2B32762B37796E46476D513D3D</domain_entry_id> <namespace>DC=example,DC=com</namespace> <domain href="/ovirt-engine/api/domains/ABCDEF" id="ABCDEF"> <name>myextension-authz</name> </domain> </group>
DELETE /ovirt-engine/api/groups/123
POST /ovirt-engine/api/groups
<group> <name>Developers</name> <domain> <name>internal-authz</name> </domain> </group>
GET /ovirt-engine/api/groups
<groups> <group href="/ovirt-engine/api/groups/123" id="123"> <name>mygroup</name> <link href="/ovirt-engine/api/groups/123/roles" rel="roles"/> <link href="/ovirt-engine/api/groups/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/groups/123/tags" rel="tags"/> <domain_entry_id>476652557A382F67696B6D2B32762B37796E46476D513D3D</domain_entry_id> <namespace>DC=example,DC=com</namespace> <domain href="/ovirt-engine/api/domains/ABCDEF" id="ABCDEF"> <name>myextension-authz</name> </domain> </group> </groups>
POST /ovirt-engine/api/hosts/123/commitnetconfig
<action/>
#!/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 "USD{user}:USD{password}" --request POST --header "Version: 4" --header "Content-Type: application/xml" --header "Accept: application/xml" --data ' <action> <fence_type>start</fence_type> </action> ' "USD{url}/hosts/123/fence"
POST /ovirt-engine/api/hosts/123/forceselectspm
<action/>
GET /ovirt-engine/api/hosts/123
GET /ovirt-engine/api/hosts/123?all_content=true
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"
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"
POST /ovirt-engine/api/hosts/123/iscsidiscover
<action> <iscsi> <address>myiscsi.example.com</address> </iscsi> </action>
<discovered_targets> <iscsi_details> <address>10.35.1.72</address> <port>3260</port> <portal>10.35.1.72:3260,1</portal> <target>iqn.2015-08.com.tgt:444</target> </iscsi_details> </discovered_targets>
#!/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 "USD{user}:USD{password}" --request DELETE --header "Version: 4" "USD{url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc"
#!/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 "USD{user}:USD{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> ' "USD{url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc/setupnetworks"
<options name="mode" value="4"/> <options name="miimon" value="100"/> <ip address="192.168.122.10" netmask="255.255.255.0"/>
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()
POST /ovirt-engine/api/hosts/123/syncallnetworks
<action/>
PUT /ovirt-engine/api/hosts/123
<host> <os> <custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline> </os> </host>
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>
GET /ovirt-engine/api/hosts/123/storage
<host_storages> <host_storage id="123"> </host_storage> </host_storages>
<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>
<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>
POST /ovirt-engine/api/hosts
<host> <name>myhost</name> <address>myhost.example.com</address> <root_password>myrootpassword</root_password> </host>
POST /ovirt-engine/api/hosts?deploy_hosted_engine=true
POST /ovirt-engine/api/hosts
<host> <name>myhost</name> <address>myhost.example.com</address> <root_password>123456</root_password> <external_network_provider_configurations> <external_network_provider_configuration> <external_network_provider name="ovirt-provider-ovn"/> </external_network_provider_configuration> </external_network_provider_configurations> </host>
GET /ovirt-engine/api/hosts
<hosts> <host href="/ovirt-engine/api/hosts/123" id="123"> </host> <host href="/ovirt-engine/api/hosts/456" id="456"> </host> </host>
GET /ovirt-engine/api/hosts?all_content=true
GET /ovirt-engine/api/icons/123
<icon id="123"> <data>Some binary data here</data> <media_type>image/png</media_type> </icon>
GET /ovirt-engine/api/icons
<icons> <icon id="123"> <data>...</data> <media_type>image/png</media_type> </icon> </icons>
transfers_service = system_service.image_transfers_service() transfer = transfers_service.add( types.ImageTransfer( disk=types.Disk( id='123' ) ) )
transfers_service = system_service.image_transfers_service() transfer = transfers_service.add( types.ImageTransfer( disk=types.Disk( id='123' ), host=types.Host( id='456' ) ) )
transfers_service = system_service.image_transfers_service() transfer = transfers_service.add( types.ImageTransfer( disk=types.Disk( id='123' ), direction=types.ImageTransferDirection.DOWNLOAD ) )
transfer_service = transfers_service.image_transfer_service(transfer.id) while transfer.phase == types.ImageTransferPhase.INITIALIZING: time.sleep(3) transfer = transfer_service.get()
transfer_headers = { 'Authorization' : transfer.signed_ticket, }
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) )
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
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
transfer_service.finalize()
POST /ovirt-engine/api/disks
<disk> <storage_domains> <storage_domain id="123"/> </storage_domains> <alias>mydisk</alias> <initial_size>1073741824</initial_size> <provisioned_size>1073741824</provisioned_size> <format>raw</format> </disk>
POST /ovirt-engine/api/imagetransfers
<image_transfer> <disk id="456"/> <direction>upload|download</direction> </image_transfer>
<image_transfer id="123"> <direction>download|upload</direction> <phase>initializing|transferring</phase> <proxy_url>https://proxy_fqdn:54323/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb</proxy_url> <transfer_url>https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb</transfer_url> </image_transfer>
curl --cacert /etc/pki/ovirt-engine/ca.pem https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb -o <output_file>
curl --cacert /etc/pki/ovirt-engine/ca.pem --upload-file <file_to_upload> -X PUT https://daemon_fqdn:54322/images/41c732d4-2210-4e7b-9e5c-4e2805baadbb
POST /ovirt-engine/api/imagetransfers/123/finalize
<action />
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()
POST /ovirt-engine/api/imagetransfers
<image_transfer> <disk id="123"/> <direction>upload|download</direction> </image_transfer>
POST /ovirt-engine/api/imagetransfers
<image_transfer> <snapshot id="456"/> <direction>download|upload</direction> </image_transfer>
GET /ovirt-engine/api/instancetypes/123
DELETE /ovirt-engine/api/instancetypes/123
PUT /ovirt-engine/api/instancetypes/123
<instance_type> <memory>1073741824</memory> <cpu> <topology> <cores>1</cores> <sockets>2</sockets> <threads>1</threads> </topology> </cpu> </instance_type>
POST /ovirt-engine/api/instancetypes
<instance_type> <name>myinstancetype</name> </template>
<instance_type> <name>myinstancetype</name> <console> <enabled>true</enabled> </console> <cpu> <topology> <cores>2</cores> <sockets>2</sockets> <threads>1</threads> </topology> </cpu> <custom_cpu_model>AMD Opteron_G2</custom_cpu_model> <custom_emulated_machine>q35</custom_emulated_machine> <display> <monitors>1</monitors> <single_qxl_pci>true</single_qxl_pci> <smartcard_enabled>true</smartcard_enabled> <type>spice</type> </display> <high_availability> <enabled>true</enabled> <priority>1</priority> </high_availability> <io> <threads>2</threads> </io> <memory>4294967296</memory> <memory_policy> <ballooning>true</ballooning> <guaranteed>268435456</guaranteed> </memory_policy> <migration> <auto_converge>inherit</auto_converge> <compressed>inherit</compressed> <policy id="00000000-0000-0000-0000-000000000000"/> </migration> <migration_downtime>2</migration_downtime> <os> <boot> <devices> <device>hd</device> </devices> </boot> </os> <rng_device> <rate> <bytes>200</bytes> <period>2</period> </rate> <source>urandom</source> </rng_device> <soundcard_enabled>true</soundcard_enabled> <usb> <enabled>true</enabled> <type>native</type> </usb> <virtio_scsi> <enabled>true</enabled> </virtio_scsi> </instance_type>
DELETE /ovirt-engine/api/datacenters/123/iscsibonds/456
PUT /ovirt-engine/api/datacenters/123/iscsibonds/1234
<iscsi_bond> <name>mybond</name> <description>My iSCSI bond</description> </iscsi_bond>
POST /ovirt-engine/api/datacenters/123/iscsibonds
<iscsi_bond> <name>mybond</name> <storage_connections> <storage_connection id="456"/> <storage_connection id="789"/> </storage_connections> <networks> <network id="abc"/> </networks> </iscsi_bond>
POST /ovirt-engine/api/jobs/clear
<action/>
POST /ovirt-engine/api/jobs/end
<action> <force>true</force> <status>finished</status> </action>
GET /ovirt-engine/api/jobs/123
<job href="/ovirt-engine/api/jobs/123" id="123"> <actions> <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/> <link href="/ovirt-engine/api/jobs/123/end" rel="end"/> </actions> <description>Adding Disk</description> <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/> <auto_cleared>true</auto_cleared> <end_time>2016-12-12T23:07:29.758+02:00</end_time> <external>false</external> <last_updated>2016-12-12T23:07:29.758+02:00</last_updated> <start_time>2016-12-12T23:07:26.593+02:00</start_time> <status>failed</status> <owner href="/ovirt-engine/api/users/456" id="456"/> </job>
POST /ovirt-engine/api/jobs
<job> <description>Doing some work</description> <auto_cleared>true</auto_cleared> </job>
<job href="/ovirt-engine/api/jobs/123" id="123"> <actions> <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/> <link href="/ovirt-engine/api/jobs/123/end" rel="end"/> </actions> <description>Doing some work</description> <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/> <auto_cleared>true</auto_cleared> <external>true</external> <last_updated>2016-12-13T02:15:42.130+02:00</last_updated> <start_time>2016-12-13T02:15:42.130+02:00</start_time> <status>started</status> <owner href="/ovirt-engine/api/users/456" id="456"/> </job>
GET /ovirt-engine/api/jobs
<jobs> <job href="/ovirt-engine/api/jobs/123" id="123"> <actions> <link href="/ovirt-engine/api/jobs/123/clear" rel="clear"/> <link href="/ovirt-engine/api/jobs/123/end" rel="end"/> </actions> <description>Adding Disk</description> <link href="/ovirt-engine/api/jobs/123/steps" rel="steps"/> <auto_cleared>true</auto_cleared> <end_time>2016-12-12T23:07:29.758+02:00</end_time> <external>false</external> <last_updated>2016-12-12T23:07:29.758+02:00</last_updated> <start_time>2016-12-12T23:07:26.593+02:00</start_time> <status>failed</status> <owner href="/ovirt-engine/api/users/456" id="456"/> </job> </jobs>
GET /ovirt-engine/api/katelloerrata
<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>
GET /ovirt-engine/api/katelloerrata/123
<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>
GET ovirt-engine/api/hosts/123/nics/321/linklayerdiscoveryprotocolelements
<link_layer_discovery_protocol_elements> <link_layer_discovery_protocol_element> <name>Port Description</name> <properties> <property> <name>port description</name> <value>Summit300-48-Port 1001</value> </property> </properties> <type>4</type> </link_layer_discovery_protocol_element> <link_layer_discovery_protocol_elements>
DELETE /ovirt-engine/api/macpools/123
PUT /ovirt-engine/api/macpools/123
<mac_pool> <name>UpdatedMACPool</name> <description>An updated MAC address pool</description> <allow_duplicates>false</allow_duplicates> <ranges> <range> <from>00:1A:4A:16:01:51</from> <to>00:1A:4A:16:01:e6</to> </range> <range> <from>02:1A:4A:01:00:00</from> <to>02:1A:4A:FF:FF:FF</to> </range> </ranges> </mac_pool>
POST /ovirt-engine/api/macpools
<mac_pool> <name>MACPool</name> <description>A MAC address pool</description> <allow_duplicates>true</allow_duplicates> <default_pool>false</default_pool> <ranges> <range> <from>00:1A:4A:16:01:51</from> <to>00:1A:4A:16:01:e6</to> </range> </ranges> </mac_pool>
GET /ovirt-engine/api/networks/123
<network href="/ovirt-engine/api/networks/123" id="123"> <name>ovirtmgmt</name> <description>Default Management Network</description> <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/> <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/> <mtu>0</mtu> <stp>false</stp> <usages> <usage>vm</usage> </usages> <data_center href="/ovirt-engine/api/datacenters/456" id="456"/> </network>
DELETE /ovirt-engine/api/networks/123
DELETE /ovirt-engine/api/datacenters/123/networks/456
PUT /ovirt-engine/api/networks/123
<network> <description>My updated description</description> </network>
PUT /ovirt-engine/api/datacenters/123/networks/456
<network> <mtu>1500</mtu> </network>
<network_filter id="00000019-0019-0019-0019-00000000026b"> <name>example-network-filter-b</name> <version> <major>4</major> <minor>0</minor> <build>-1</build> <revision>-1</revision> </version> </network_filter>
GET http://localhost:8080/ovirt-engine/api/clusters/{cluster:id}/networkfilters
<network_filters> <network_filter id="00000019-0019-0019-0019-00000000026c"> <name>example-network-filter-a</name> <version> <major>4</major> <minor>0</minor> <build>-1</build> <revision>-1</revision> </version> </network_filter> <network_filter id="00000019-0019-0019-0019-00000000026b"> <name>example-network-filter-b</name> <version> <major>4</major> <minor>0</minor> <build>-1</build> <revision>-1</revision> </version> </network_filter> <network_filter id="00000019-0019-0019-0019-00000000026a"> <name>example-network-filter-a</name> <version> <major>3</major> <minor>0</minor> <build>-1</build> <revision>-1</revision> </version> </network_filter> </network_filters>
DELETE /ovirt-engine/api/networks/123/labels/exemplary
POST /ovirt-engine/api/networks/123/labels
<label id="mylabel"/>
POST /ovirt-engine/api/networks
<network> <name>mynetwork</name> <data_center id="123"/> </network>
POST /ovirt-engine/api/datacenters/123/networks
<network> <name>ovirtmgmt</name> </network>
POST /ovirt-engine/api/networks
<network> <name>exnetwork</name> <external_provider id="456"/> <data_center id="123"/> </network>
GET /ovirt-engine/api/networks
<networks> <network href="/ovirt-engine/api/networks/123" id="123"> <name>ovirtmgmt</name> <description>Default Management Network</description> <link href="/ovirt-engine/api/networks/123/permissions" rel="permissions"/> <link href="/ovirt-engine/api/networks/123/vnicprofiles" rel="vnicprofiles"/> <link href="/ovirt-engine/api/networks/123/networklabels" rel="networklabels"/> <mtu>0</mtu> <stp>false</stp> <usages> <usage>vm</usage> </usages> <data_center href="/ovirt-engine/api/datacenters/456" id="456"/> </network> </networks>
DELETE /ovirt-engine/api/vms/789/nics/456/networkfilterparameters/123
PUT /ovirt-engine/api/vms/789/nics/456/networkfilterparameters/123
<network_filter_parameter> <name>updatedName</name> <value>updatedValue</value> </network_filter_parameter>
POST /ovirt-engine/api/vms/789/nics/456/networkfilterparameters
<network_filter_parameter> <name>IP</name> <value>10.0.1.2</value> </network_filter_parameter>
POST /ovirt-engine/api/openstackimageproviders/123/images/456/import
<action> <storage_domain> <name>images0</name> </storage_domain> <cluster> <name>images0</name> </cluster> </action>
POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
GET /ovirt-engine/api/openstacknetworkproviders/1234
DELETE /ovirt-engine/api/openstacknetworkproviders/1234
POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
PUT /ovirt-engine/api/openstacknetworkproviders/1234
<openstack_network_provider> <name>ovn-network-provider</name> <requires_authentication>false</requires_authentication> <url>http://some_server_url.domain.com:9696</url> <tenant_name>oVirt</tenant_name> <type>external</type> </openstack_network_provider>
POST /ovirt-engine/api/externalhostproviders/123/testconnectivity
POST /ovirt-engine/api/openstackvolumeproviders
<openstack_volume_provider> <name>mycinder</name> <url>https://mycinder.example.com:8776</url> <data_center> <name>mydc</name> </data_center> <requires_authentication>true</requires_authentication> <username>admin</username> <password>mypassword</password> <tenant_name>mytenant</tenant_name> </openstack_volume_provider>
GET /ovirt-engine/api/roles/123/permits/456
<permit href="/ovirt-engine/api/roles/123/permits/456" id="456"> <name>change_vm_cd</name> <administrative>false</administrative> <role href="/ovirt-engine/api/roles/123" id="123"/> </permit>
DELETE /ovirt-engine/api/roles/123/permits/456
POST /ovirt-engine/api/roles/123/permits
<permit> <name>create_vm</name> </permit>
GET /ovirt-engine/api/roles/123/permits
<permits> <permit href="/ovirt-engine/api/roles/123/permits/5" id="5"> <name>change_vm_cd</name> <administrative>false</administrative> <role href="/ovirt-engine/api/roles/123" id="123"/> </permit> <permit href="/ovirt-engine/api/roles/123/permits/7" id="7"> <name>connect_to_vm</name> <administrative>false</administrative> <role href="/ovirt-engine/api/roles/123" id="123"/> </permit> </permits>
GET /ovirt-engine/api/datacenters/123/qoss/123
<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123"> <name>123</name> <description>123</description> <max_iops>1</max_iops> <max_throughput>1</max_throughput> <type>storage</type> <data_center href="/ovirt-engine/api/datacenters/123" id="123"/> </qos>
DELETE /ovirt-engine/api/datacenters/123/qoss/123
PUT /ovirt-engine/api/datacenters/123/qoss/123
curl -u admin@internal:123456 -X PUT -H "content-type: application/xml" -d "<qos><name>321</name><description>321</description><max_iops>10</max_iops></qos>" https://engine/ovirt-engine/api/datacenters/123/qoss/123
<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123"> <name>321</name> <description>321</description> <max_iops>10</max_iops> <max_throughput>1</max_throughput> <type>storage</type> <data_center href="/ovirt-engine/api/datacenters/123" id="123"/> </qos>
POST /ovirt-engine/api/datacenters/123/qoss
<qos href="/ovirt-engine/api/datacenters/123/qoss/123" id="123"> <name>123</name> <description>123</description> <max_iops>10</max_iops> <type>storage</type> <data_center href="/ovirt-engine/api/datacenters/123" id="123"/> </qos>
GET /ovirt-engine/api/datacenter/123/qoss
<qoss> <qos href="/ovirt-engine/api/datacenters/123/qoss/1" id="1">...</qos> <qos href="/ovirt-engine/api/datacenters/123/qoss/2" id="2">...</qos> <qos href="/ovirt-engine/api/datacenters/123/qoss/3" id="3">...</qos> </qoss>
GET /ovirt-engine/api/datacenters/123/quotas/456
<quota id="456"> <name>myquota</name> <description>My new quota for virtual machines</description> <cluster_hard_limit_pct>20</cluster_hard_limit_pct> <cluster_soft_limit_pct>80</cluster_soft_limit_pct> <storage_hard_limit_pct>20</storage_hard_limit_pct> <storage_soft_limit_pct>80</storage_soft_limit_pct> </quota>
DELETE /ovirt-engine/api/datacenters/123-456/quotas/654-321 -0472718ab224 HTTP/1.1 Accept: application/xml Content-type: application/xml
PUT /ovirt-engine/api/datacenters/123/quotas/456
<quota> <cluster_hard_limit_pct>30</cluster_hard_limit_pct> <cluster_soft_limit_pct>70</cluster_soft_limit_pct> <storage_hard_limit_pct>20</storage_hard_limit_pct> <storage_soft_limit_pct>80</storage_soft_limit_pct> </quota>
POST /ovirt-engine/api/datacenters/123/quotas/456/quotastoragelimits
<quota_storage_limit> <limit>100</limit> </quota_storage_limit>
POST /ovirt-engine/api/datacenters/123/quotas/456/quotastoragelimits
<quota_storage_limit> <limit>50</limit> <storage_domain id="000"/> </quota_storage_limit>
POST /ovirt-engine/api/datacenters/123/quotas
<quota> <name>myquota</name> <description>My new quota for virtual machines</description> </quota>
GET /ovirt-engine/api/roles/123
<role id="123"> <name>MyRole</name> <description>MyRole description</description> <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/> <administrative>true</administrative> <mutable>false</mutable> </role>
DELETE /ovirt-engine/api/roles/{role_id}
PUT /ovirt-engine/api/roles/123
<role> <name>MyNewRoleName</name> <description>My new description of the role</description> <administrative>true</administrative> </group>
POST /ovirt-engine/api/roles
<role> <name>MyRole</name> <description>My custom role to create virtual machines</description> <administrative>false</administrative> <permits> <permit id="1"/> <permit id="1300"/> </permits> </group>
GET /ovirt-engine/api/roles
<roles> <role id="123"> <name>SuperUser</name> <description>Roles management administrator</description> <link href="/ovirt-engine/api/roles/123/permits" rel="permits"/> <administrative>true</administrative> <mutable>false</mutable> </role> </roles>
GET /ovirt-engine/api/vms/123/snapshots/456?all_content=true
POST /ovirt-engine/api/vms/123/snapshots/456/restore
<action/>
POST /ovirt-engine/api/vms/123/snapshots/456/restore
<action> <disks> <disk id="111"> <image_id>222</image_id> </disk> </disks> </action>
POST /ovirt-engine/api/vms/123/snapshots
<snapshot> <description>My snapshot</description> </snapshot>
<snapshot> <description>My snapshot</description> <disk_attachments> <disk_attachment> <disk id="123"> <image_id>456</image_id> </disk> </disk_attachment> </disk_attachments> </snapshot>
<snapshot> <description>My snapshot</description> <persist_memorystate>false</persist_memorystate> </snapshot>
GET /ovirt-engine/api/vms/123/snapshots?all_content=true
GET /ovirt-engine/api/users/123/sshpublickeys
<ssh_public_keys> <ssh_public_key href="/ovirt-engine/api/users/123/sshpublickeys/456" id="456"> <content>ssh-rsa ...</content> <user href="/ovirt-engine/api/users/123" id="123"/> </ssh_public_key> </ssh_public_keys>
{ "ssh_public_key": [ { "content": "ssh-rsa ...", "user": { "href": "/ovirt-engine/api/users/123", "id": "123" }, "href": "/ovirt-engine/api/users/123/sshpublickeys/456", "id": "456" } ] }
GET /ovirt-engine/api/vms/123/statistics
<statistics> <statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456"> <name>memory.installed</name> <description>Total memory configured</description> <kind>gauge</kind> <type>integer</type> <unit>bytes</unit> <values> <value> <datum>1073741824</datum> </value> </values> <vm href="/ovirt-engine/api/vms/123" id="123"/> </statistic> </statistics>
GET /ovirt-engine/api/vms/123/statistics/456
<statistic href="/ovirt-engine/api/vms/123/statistics/456" id="456"> <name>memory.installed</name> <description>Total memory configured</description> <kind>gauge</kind> <type>integer</type> <unit>bytes</unit> <values> <value> <datum>1073741824</datum> </value> </values> <vm href="/ovirt-engine/api/vms/123" id="123"/> </statistic>
POST /ovirt-engine/api/jobs/123/steps/456/end
<action> <force>true</force> <succeeded>true</succeeded> </action>
GET /ovirt-engine/api/jobs/123/steps/456
<step href="/ovirt-engine/api/jobs/123/steps/456" id="456"> <actions> <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/> </actions> <description>Validating</description> <end_time>2016-12-12T23:07:26.627+02:00</end_time> <external>false</external> <number>0</number> <start_time>2016-12-12T23:07:26.605+02:00</start_time> <status>finished</status> <type>validating</type> <job href="/ovirt-engine/api/jobs/123" id="123"/> </step>
POST /ovirt-engine/api/jobs/123/steps
<step> <description>Validating</description> <start_time>2016-12-12T23:07:26.605+02:00</start_time> <status>started</status> <type>validating</type> </step>
<step href="/ovirt-engine/api/jobs/123/steps/456" id="456"> <actions> <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/> </actions> <description>Validating</description> <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/> <external>true</external> <number>2</number> <start_time>2016-12-13T01:06:15.380+02:00</start_time> <status>started</status> <type>validating</type> <job href="/ovirt-engine/api/jobs/123" id="123"/> </step>
GET /ovirt-engine/api/job/123/steps
<steps> <step href="/ovirt-engine/api/jobs/123/steps/456" id="456"> <actions> <link href="/ovirt-engine/api/jobs/123/steps/456/end" rel="end"/> </actions> <description>Validating</description> <link href="/ovirt-engine/api/jobs/123/steps/456/statistics" rel="statistics"/> <external>true</external> <number>2</number> <start_time>2016-12-13T01:06:15.380+02:00</start_time> <status>started</status> <type>validating</type> <job href="/ovirt-engine/api/jobs/123" id="123"/> </step> </steps>
<host_storage id="360014051136c20574f743bdbd28177fd"> <logical_units> <logical_unit id="360014051136c20574f743bdbd28177fd"> <lun_mapping>0</lun_mapping> <paths>1</paths> <product_id>lun0</product_id> <serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial> <size>10737418240</size> <status>used</status> <vendor_id>LIO-ORG</vendor_id> <volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-MNzIBZ</volume_group_id> </logical_unit> </logical_units> <type>iscsi</type> <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/> </host_storage>
<host_storage id="360014051136c20574f743bdbd28177fd"> <logical_units> <logical_unit id="360014051136c20574f743bdbd28177fd"> <lun_mapping>0</lun_mapping> <paths>1</paths> <product_id>lun0</product_id> <serial>SLIO-ORG_lun0_1136c205-74f7-43bd-bd28-177fd5ce6993</serial> <size>10737418240</size> <vendor_id>LIO-ORG</vendor_id> <volume_group_id>O9Du7I-RahN-ECe1-dZ1w-nh0b-64io-MNzIBZ</volume_group_id> </logical_unit> </logical_units> <type>iscsi</type> <host id="8bb5ade5-e988-4000-8b93-dbfc6717fe50"/> </host_storage>
POST /ovirt-engine/api/storagedomains/123/reduceluns
<action> <logical_units> <logical_unit id="1IET_00010001"/> <logical_unit id="1IET_00010002"/> </logical_units> </action>
Note that this operation is only applicable to block storage domains (i.e., storage domains with the <<types/storage_type, storage type> of iSCSI or FCP).
POST /ovirt-engine/api/storagedomains/262b056b-aede-40f1-9666-b883eff59d40/refreshluns
<action> <logical_units> <logical_unit id="1IET_00010001"/> <logical_unit id="1IET_00010002"/> </logical_units> </action>
DELETE /ovirt-engine/api/storagedomains/123?destroy=true
DELETE /ovirt-engine/api/storagedomains/123?host=myhost
PUT /ovirt-engine/api/storagedomains/123
<storage_domain> <name>data2</name> <wipe_after_delete>true</wipe_after_delete> </storage_domain>
POST /ovirt-engine/api/storagedomains/123/disks?unregistered=true
<disk id="456"/>
POST /ovirt-engine/api/storagedomains/123/disks
<disk> <name>mydisk</name> <format>cow</format> <provisioned_size>1073741824</provisioned_size> </disk>
GET /ovirt-engine/api/storagedomains/123/disks?unregistered=true
POST /ovirt-engine/api/storagedomains/123/templates/456/import
<action> <storage_domain> <name>myexport</name> </storage_domain> <cluster> <name>mycluster</name> </cluster> </action>
GET /ovirt-engine/api/storagedomains/123/templates?unregistered=true
POST /ovirt-engine/api/storagedomains/123/vms/456/import
<action> <storage_domain> <name>mydata</name> </storage_domain> <cluster> <name>mycluster</name> </cluster> </action>
<action> <storage_domain> <name>mydata</name> </storage_domain> <cluster> <name>mycluster</name> </cluster> <clone>true</clone> <vm> <name>myvm</name> </vm> </action>
<action> <cluster> <name>mycluster</name> </cluster> <vm> <name>myvm</name> </vm> <disks> <disk id="123"/> <disk id="456"/> </disks> </action>
DELETE /ovirt-engine/api/storagedomains/123/vms/456
GET /ovirt-engine/api/storagedomains/123/vms
<vms> <vm id="456" href="/api/storagedomains/123/vms/456"> <name>vm1</name> <storage_domain id="123" href="/api/storagedomains/123"/> <actions> <link rel="import" href="/api/storagedomains/123/vms/456/import"/> </actions> </vm> </vms>
GET /ovirt-engine/api/storagedomains/123/vms?unregistered=true
POST /ovirt-engine/api/storagedomains
<storage_domain> <name>mydata</name> <type>data</type> <storage> <type>nfs</type> <address>mynfs.example.com</address> <path>/exports/mydata</path> </storage> <host> <name>myhost</name> </host> </storage_domain>
<storage_domain> <name>myisos</name> <type>iso</type> <storage> <type>nfs</type> <address>mynfs.example.com</address> <path>/export/myisos</path> </storage> <host> <name>myhost</name> </host> </storage_domain>
<storage_domain> <name>myiscsi</name> <type>data</type> <storage> <type>iscsi</type> <logical_units> <logical_unit id="3600144f09dbd050000004eedbd340001"/> <logical_unit id="3600144f09dbd050000004eedbd340002"/> </logical_units> </storage> <host> <name>myhost</name> </host> </storage_domain>
DELETE /ovirt-engine/api/storageconnections/123?host=456
PUT /ovirt-engine/api/storageconnections/123
<storage_connection> <address>mynewnfs.example.com</address> </storage_connection>
PUT /ovirt-engine/api/storageconnections/123
<storage_connection> <port>3260</port> <target>iqn.2017-01.com.myhost:444</target> </storage_connection>
PUT /ovirt-engine/api/hosts/123/storageconnectionextensions/456
<storage_connection_extension> <target>iqn.2016-01.com.example:mytarget</target> <username>myuser</username> <password>mypassword</password> </storage_connection_extension>
POST /ovirt-engine/api/hosts/123/storageconnectionextensions
<storage_connection_extension> <target>iqn.2016-01.com.example:mytarget</target> <username>myuser</username> <password>mypassword</password> </storage_connection_extension>
POST /ovirt-engine/api/storageconnections
<storage_connection> <type>nfs</type> <address>mynfs.example.com</address> <path>/export/mydata</path> <host> <name>myhost</name> </host> </storage_connection>
GET /ovirt-engine/api
<api> <link rel="capabilities" href="/api/capabilities"/> <link rel="clusters" href="/api/clusters"/> <link rel="clusters/search" href="/api/clusters?search={query}"/> <link rel="datacenters" href="/api/datacenters"/> <link rel="datacenters/search" href="/api/datacenters?search={query}"/> <link rel="events" href="/api/events"/> <link rel="events/search" href="/api/events?search={query}"/> <link rel="hosts" href="/api/hosts"/> <link rel="hosts/search" href="/api/hosts?search={query}"/> <link rel="networks" href="/api/networks"/> <link rel="roles" href="/api/roles"/> <link rel="storagedomains" href="/api/storagedomains"/> <link rel="storagedomains/search" href="/api/storagedomains?search={query}"/> <link rel="tags" href="/api/tags"/> <link rel="templates" href="/api/templates"/> <link rel="templates/search" href="/api/templates?search={query}"/> <link rel="users" href="/api/users"/> <link rel="groups" href="/api/groups"/> <link rel="domains" href="/api/domains"/> <link rel="vmpools" href="/api/vmpools"/> <link rel="vmpools/search" href="/api/vmpools?search={query}"/> <link rel="vms" href="/api/vms"/> <link rel="vms/search" href="/api/vms?search={query}"/> <product_info> <name>oVirt Engine</name> <vendor>ovirt.org</vendor> <version> <build>4</build> <full_version>4.0.4</full_version> <major>4</major> <minor>0</minor> <revision>0</revision> </version> </product_info> <special_objects> <blank_template href="/ovirt-engine/api/templates/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/> <root_tag href="/ovirt-engine/api/tags/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/> </special_objects> <summary> <hosts> <active>0</active> <total>0</total> </hosts> <storage_domains> <active>0</active> <total>1</total> </storage_domains> <users> <active>1</active> <total>1</total> </users> <vms> <active>0</active> <total>0</total> </vms> </summary> <time>2016-09-14T12:00:48.132+02:00</time> </api>
GET /ovirt-engine/api/options/MigrationPoliciesSupported
<system_option href="/ovirt-engine/api/options/MigrationPoliciesSupported" id="MigrationPoliciesSupported"> <name>MigrationPoliciesSupported</name> <values> <system_option_value> <value>true</value> <version>4.0</version> </system_option_value> <system_option_value> <value>true</value> <version>4.1</version> </system_option_value> <system_option_value> <value>true</value> <version>4.2</version> </system_option_value> <system_option_value> <value>false</value> <version>3.6</version> </system_option_value> </values> </system_option>
GET /ovirt-engine/api/options/MigrationPoliciesSupported?version=4.2
<system_option href="/ovirt-engine/api/options/MigrationPoliciesSupported" id="MigrationPoliciesSupported"> <name>MigrationPoliciesSupported</name> <values> <system_option_value> <value>true</value> <version>4.2</version> </system_option_value> </values> </system_option>
POST /ovirt-engine/api/vms/123/permissions
<permission> <role> <name>UserVmManager</name> </role> <user id="456"/> </permission>
POST /ovirt-engine/api/permissions
<permission> <role> <name>SuperUser</name> </role> <user id="456"/> </permission>
POST /ovirt-engine/api/clusters/123/permissions
<permission> <role> <name>UserRole</name> </role> <group id="789"/> </permission>
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>
GET /ovirt-engine/api/tags/123
<tag href="/ovirt-engine/api/tags/123" id="123"> <name>root</name> <description>root</description> </tag>
DELETE /ovirt-engine/api/tags/123
PUT /ovirt-engine/api/tags/123
<tag> <parent id="456"/> </tag>
<tag> <parent> <name>mytag</name> </parent> </tag>
POST /ovirt-engine/api/tags
<tag> <name>mytag</name> </tag>
<tag> <name>mytag</name> <parent> <name>myparenttag</name> </parent> </tag>
GET /ovirt-engine/api/tags
<tags> <tag href="/ovirt-engine/api/tags/222" id="222"> <name>root2</name> <description>root2</description> <parent href="/ovirt-engine/api/tags/111" id="111"/> </tag> <tag href="/ovirt-engine/api/tags/333" id="333"> <name>root3</name> <description>root3</description> <parent href="/ovirt-engine/api/tags/222" id="222"/> </tag> <tag href="/ovirt-engine/api/tags/111" id="111"> <name>root</name> <description>root</description> </tag> </tags>
root: (id: 111) - root2 (id: 222) - root3 (id: 333)
POST /ovirt-engine/api/templates/123/export
<action> <storage_domain id="456"/> <exclusive>true<exclusive/> </action>
DELETE /ovirt-engine/api/templates/123
PUT /ovirt-engine/api/templates/123
<template> <memory>1073741824</memory> </template>
<template> <version> <version_name>mytemplate_2</version_name> </version> </template>
GET /ovirt-engine/api/templates/123/cdroms/
<cdrom href="..." id="00000000-0000-0000-0000-000000000000"> <template href="/ovirt-engine/api/templates/123" id="123"/> <file id="mycd.iso"/> </cdrom>
<cdrom href="..." id="00000000-0000-0000-0000-000000000000"> <template href="/ovirt-engine/api/templates/123" id="123"/> </cdrom>
DELETE /ovirt-engine/api/templates/{template:id}/diskattachments/{attachment:id}?storage_domain=072fbaa1-08f3-4a40-9f34-a5ca22dd1d74
POST /ovirt-engine/api/templates
<template> <name>mytemplate</name> <vm id="123"/> </template>
<template> <name>mytemplate</name> <vm id="123"> <disk_attachments> <disk_attachment> <disk id="456"> <name>mydisk</name> <format>cow</format> <sparse>true</sparse> </disk> </disk_attachment> </disk_attachments> </vm> </template>
<template> <name>mytemplate</name> <vm id="123"/> <version> <base_template id="456"/> <version_name>mytemplate_001</version_name> </version> </template>
<template> <name>mytemplate</name> <storage_domain id="123"/> <vm id="456"> <disk_attachments> <disk_attachment> <disk id="789"> <format>cow</format> <sparse>true</sparse> </disk> </disk_attachment> </disk_attachments> </vm> </template>
<template> <name>mytemplate</name> <vm id="123"> <disk_attachments> <disk_attachment> <disk id="456"> <format>cow</format> <sparse>true</sparse> <storage_domains> <storage_domain id="789"/> </storage_domains> </disk> </disk_attachment> </disk_attachments> </vm> </template>
POST /ovirt-engine/api/templates?clone_permissions=true
<template> <name>mytemplate<name> <vm> <name>myvm<name> </vm> </template>
GET /ovirt-engine/api/templates
GET /ovirt-engine/api/users/1234
<user href="/ovirt-engine/api/users/1234" id="1234"> <name>admin</name> <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/> <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/> <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/> <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/> <department></department> <domain_entry_id>23456</domain_entry_id> <email>user1@domain.com</email> <last_name>Lastname</last_name> <namespace>*</namespace> <principal>user1</principal> <user_name>user1@domain-authz</user_name> <domain href="/ovirt-engine/api/domains/45678" id="45678"> <name>domain-authz</name> </domain> </user>
DELETE /ovirt-engine/api/users/1234
POST /ovirt-engine/api/users
<user> <user_name>myuser@myextension-authz</user_name> <domain> <name>myextension-authz</name> </domain> </user>
<user> <principal>myuser@mysubdomain.mydomain.com</principal> <user_name>myuser@mysubdomain.mydomain.com@myextension-authz</user_name> <domain> <name>myextension-authz</name> </domain> </user>
GET /ovirt-engine/api/users
<users> <user href="/ovirt-engine/api/users/1234" id="1234"> <name>admin</name> <link href="/ovirt-engine/api/users/1234/sshpublickeys" rel="sshpublickeys"/> <link href="/ovirt-engine/api/users/1234/roles" rel="roles"/> <link href="/ovirt-engine/api/users/1234/permissions" rel="permissions"/> <link href="/ovirt-engine/api/users/1234/tags" rel="tags"/> <domain_entry_id>23456</domain_entry_id> <namespace>*</namespace> <principal>user1</principal> <user_name>user1@domain-authz</user_name> <domain href="/ovirt-engine/api/domains/45678" id="45678"> <name>domain-authz</name> </domain> </user> </users>
POST /ovirt-engine/api/vms/123/cancelmigration
<action/>
POST /ovirt-engine/api/vms/123/detach
<action/>
POST /ovirt-engine/api/vms/123/export
<action> <storage_domain> <name>myexport</name> </storage_domain> <exclusive>true</exclusive> <discard_snapshots>true</discard_snapshots> </action>
POST /ovirt-engine/api/vms/123/export
<action> <host> <name>myhost</name> </host> <directory>/home/ovirt</directory> <filename>myvm.ova</filename> </action>
POST /ovirt-engine/api/vms/123/freezefilesystems
<action/>
GET /ovirt-engine/api/vms/123?all_content=true
GET /vms/{vm:id};next_run
GET /vms/{vm:id};next_run=true
POST /ovirt-engine/api/vms/123/logon
<action/>
POST /ovirt-engine/api/vms/123/maintenance
<action> <maintenance_enabled>true<maintenance_enabled/> </action>
POST /ovirt-engine/api/vms/123/migrate
<action> <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/> </action>
POST /ovirt-engine/api/vms/123/previewsnapshot
<action> <disks> <disk id="111"> <image_id>222</image_id> </disk> </disks> <snapshot id="456"/> </action>
POST /ovirt-engine/api/vms/123/reboot
<action/>
DELETE /ovirt-engine/api/vms/123
POST /ovirt-engine/api/vms/123/shutdown
<action/>
POST /ovirt-engine/api/vms/123/start
<action/>
<action> <vm> <os> <boot> <devices> <device>cdrom</device> </devices> </boot> </os> </vm> </action>
POST /ovirt-engine/api/vms/123/stop
<action/>
POST /ovirt-engine/api/vms/123/suspend
<action/>
POST /api/vms/123/thawfilesystems
<action/>
POST /ovirt-engine/api/vms/123/ticket
<action> <ticket> <value>abcd12345</value> <expiry>120</expiry> </ticket> </action>
POST /ovirt-engine/api/vms/123/graphicsconsoles/456/ticket
GET /ovirt-engine/api/vms/123/applications/789
<application href="/ovirt-engine/api/vms/123/applications/789" id="789"> <name>ovirt-guest-agent-common-1.0.12-3.el7</name> <vm href="/ovirt-engine/api/vms/123" id="123"/> </application>
GET /ovirt-engine/api/vms/123/applications/
<applications> <application href="/ovirt-engine/api/vms/123/applications/456" id="456"> <name>kernel-3.10.0-327.36.1.el7</name> <vm href="/ovirt-engine/api/vms/123" id="123"/> </application> <application href="/ovirt-engine/api/vms/123/applications/789" id="789"> <name>ovirt-guest-agent-common-1.0.12-3.el7</name> <vm href="/ovirt-engine/api/vms/123" id="123"/> </application> </applications>
<cdrom href="..." id="00000000-0000-0000-0000-000000000000"> <file id="mycd.iso"/> <vm href="/ovirt-engine/api/vms/123" id="123"/> </cdrom>
<cdrom href="..." id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> </cdrom>
PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000
<cdrom> <file id="mycd.iso"/> </cdrom>
<cdrom> <file id=""/> </cdrom>
PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000?current=true
<cdrom> <file id=""/> </cdrom>
GET /ovit-engine/api/vms/123/graphicsconsoles/456?current=true
POST /ovirt-engine/api/vms/123/graphicsconsoles/456/remoteviewerconnectionfile
<action/>
<action> <remote_viewer_connection_file> [virt-viewer] type=spice host=192.168.1.101 port=-1 password=123456789 delete-this-file=1 fullscreen=0 toggle-fullscreen=shift+f11 release-cursor=shift+f12 secure-attention=ctrl+alt+end tls-port=5900 enable-smartcard=0 enable-usb-autoshare=0 usb-filter=null tls-ciphers=DEFAULT host-subject=O=local,CN=example.com ca= </remote_viewer_connection_file> </action>
Find the virtual machine: vm = vms_service.list(search='name=myvm')[0] Locate the service that manages the virtual machine, as that is where the locators are defined: vm_service = vms_service.vm_service(vm.id) Find the graphic console of the virtual machine: graphics_consoles_service = vm_service.graphics_consoles_service() graphics_console = graphics_consoles_service.list()[0] Generate the remote viewer connection file: console_service = graphics_consoles_service.console_service(graphics_console.id) remote_viewer_connection_file = console_service.remote_viewer_connection_file() Write the content to file "/tmp/remote_viewer_connection_file.vv" path = "/tmp/remote_viewer_connection_file.vv" with open(path, "w") as f: f.write(remote_viewer_connection_file)
#!/bin/sh -ex remote-viewer --ovirt-ca-file=/etc/pki/ovirt-engine/ca.pem /tmp/remote_viewer_connection_file.vv
POST /ovirt-engine/api/vms/123/graphicsconsoles/456/ticket
<action> <ticket> <value>abcd12345</value> <expiry>120</expiry> </ticket> </action>
GET /ovirt-engine/api/vms/123/graphicsconsoles?current=true
GET /ovirt-engine/api/vms/123/hostdevices/456
<host_device href="/ovirt-engine/api/hosts/543/devices/456" id="456"> <name>pci_0000_04_00_0</name> <capability>pci</capability> <iommu_group>30</iommu_group> <placeholder>true</placeholder> <product id="0x13ba"> <name>GM107GL [Quadro K2200]</name> </product> <vendor id="0x10de"> <name>NVIDIA Corporation</name> </vendor> <host href="/ovirt-engine/api/hosts/543" id="543"/> <parent_device href="/ovirt-engine/api/hosts/543/devices/456" id="456"> <name>pci_0000_00_03_0</name> </parent_device> <vm href="/ovirt-engine/api/vms/123" id="123"/> </host_device>
DELETE /ovirt-engine/api/vms/123/hostdevices/456
POST /ovirt-engine/api/vms/123/hostdevices
<host_device id="123" />
DELETE /ovirt-engine/api/vms/123/nics/456
PUT /ovirt-engine/api/vms/123/nics/456
<nic> <name>mynic</name> <interface>e1000</interface> <vnic_profile id='789'/> </nic>
POST /ovirt-engine/api/vms/123/nics
<nic> <name>mynic</name> <interface>virtio</interface> <vnic_profile id="456"/> </nic>
curl --request POST --header "Version: 4" --header "Content-Type: application/xml" --header "Accept: application/xml" --user "admin@internal:mypassword" --cacert /etc/pki/ovirt-engine/ca.pem --data ' <nic> <name>mynic</name> <interface>virtio</interface> <vnic_profile id="456"/> </nic> ' https://myengine.example.com/ovirt-engine/api/vms/123/nics
DELETE /ovirt-engine/api/vms/123/numanodes/456
PUT /ovirt-engine/api/vms/123/numanodes/456
<vm_numa_node> <numa_node_pins> <numa_node_pin> <index>0</index> </numa_node_pin> </numa_node_pins> </vm_numa_node>
POST /ovirt-engine/api/vms/c7ecd2dc/numanodes Accept: application/xml Content-type: application/xml
<vm_numa_node> <cpu> <cores> <core> <index>0</index> </core> </cores> </cpu> <index>0</index> <memory>1024</memory> </vm_numa_node>
POST /ovirt-engine/api/vmpools/123/allocatevm
<action/>
GET /ovirt-engine/api/vmpools/123
<vm_pool id="123"> <actions>...</actions> <name>MyVmPool</name> <description>MyVmPool description</description> <link href="/ovirt-engine/api/vmpools/123/permissions" rel="permissions"/> <max_user_vms>1</max_user_vms> <prestarted_vms>0</prestarted_vms> <size>100</size> <stateful>false</stateful> <type>automatic</type> <use_latest_template_version>false</use_latest_template_version> <cluster id="123"/> <template id="123"/> <vm id="123">...</vm> </vm_pool>
DELETE /ovirt-engine/api/vmpools/123
PUT /ovirt-engine/api/vmpools/123
<vmpool> <name>VM_Pool_B</name> <description>Virtual Machine Pool B</description> <size>3</size> <prestarted_vms>1</size> <max_user_vms>2</size> </vmpool>
POST /ovirt-engine/api/vmpools
<vmpool> <name>mypool</name> <cluster id="123"/> <template id="456"/> </vmpool>
GET /ovirt-engine/api/vmpools
<vm_pools> <vm_pool id="123"> </vm_pool> </vm_pools>
GET /ovirt-engine/api/vms/123/sessions
<sessions> <session href="/ovirt-engine/api/vms/123/sessions/456" id="456"> <console_user>true</console_user> <ip> <address>192.168.122.1</address> </ip> <user href="/ovirt-engine/api/users/789" id="789"/> <vm href="/ovirt-engine/api/vms/123" id="123"/> </session> </sessions>
<watchdogs> <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> <action>poweroff</action> <model>i6300esb</model> </watchdog> </watchdogs>
DELETE /ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000
PUT /ovirt-engine/api/vms/123/watchdogs <watchdog> <action>reset</action> </watchdog>
<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> <action>reset</action> <model>i6300esb</model> </watchdog>
POST /ovirt-engine/api/vms/123/watchdogs <watchdog> <action>poweroff</action> <model>i6300esb</model> </watchdog>
<watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> <action>poweroff</action> <model>i6300esb</model> </watchdog>
<watchdogs> <watchdog href="/ovirt-engine/api/vms/123/watchdogs/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"> <vm href="/ovirt-engine/api/vms/123" id="123"/> <action>poweroff</action> <model>i6300esb</model> </watchdog> </watchdogs>
#!/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 "USD{user}:USD{password}" --request POST --header "Version: 4" --header "Content-Type: application/xml" --header "Accept: application/xml" --data ' <vm> <name>myvm</name> <template> <name>Blank</name> </template> <cluster> <name>mycluster</name> </cluster> </vm> ' "USD{url}/vms"
#!/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 "USD{user}:USD{password}" --request POST --header "Content-Type: application/xml" --header "Accept: application/xml" --data ' <vm> <name>myvm</name> <snapshots> <snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/> </snapshots> <cluster> <name>mycluster</name> </cluster> </vm> ' "USD{url}/vms"
<vm> <disk_attachments> <disk_attachment> <disk id="8d4bd566-6c86-4592-a4a7-912dbf93c298"> <storage_domains> <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/> </storage_domains> </disk> <disk_attachment> </disk_attachments> </vm>
<vm> <disk_attachments> <disk_attachment> <disk> <image_id>8d4bd566-6c86-4592-a4a7-912dbf93c298</image_id> <storage_domains> <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/> </storage_domains> </disk> <disk_attachment> </disk_attachments> </vm>
<vm> <name>myvm</name> <description>My Desktop Virtual Machine</description> <type>desktop</type> <memory>2147483648</memory> </vm>
<vm> <os> <boot dev="cdrom"/> </os> </vm>
<vm> <os> <boot> <devices> <device>cdrom</device> </devices> </boot> </os> </vm>
POST /ovirt-engine/vms?clone=true
<vm> <name>myvm<name> <template> <name>mytemplate<name> </template> <cluster> <name>mycluster<name> </cluster> </vm>
POST /ovirt-engine/api/vms?clone_permissions=true
<vm> <name>myvm<name> <template> <name>mytemplate<name> </template> <cluster> <name>mycluster<name> </cluster> </vm>
GET /ovirt-engine/api/vms?all_content=true
POST /ovirt-engine/api/networks/456/vnicprofiles
<vnic_profile id="123"> <name>new_vNIC_name</name> <pass_through> <mode>disabled</mode> </pass_through> <port_mirroring>false</port_mirroring> </vnic_profile>
<vnic_profile href="/ovirt-engine/api/vnicprofiles/123" id="123"> <name>new_vNIC_name</name> <link href="/ovirt-engine/api/vnicprofiles/123/permissions" rel="permissions"/> <pass_through> <mode>disabled</mode> </pass_through> <port_mirroring>false</port_mirroring> <network href="/ovirt-engine/api/networks/456" id="456"/> <network_filter href="/ovirt-engine/api/networkfilters/789" id="789"/> </vnic_profile>
<vnic_profile> <name>no_network_filter</name> <network_filter/> </vnic_profile>
<vnic_profile> <name>user_choice_network_filter</name> <network_filter id= "0000001b-001b-001b-001b-0000000001d5"/> </vnic_profile>