booleanstringintegerdatedecimalarchitectureundefinedx86_64ppc64logical_unitidstringaddressstringportintegertargetstringusernamestringpasswordstringportalstringserialstringvendor_idstringproduct_idstringlun_mappingintegersizeintegerpathsintegerstatusvolume_group_idstringstorage_domain_idstringdisk_idstringagent_configurationnetwork_mappingsstringbroker_typeaddressstringportintegerusernamestringpasswordstringtime_zonenamestringutc_offsetstringtransparent_huge_pagesenabledbooleanconfiguration_typeovfpayload_encodingbase64plaintextbiosboot_menuboot_menuspmpriorityintegerstatuswatchdogmodelactionidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmbookmarkvaluestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringstorage_connection_extensiontargetstringusernamestringpasswordstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostsnapshot_statusoklockedin_previewip_address_assignmentipipassignment_methodThe enum describes whether vNIC to be implemented as a pass-through device or a virtual one.
Currently it supports only 2 option, but there is a plan to add more in the future.
<div class="paragraph">
<p>The enum describes whether vNIC to be implemented as a pass-through device or a virtual one.
Currently it supports only 2 option, but there is a plan to add more in the future.</p>
</div>
vnic_pass_through_modeTo be implemented as a pass-through device
<div class="paragraph">
<p>To be implemented as a pass-through device</p>
</div>
enabledTo be implemented as a virtual device
<div class="paragraph">
<p>To be implemented as a virtual device</p>
</div>
disabledagenttypestringaddressstringusernamestringpasswordstringoptionsoption[]encrypt_optionsbooleanconcurrentbooleanorderintegerportintegeridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostgluster_volumevolume_typetransport_types[]replica_countintegerstripe_countintegerdisperse_countintegerredundancy_countintegeroptionsoption[]statusidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclusterbricksgluster_brick[]statisticsstatistic[]The OpenStack network provider can either be implemented by OpenStack Neutron, in which case the Neutron
agent is automatically installed on the hosts, or it can be an external provider implementing the
OpenStack API, in which case the virtual interface driver will be a custom solution installed manually.
<div class="paragraph">
<p>The OpenStack network provider can either be implemented by OpenStack Neutron, in which case the Neutron
agent is automatically installed on the hosts, or it can be an external provider implementing the
OpenStack API, in which case the virtual interface driver will be a custom solution installed manually.</p>
</div>
open_stack_network_provider_typeIndicates that the provider is OpenStack Neutron.
The standard OpenStack Neutron agent will be used as the virtual interface driver.
<div class="paragraph">
<p>Indicates that the provider is OpenStack Neutron.
The standard OpenStack Neutron agent will be used as the virtual interface driver.</p>
</div>
neutronIndicates that the provider is an external one, implementing the OpenStack Neutron API.
The virtual interface driver in this case is implemented by the external provider.
<div class="paragraph">
<p>Indicates that the provider is an external one, implementing the OpenStack Neutron API.
The virtual interface driver in this case is implemented by the external provider.</p>
</div>
externaliconmedia_typestringdatastringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringopen_stack_volume_typepropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringopenstack_volume_provideropen_stack_volume_providerThis enumerated type is used to what type of operating system is used by the host.
<div class="paragraph">
<p>This enumerated type is used to what type of operating system is used by the host.</p>
</div>
host_typeThe host contains a full RHEL, CentOS or Fedora installation.
<div class="paragraph">
<p>The host contains a full RHEL, CentOS or Fedora installation.</p>
</div>
rhelThe host contains a small scaled version of RHEL, CentOS or Fedora, used solely to host virtual machines.
<div class="paragraph">
<p>The host contains a small scaled version of RHEL, CentOS or Fedora, used solely to host virtual machines.</p>
</div>
rhev_hThe host is NGN (Next Generation Node) - a new implementation of RHEV_H which is like RHEL, CentOS or Fedora installation.
The main difference between NGN and legacy RHEV-H is that NGN has a writeable file system and will handle its installation
instead of pushing RPMs to it by the engine in legacy RHEV-H.
<div class="paragraph">
<p>The host is NGN (Next Generation Node) - a new implementation of RHEV_H which is like RHEL, CentOS or Fedora installation.
The main difference between NGN and legacy RHEV-H is that NGN has a writeable file system and will handle its installation
instead of pushing RPMs to it by the engine in legacy RHEV-H.</p>
</div>
ovirt_nodeDescribes how a disk is attached to a virtual machine.
<div class="paragraph">
<p>Describes how a disk is attached to a virtual machine.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue2 Nov 2016statusvalueupdated_by_docsdisk_attachmentDefines whether the disk is bootable.
<div class="paragraph">
<p>Defines whether the disk is bootable.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue2 Nov 2016statusvalueupdated_by_docsbootablebooleanThe type of interface driver used to connect the disk device to the virtual machine.
<div class="paragraph">
<p>The type of interface driver used to connect the disk device to the virtual machine.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedinterfaceThis flag indicates if the disk is active in the virtual machine it's attached to.
A disk attached to a virtual machine in an active status is connected to the virtual machine at run time and
can be used.
<div class="paragraph">
<p>This flag indicates if the disk is active in the virtual machine it’s attached to.</p>
</div>
<div class="paragraph">
<p>A disk attached to a virtual machine in an active status is connected to the virtual machine at run time and
can be used.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue3 Nov 2016statusvalueupdated_by_docsactivebooleanThe logical name of the virtual machine's disk, as seen from inside the virtual machine.
The logical name of a disk is reported only when the guest agent is installed and running inside the virtual
machine.
For example, if the guest operating system is Linux and the disk is connected via a VirtIO interface, the
logical name will be reported as `/dev/vda`:
[source,xml]
----
<disk_attachment>
...
<logical_name>/dev/vda</logical_name>
</disk_attachment>
----
If the guest operating system is Windows, the logical name will be reported as `\\.\PHYSICALDRIVE0`.
<div class="paragraph">
<p>The logical name of the virtual machine’s disk, as seen from inside the virtual machine.</p>
</div>
<div class="paragraph">
<p>The logical name of a disk is reported only when the guest agent is installed and running inside the virtual
machine.</p>
</div>
<div class="paragraph">
<p>For example, if the guest operating system is Linux and the disk is connected via a VirtIO interface, the
logical name will be reported as <code>/dev/vda</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><disk_attachment>
...
<logical_name>/dev/vda</logical_name>
</disk_attachment></code></pre>
</div>
</div>
<div class="paragraph">
<p>If the guest operating system is Windows, the logical name will be reported as <code>\\.\PHYSICALDRIVE0</code>.</p>
</div>
authorvalueIdan Shaby <ishaby@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue3 Nov 2016statusvalueupdated_by_docssincevalue4.0.2logical_namestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringThe reference to the disk.
<div class="paragraph">
<p>The reference to the disk.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue3 Nov 2016statusvalueupdated_by_docsdiskdiskThe reference to the virtual machine.
<div class="paragraph">
<p>The reference to the virtual machine.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue3 Nov 2016statusvalueupdated_by_docsvmvmThe reference to the template.
<div class="paragraph">
<p>The reference to the template.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue3 Nov 2016statusvalueupdated_by_docstemplatetemplatelog_severitynormalwarningerroralertopen_stack_image_providertenant_namestringurlstringrequires_authenticationbooleanusernamestringpasswordstringauthentication_urlstringpropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringcertificatescertificate[]imagesopen_stack_image[]open_stack_networkidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringopenstack_network_provideropen_stack_network_providerwatchdog_modeli6300esbvm_statusunassigneddownuppowering_uppausedmigratingunknownnot_respondingwait_for_launchreboot_in_progresssaving_staterestoring_statesuspendedimage_lockedpowering_downrng_devicerateratesourcegraphics_typespicevncdisk_storage_typeimageluncinderopen_stack_subnetcidrstringip_versionstringgatewaystringdns_serversstring[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringopenstack_networkopen_stack_networkvm_pool_typeautomaticmanualnuma_tune_modestrictinterleavepreferredThis type contains references to special objects, like the blank template and the root of the hierarchy of tags.
<div class="paragraph">
<p>This type contains references to special objects, like the blank template and the root of the hierarchy of tags.</p>
</div>
special_objectsReference to the blank template.
<div class="paragraph">
<p>Reference to the blank template.</p>
</div>
blank_templatetemplateReference to the root of the hierarchy of tags.
<div class="paragraph">
<p>Reference to the root of the hierarchy of tags.</p>
</div>
root_tagtagboot_devicecdromhdnetworkuserdomain_entry_idstringdepartmentstringlogged_inbooleanName space where user resides. When using the authorization provider that stores users in the LDAP
(see https://github.com/oVirt/ovirt-engine-extension-aaa-ldap[here] for details) this attribute equals to naming
context of the LDAP. When using the built-in authorization provider that stores users in the database
(see https://github.com/oVirt/ovirt-engine-extension-aaa-jdbc[here] for details) this attribute is ignored.
<div class="paragraph">
<p>Name space where user resides. When using the authorization provider that stores users in the LDAP
(see <a href="https://github.com/oVirt/ovirt-engine-extension-aaa-ldap">here</a> for details) this attribute equals to naming
context of the LDAP. When using the built-in authorization provider that stores users in the database
(see <a href="https://github.com/oVirt/ovirt-engine-extension-aaa-jdbc">here</a> for details) this attribute is ignored.</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddednamespacestringlast_namestringUsername of the user. The format depends on authorization provider type. In case of most LDAP providers it is
value of the `uid` LDAP attribute. In case of Active Directory it is the user principal name (UPN). `UPN` or
`uid` must be followed by authorization provider name. For example in case of LDAP using `uid` attribute it is:
`myuser@myextension-authz`. In case of Active Directory using `UPN` it is:
`myuser@mysubdomain.mydomain.com@myextension-authz`. This attribute is required parameter when adding new user.
<div class="paragraph">
<p>Username of the user. The format depends on authorization provider type. In case of most LDAP providers it is
value of the <code>uid</code> LDAP attribute. In case of Active Directory it is the user principal name (UPN). <code>UPN</code> or
<code>uid</code> must be followed by authorization provider name. For example in case of LDAP using <code>uid</code> attribute it is:
<code>myuser@myextension-authz</code>. In case of Active Directory using <code>UPN</code> it is:
<code>myuser@mysubdomain.mydomain.com@myextension-authz</code>. This attribute is required parameter when adding new user.</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddeduser_namestringSame as `user_name` principal has different formats based on LDAP provider. In case of most LDAP providers it is
value of the `uid` LDAP attribute. In case of Active Directory it is the user principal name (UPN).
<div class="paragraph">
<p>Same as <code>user_name</code> principal has different formats based on LDAP provider. In case of most LDAP providers it is
value of the <code>uid</code> LDAP attribute. In case of Active Directory it is the user principal name (UPN).</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddedprincipalstringpasswordstringemailstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringdomaindomainrolesrole[]groupsgroup[]permissionspermission[]tagstag[]ssh_public_keysssh_public_key[]job_statusabortedfailedfinishedstartedunknownRepresents a physical NUMA node.
Example XML representation:
[source,xml]
----
<host_numa_node href="/ovirt-engine/api/hosts/0923f1ea/numanodes/007cf1ab" id="007cf1ab">
<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>65536</memory>
<node_distance>40 20 40 10</node_distance>
<host href="/ovirt-engine/api/hosts/0923f1ea" id="0923f1ea"/>
</host_numa_node>
----
<div class="paragraph">
<p>Represents a physical NUMA node.</p>
</div>
<div class="paragraph">
<p>Example XML representation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><host_numa_node href="/ovirt-engine/api/hosts/0923f1ea/numanodes/007cf1ab" id="007cf1ab">
<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>65536</memory>
<node_distance>40 20 40 10</node_distance>
<host href="/ovirt-engine/api/hosts/0923f1ea" id="0923f1ea"/>
</host_numa_node></code></pre>
</div>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddednuma_nodeindexintegerMemory of the NUMA node in MB.
<div class="paragraph">
<p>Memory of the NUMA node in MB.</p>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedmemoryintegercpucpunode_distancestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthoststatisticsstatistic[]memory_policyguaranteedintegerballooningbooleanover_commitmemory_over_committransparent_huge_pagestransparent_huge_pagesmemory_over_commitpercentintegerimageidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringstorage_domainstorage_domainkdump_statusunknowndisabledenabledRepresents a MAC address pool.
Example of a XML representatian of a MAC address pool:
[source,xml]
----
<mac_pool href="/ovirt-engine/api/macpools/123" id="123">
<name>Default</name>
<description>Default MAC pool</description>
<allow_duplicates>false</allow_duplicates>
<default_pool>true</default_pool>
<ranges>
<range>
<from>00:1A:4A:16:01:51</from>
<to>00:1A:4A:16:01:E6</to>
</range>
</ranges>
</mac_pool>
----
<div class="paragraph">
<p>Represents a MAC address pool.</p>
</div>
<div class="paragraph">
<p>Example of a XML representatian of a MAC address pool:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><mac_pool href="/ovirt-engine/api/macpools/123" id="123">
<name>Default</name>
<description>Default MAC pool</description>
<allow_duplicates>false</allow_duplicates>
<default_pool>true</default_pool>
<ranges>
<range>
<from>00:1A:4A:16:01:51</from>
<to>00:1A:4A:16:01:E6</to>
</range>
</ranges>
</mac_pool></code></pre>
</div>
</div>
authorvalueMarcin Mirecki <mmirecki@redhat.com>datevalue14 Sept 2016statusvalueaddedmac_poolDefines whether duplicate MAC addresses are permitted in the pool. If not specified defaults to `false`.
<div class="paragraph">
<p>Defines whether duplicate MAC addresses are permitted in the pool. If not specified defaults to <code>false</code>.</p>
</div>
authorvalueMarcin Mirecki <mmirecki@redhat.com>datevalue22 Sept 2016statusvalueaddedallow_duplicatesbooleanDefines whether this is the default pool. If not specified defaults to `false`.
<div class="paragraph">
<p>Defines whether this is the default pool. If not specified defaults to <code>false</code>.</p>
</div>
authorvalueMarcin Mirecki <mmirecki@redhat.com>datevalue22 Sept 2016statusvalueaddeddefault_poolbooleanDefines the range of MAC addresses for the pool. Multiple ranges can be defined.
<div class="paragraph">
<p>Defines the range of MAC addresses for the pool. Multiple ranges can be defined.</p>
</div>
authorvalueMarcin Mirecki <mmirecki@redhat.com>datevalue22 Sept 2016statusvalueaddedrangesrange[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringse_linux_modeenforcingpermissivedisabledAffinity label is a label that can influence the VM scheduling.
It is most often used to create a sub-cluster from available hosts.
<div class="paragraph">
<p>Affinity label is a label that can influence the VM scheduling.
It is most often used to create a sub-cluster from available hosts.</p>
</div>
affinity_labelThe `readOnly` property marks a label that can't be modified.
This is mostly the case when listing internally generated labels.
<div class="paragraph">
<p>The <code>readOnly</code> property marks a label that can’t be modified.
This is mostly the case when listing internally generated labels.</p>
</div>
read_onlybooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringList of hosts that were labeled using this scheduling label.
<div class="paragraph">
<p>List of hosts that were labeled using this scheduling label.</p>
</div>
hostshost[]List of vms that were labeled using this scheduling label.
<div class="paragraph">
<p>List of vms that were labeled using this scheduling label.</p>
</div>
vmsvm[]access_protocolglusternfscifsscheduling_policylockedbooleandefault_policybooleanpropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringbalancesbalance[]filtersfilter[]weightweight[]openstack_volume_authentication_keyuuidstringvaluestringusage_typecreation_datedateidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringopenstack_volume_provideropen_stack_volume_providerrangefromstringtostringpermissionidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringroleroleuserusergroupgroupdata_centerdata_centerclusterclusterhosthoststorage_domainstorage_domainvmvmvm_poolvm_pooltemplatetemplatediskdiskDefines the bandwidth used by migration.
<div class="paragraph">
<p>Defines the bandwidth used by migration.</p>
</div>
migration_bandwidthThe way how the bandwidth is assigned.
<div class="paragraph">
<p>The way how the bandwidth is assigned.</p>
</div>
assignment_methodCustom bandwidth in Mbit/s. Will be applied only if the `assignmentMethod` attribute is `custom`.
<div class="paragraph">
<p>Custom bandwidth in Mbit/s. Will be applied only if the <code>assignmentMethod</code> attribute is <code>custom</code>.</p>
</div>
custom_valueintegerentity_profile_detailprofile_detailsprofile_detail[]ssh_public_keycontentstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringuseruserRepresents virtual NUMA node.
An example XML representation:
[source, xml]
----
<vm_numa_node href="/ovirt-engine/api/vms/f1aa8209/numanodes/706cb6b0" id="706cb6b0">
<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>1024</memory>
<numa_node_pins>
<numa_node_pin>
<host_numa_node id="007cf1ab"/>
<index>0</index>
<pinned>true</pinned>
</numa_node_pin>
</numa_node_pins>
<vm href="/ovirt-engine/api/vms/f1aa8209" id="f1aa8209"/>
</vm_numa_node>
----
<div class="paragraph">
<p>Represents virtual NUMA node.</p>
</div>
<div class="paragraph">
<p>An example XML representation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm_numa_node href="/ovirt-engine/api/vms/f1aa8209/numanodes/706cb6b0" id="706cb6b0">
<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>1024</memory>
<numa_node_pins>
<numa_node_pin>
<host_numa_node id="007cf1ab"/>
<index>0</index>
<pinned>true</pinned>
</numa_node_pin>
</numa_node_pins>
<vm href="/ovirt-engine/api/vms/f1aa8209" id="f1aa8209"/>
</vm_numa_node></code></pre>
</div>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedvirtual_numa_nodenuma_node_pinsnuma_node_pin[]indexintegerMemory of the NUMA node in MB.
<div class="paragraph">
<p>Memory of the NUMA node in MB.</p>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedmemoryintegercpucpunode_distancestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthoststatisticsstatistic[]vmvmstatisticvaluesvalue[]kindtypeunitidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringdiskdiskhosthosthost_nichost_nichost_numa_nodenuma_nodenicnicvmvmbrickgluster_brickstepstepgluster_volumegluster_volumeThe enum defines valid values for the IP protocol version.
<div class="paragraph">
<p>The enum defines valid values for the IP protocol version.</p>
</div>
ip_versionIPv4.
<div class="paragraph">
<p>IPv4.</p>
</div>
v4IPv6.
<div class="paragraph">
<p>IPv6.</p>
</div>
v6serial_numberpolicyvaluestringksmenabledbooleanmerge_across_nodesbooleanhook_content_typetextbinarydisk_interfaceidevirtio_scsivirtiospapr_vscsivolume_groupidstringnamestringlogical_unitslogical_unit[]skip_if_connectivity_brokenenabledbooleanthresholdintegerauto_numa_statusdisableenableunknowndisk_typedatasystemvnic_pass_throughDefines if the vNIC to be implemented as a virtual device or as a pass-through to a host device.
<div class="paragraph">
<p>Defines if the vNIC to be implemented as a virtual device or as a pass-through to a host device.</p>
</div>
modebrick_profile_detailprofile_detailsprofile_detail[]brickgluster_bricknetwork_statusoperationalnon_operationalnic_interfacee1000virtiortl8139rtl8139_virtiospapr_vlanpci_passthroughvalue_typedecimalintegerstringresolution_typeaddcopyiscsi_detailsinitiatorstringportintegertargetstringusernamestringpasswordstringportalstringaddressstringserialstringvendor_idstringproduct_idstringlun_mappingintegersizeintegerpathsintegerstatusstringvolume_group_idstringstorage_domain_idstringdisk_idstringvcpu_pinvcpuintegercpu_setstringconfigurationtypeThe document describing the virtual machine.
Example of the OVF document:
[source,xml]
----
<?xml version='1.0' encoding='UTF-8'?>
<ovf:Envelope xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1/"
xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData"
xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
ovf:version="3.5.0.0">
<References/>
<Section xsi:type="ovf:NetworkSection_Type">
<Info>List of networks</Info>
<Network ovf:name="Network 1"/>
</Section>
<Section xsi:type="ovf:DiskSection_Type">
<Info>List of Virtual Disks</Info>
</Section>
<Content ovf:id="out" xsi:type="ovf:VirtualSystem_Type">
<CreationDate>2014/12/03 04:25:45</CreationDate>
<ExportDate>2015/02/09 14:12:24</ExportDate>
<DeleteProtected>false</DeleteProtected>
<SsoMethod>guest_agent</SsoMethod>
<IsSmartcardEnabled>false</IsSmartcardEnabled>
<TimeZone>Etc/GMT</TimeZone>
<default_boot_sequence>0</default_boot_sequence>
<Generation>1</Generation>
<VmType>1</VmType>
<MinAllocatedMem>1024</MinAllocatedMem>
<IsStateless>false</IsStateless>
<IsRunAndPause>false</IsRunAndPause>
<AutoStartup>false</AutoStartup>
<Priority>1</Priority>
<CreatedByUserId>fdfc627c-d875-11e0-90f0-83df133b58cc</CreatedByUserId>
<IsBootMenuEnabled>false</IsBootMenuEnabled>
<IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled>
<IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled>
<Name>VM_export</Name>
<TemplateId>00000000-0000-0000-0000-000000000000</TemplateId>
<TemplateName>Blank</TemplateName>
<IsInitilized>false</IsInitilized>
<Origin>3</Origin>
<DefaultDisplayType>1</DefaultDisplayType>
<TrustedService>false</TrustedService>
<OriginalTemplateId>00000000-0000-0000-0000-000000000000</OriginalTemplateId>
<OriginalTemplateName>Blank</OriginalTemplateName>
<UseLatestVersion>false</UseLatestVersion>
<Section ovf:id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a"
ovf:required="false"
xsi:type="ovf:OperatingSystemSection_Type">
<Info>Guest Operating System</Info>
<Description>other</Description>
</Section>
<Section xsi:type="ovf:VirtualHardwareSection_Type">
<Info>1 CPU, 1024 Memeory</Info>
<System>
<vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType>
</System>
<Item>
<rasd:Caption>1 virtual cpu</rasd:Caption>
<rasd:Description>Number of virtual CPU</rasd:Description>
<rasd:InstanceId>1</rasd:InstanceId>
<rasd:ResourceType>3</rasd:ResourceType>
<rasd:num_of_sockets>1</rasd:num_of_sockets>
<rasd:cpu_per_socket>1</rasd:cpu_per_socket>
</Item>
<Item>
<rasd:Caption>1024 MB of memory</rasd:Caption>
<rasd:Description>Memory Size</rasd:Description>
<rasd:InstanceId>2</rasd:InstanceId>
<rasd:ResourceType>4</rasd:ResourceType>
<rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits>
<rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
</Item>
<Item>
<rasd:Caption>USB Controller</rasd:Caption>
<rasd:InstanceId>3</rasd:InstanceId>
<rasd:ResourceType>23</rasd:ResourceType>
<rasd:UsbPolicy>DISABLED</rasd:UsbPolicy>
</Item>
</Section>
</Content>
</ovf:Envelope>
----
<div class="paragraph">
<p>The document describing the virtual machine.</p>
</div>
<div class="paragraph">
<p>Example of the OVF document:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><?xml version='1.0' encoding='UTF-8'?>
<ovf:Envelope xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1/"
xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData"
xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
ovf:version="3.5.0.0">
<References/>
<Section xsi:type="ovf:NetworkSection_Type">
<Info>List of networks</Info>
<Network ovf:name="Network 1"/>
</Section>
<Section xsi:type="ovf:DiskSection_Type">
<Info>List of Virtual Disks</Info>
</Section>
<Content ovf:id="out" xsi:type="ovf:VirtualSystem_Type">
<CreationDate>2014/12/03 04:25:45</CreationDate>
<ExportDate>2015/02/09 14:12:24</ExportDate>
<DeleteProtected>false</DeleteProtected>
<SsoMethod>guest_agent</SsoMethod>
<IsSmartcardEnabled>false</IsSmartcardEnabled>
<TimeZone>Etc/GMT</TimeZone>
<default_boot_sequence>0</default_boot_sequence>
<Generation>1</Generation>
<VmType>1</VmType>
<MinAllocatedMem>1024</MinAllocatedMem>
<IsStateless>false</IsStateless>
<IsRunAndPause>false</IsRunAndPause>
<AutoStartup>false</AutoStartup>
<Priority>1</Priority>
<CreatedByUserId>fdfc627c-d875-11e0-90f0-83df133b58cc</CreatedByUserId>
<IsBootMenuEnabled>false</IsBootMenuEnabled>
<IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled>
<IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled>
<Name>VM_export</Name>
<TemplateId>00000000-0000-0000-0000-000000000000</TemplateId>
<TemplateName>Blank</TemplateName>
<IsInitilized>false</IsInitilized>
<Origin>3</Origin>
<DefaultDisplayType>1</DefaultDisplayType>
<TrustedService>false</TrustedService>
<OriginalTemplateId>00000000-0000-0000-0000-000000000000</OriginalTemplateId>
<OriginalTemplateName>Blank</OriginalTemplateName>
<UseLatestVersion>false</UseLatestVersion>
<Section ovf:id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a"
ovf:required="false"
xsi:type="ovf:OperatingSystemSection_Type">
<Info>Guest Operating System</Info>
<Description>other</Description>
</Section>
<Section xsi:type="ovf:VirtualHardwareSection_Type">
<Info>1 CPU, 1024 Memeory</Info>
<System>
<vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType>
</System>
<Item>
<rasd:Caption>1 virtual cpu</rasd:Caption>
<rasd:Description>Number of virtual CPU</rasd:Description>
<rasd:InstanceId>1</rasd:InstanceId>
<rasd:ResourceType>3</rasd:ResourceType>
<rasd:num_of_sockets>1</rasd:num_of_sockets>
<rasd:cpu_per_socket>1</rasd:cpu_per_socket>
</Item>
<Item>
<rasd:Caption>1024 MB of memory</rasd:Caption>
<rasd:Description>Memory Size</rasd:Description>
<rasd:InstanceId>2</rasd:InstanceId>
<rasd:ResourceType>4</rasd:ResourceType>
<rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits>
<rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
</Item>
<Item>
<rasd:Caption>USB Controller</rasd:Caption>
<rasd:InstanceId>3</rasd:InstanceId>
<rasd:ResourceType>23</rasd:ResourceType>
<rasd:UsbPolicy>DISABLED</rasd:UsbPolicy>
</Item>
</Section>
</Content>
</ovf:Envelope></code></pre>
</div>
</div>
authorvalueShmuel Melamud <smelamud@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue4 Nov 2016statusvalueupdated_by_docsdatastringdeviceidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmskip_if_sd_activeenabledbooleanse_linuxmodeusbenabledbooleantypeRepresents pinning of a virtual NUMA node to a physical NUMA node.
<div class="paragraph">
<p>Represents pinning of a virtual NUMA node to a physical NUMA node.</p>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddednuma_node_pinDeprecated - has no function.
<div class="paragraph">
<p>Deprecated - has no function.</p>
</div>
deprecatedauthorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedhost_numa_nodenuma_nodeDeprecated - should always be true.
<div class="paragraph">
<p>Deprecated - should always be true.</p>
</div>
deprecatedauthorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedpinnedbooleanIndex of a physical NUMA node to which the virtual NUMA node is pinned.
<div class="paragraph">
<p>Index of a physical NUMA node to which the virtual NUMA node is pinned.</p>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedindexintegerhost_protocolxmlstomperror_handlingon_errorexternal_host_grouparchitecture_namestringoperating_system_namestringdomain_namestringsubnet_namestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringexternal_host_providerexternal_host_providertemplate_statusillegallockedokssomethodsmethod[]vm_affinitymigratableuser_migratablepinnedpayloadfilesfile[]volume_idstringtypekernelversionversionmessage_broker_typeqpidrabbit_mqgluster_stateupdownunknowndisplay_typevncspicemigration_optionsauto_convergecompressedThe bandwidth which is allowed to be used by the migrations.
<div class="paragraph">
<p>The bandwidth which is allowed to be used by the migrations.</p>
</div>
bandwidthmigration_bandwidthReference to the migration policy as defined using `engine-config`.
<div class="paragraph">
<p>Reference to the migration policy as defined using <code>engine-config</code>.</p>
</div>
policymigration_policycpu_tunevcpu_pinsvcpu_pin[]open_stack_providertenant_namestringurlstringrequires_authenticationbooleanusernamestringpasswordstringauthentication_urlstringpropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringmethodidRepresents a host NIC.
For example, the XML representation of a host NIC looks like this:
[source,xml]
----
<host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456">
<name>eth0</name>
<boot_protocol>static</boot_protocol>
<bridged>true</bridged>
<custom_configuration>true</custom_configuration>
<ip>
<address>192.168.122.39</address>
<gateway>192.168.122.1</gateway>
<netmask>255.255.255.0</netmask>
<version>v4</version>
</ip>
<ipv6>
<gateway>::</gateway>
<version>v6</version>
</ipv6>
<ipv6_boot_protocol>none</ipv6_boot_protocol>
<mac>
<address>52:54:00:0c:79:1d</address>
</mac>
<mtu>1500</mtu>
<status>up</status>
</host_nic>
----
<div class="paragraph">
<p>Represents a host NIC.</p>
</div>
<div class="paragraph">
<p>For example, the XML representation of a host NIC looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456">
<name>eth0</name>
<boot_protocol>static</boot_protocol>
<bridged>true</bridged>
<custom_configuration>true</custom_configuration>
<ip>
<address>192.168.122.39</address>
<gateway>192.168.122.1</gateway>
<netmask>255.255.255.0</netmask>
<version>v4</version>
</ip>
<ipv6>
<gateway>::</gateway>
<version>v6</version>
</ipv6>
<ipv6_boot_protocol>none</ipv6_boot_protocol>
<mac>
<address>52:54:00:0c:79:1d</address>
</mac>
<mtu>1500</mtu>
<status>up</status>
</host_nic></code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedhost_nicThe MAC address of the NIC.
<div class="paragraph">
<p>The MAC address of the NIC.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedmacmacipipipv6ipbase_interfacestringvlanvlanbondingbondingboot_protocolipv6_boot_protocolA link to the statistics of the NIC.
<div class="paragraph">
<p>A link to the statistics of the NIC.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedstatisticsstatistic[]check_connectivitybooleanspeedintegerstatusmtuintegerbridgedbooleancustom_configurationbooleanoverride_configurationbooleannetwork_labelsnetwork_label[]propertiesproperty[]The `ad_aggregator_id` property of a bond or bond slave, for bonds in mode 4.
Bond mode 4 is the 802.3ad standard, also called dynamic link aggregation -
https://en.wikipedia.org/wiki/Link_aggregation[Wikipedia]
http://www.ieee802.org/3/hssg/public/apr07/frazier_01_0407.pdf[Presentation].
This is only valid for bonds in mode 4, or NICs (NIC - network interface card) which are part of a bond.
It is not present for bonds in other modes, or NICs which are not part in a bond in mode 4.
The `ad_aggregator_id` property indicates which of the bond slaves are active. The value of the
`ad_aggregator_id` of an active slave is the same the value of the `ad_aggregator_id` property of the bond.
This parameter is read only. Setting it will have no effect on the bond/NIC.
It is retrieved from `/sys/class/net/bondX/bonding/ad_aggregator` file for a bond, and the
`/sys/class/net/ensX/bonding_slave/ad_aggregator_id` file for a NIC.
<div class="paragraph">
<p>The <code>ad_aggregator_id</code> property of a bond or bond slave, for bonds in mode 4.
Bond mode 4 is the 802.3ad standard, also called dynamic link aggregation -
<a href="https://en.wikipedia.org/wiki/Link_aggregation">Wikipedia</a>
<a href="http://www.ieee802.org/3/hssg/public/apr07/frazier_01_0407.pdf">Presentation</a>.
This is only valid for bonds in mode 4, or NICs (NIC - network interface card) which are part of a bond.
It is not present for bonds in other modes, or NICs which are not part in a bond in mode 4.
The <code>ad_aggregator_id</code> property indicates which of the bond slaves are active. The value of the
<code>ad_aggregator_id</code> of an active slave is the same the value of the <code>ad_aggregator_id</code> property of the bond.
This parameter is read only. Setting it will have no effect on the bond/NIC.
It is retrieved from <code>/sys/class/net/bondX/bonding/ad_aggregator</code> file for a bond, and the
<code>/sys/class/net/ensX/bonding_slave/ad_aggregator_id</code> file for a NIC.</p>
</div>
authorvalueMarcin Mirecki <mmirecki@redhat.com>datevalue10 Aug 2016statusvalueaddedsincevalue4.0.3ad_aggregator_idintegerFor a SR-IOV physical function NIC describes its virtual functions configuration.
<div class="paragraph">
<p>For a SR-IOV physical function NIC describes its virtual functions configuration.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedvirtual_functions_configurationhost_nic_virtual_functions_configurationidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostA reference to the network which the interface should be connected. A blank network id is allowed.
<div class="paragraph">
<p>A reference to the network which the interface should be connected. A blank network id is allowed.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednetworknetworkqosqosFor a SR-IOV virtual function NIC references to its physical function NIC.
<div class="paragraph">
<p>For a SR-IOV virtual function NIC references to its physical function NIC.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedphysical_functionhost_nicoperating_system_infolarge_iconiconsmall_iconiconidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringjobstatusstart_timedateend_timedatelast_updateddateexternalbooleanauto_clearedbooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringowneruserstepsstep[]Describes virtual functions configuration for an SR-IOV enabled physical function NIC.
<div class="paragraph">
<p>Describes virtual functions configuration for an SR-IOV enabled physical function NIC.</p>
</div>
host_nic_virtual_functions_configurationMaximum number of virtual functions the NIC supports. Read-only property.
<div class="paragraph">
<p>Maximum number of virtual functions the NIC supports. Read-only property.</p>
</div>
max_number_of_virtual_functionsintegerNumber of curently defined virtual functions. User-defined value between 0 and `maxNumberOfVirtualFunctions`.
<div class="paragraph">
<p>Number of curently defined virtual functions. User-defined value between 0 and <code>maxNumberOfVirtualFunctions</code>.</p>
</div>
number_of_virtual_functionsintegerDefines whether all networks are allowed to be defined on the related virtual functions or specified ones only.
<div class="paragraph">
<p>Defines whether all networks are allowed to be defined on the related virtual functions or specified ones only.</p>
</div>
all_networks_allowedbooleanweightfactorintegeridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringscheduling_policyscheduling_policyscheduling_policy_unitscheduling_policy_unitopen_stack_network_providerplugin_typeagent_configurationagent_configurationIndicates whether the provider is read only.
A read-only provider does not allow adding, modifying or deleting of
networks or subnets.
Port-related operations are allowed, as they are required for the
provisioning of virtual nics.
<div class="paragraph">
<p>Indicates whether the provider is read only.
A read-only provider does not allow adding, modifying or deleting of
networks or subnets.
Port-related operations are allowed, as they are required for the
provisioning of virtual nics.</p>
</div>
read_onlybooleanThe type of provider.
<div class="paragraph">
<p>The type of provider.</p>
</div>
typetenant_namestringurlstringrequires_authenticationbooleanusernamestringpasswordstringauthentication_urlstringpropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringcertificatescertificate[]networksopen_stack_network[]subnetsopen_stack_subnet[]reported_devicetypemacmacipsip[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringvmvmquota_cluster_limitvcpu_limitintegervcpu_usageintegermemory_limitdecimalmemory_usagedecimalidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringquotaquotaclusterclusterrolemutablebooleanadministrativebooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringuseruserpermitspermit[]network_attachmentip_address_assignmentsip_address_assignment[]propertiesproperty[]in_syncbooleanreported_configurationsreported_configuration[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringnetworknetworkhost_nichost_nichosthostqosqosA list of possible phases for an <<types/image_transfer, image transfer>> entity. Each of these values
defines a specific point in a transfer flow.
Please refer to <<services/image_transfer, image transfer>> for further
documentation.
<div class="paragraph">
<p>A list of possible phases for an <a href="#types/image_transfer">image transfer</a> entity. Each of these values
defines a specific point in a transfer flow.</p>
</div>
<div class="paragraph">
<p>Please refer to <a href="#services/image_transfer">image transfer</a> for further
documentation.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4image_transfer_phaseAn unknown phase, will only be set in cases of unpredictable errors.
<div class="paragraph">
<p>An unknown phase, will only be set in cases of unpredictable errors.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4unknownThe initial phase of an added image transfer. It is set as long as the transfer session is establishing.
Once the session is established, the phase will be changed to `transferring`
<div class="paragraph">
<p>The initial phase of an added image transfer. It is set as long as the transfer session is establishing.
Once the session is established, the phase will be changed to <code>transferring</code></p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4initializingThe phase where the transfer session is open, and the client can do I/O to the desired image using its preferred
tools.
<div class="paragraph">
<p>The phase where the transfer session is open, and the client can do I/O to the desired image using its preferred
tools.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4transferringThe phase where the transfer had been resumed by the client calling
<<services/image_transfer/methods/resume, resume>>. Resuming will start a new session, and after calling it,
the phase should be changed to `transferring`, or `paused_system` in case of a failure.
<div class="paragraph">
<p>The phase where the transfer had been resumed by the client calling
<a href="#services/image_transfer/methods/resume">resume</a>. Resuming will start a new session, and after calling it,
the phase should be changed to <code>transferring</code>, or <code>paused_system</code> in case of a failure.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4resumingThis phase stands for a situation in which the session was timed out, or if some other error occurred
with this transfer, e.g, ovirt-imageio-daemon is not running in the selected host for transferring. For trying
to resume the session, the client should call <<services/image_transfer/methods/resume, resume>>. After
resuming, the phase will change to `resuming`
<div class="paragraph">
<p>This phase stands for a situation in which the session was timed out, or if some other error occurred
with this transfer, e.g, ovirt-imageio-daemon is not running in the selected host for transferring. For trying
to resume the session, the client should call <a href="#services/image_transfer/methods/resume">resume</a>. After
resuming, the phase will change to <code>resuming</code></p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4paused_systemThis phase will be set as a result of an active pause call by the user, using
<<services/image_transfer/methods/pause, pause>>.
<div class="paragraph">
<p>This phase will be set as a result of an active pause call by the user, using
<a href="#services/image_transfer/methods/pause">pause</a>.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4paused_userThis phase will be set as a result of the user actively cancelling the transfer, which can only be performed
via the webadmin.
<div class="paragraph">
<p>This phase will be set as a result of the user actively cancelling the transfer, which can only be performed
via the webadmin.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4cancelledThis phase will be set when the user calls <<services/image_transfer/methods/finalize, finalize>>. Calling
finalize is essential in order to finish the transfer session and using the targeted image. After finalizing,
the phase will be changed to `finished_success` or `finished_failure`.
Please refer to <<services/image_transfer, image transfer>> for further documentation.
<div class="paragraph">
<p>This phase will be set when the user calls <a href="#services/image_transfer/methods/finalize">finalize</a>. Calling
finalize is essential in order to finish the transfer session and using the targeted image. After finalizing,
the phase will be changed to <code>finished_success</code> or <code>finished_failure</code>.</p>
</div>
<div class="paragraph">
<p>Please refer to <a href="#services/image_transfer">image transfer</a> for further documentation.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4finalizing_successThis phase can only be set by oVirt webadmin, and states that there was some error during the transfer and it
is being finalized with failure.
<div class="paragraph">
<p>This phase can only be set by oVirt webadmin, and states that there was some error during the transfer and it
is being finalized with failure.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4finalizing_failureStates that the transfer session was successfully closed, and the targeted image was verified and ready to be
used. After reaching this phase, the image transfer entity will soon be deleted.
<div class="paragraph">
<p>States that the transfer session was successfully closed, and the targeted image was verified and ready to be
used. After reaching this phase, the image transfer entity will soon be deleted.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4finished_successStates that the targeted image failed the verification, and cannot be used. After reaching this phase,
the image transfer entity will soon be deleted, and the targeted image will be set to illegal.
<div class="paragraph">
<p>States that the targeted image failed the verification, and cannot be used. After reaching this phase,
the image transfer entity will soon be deleted, and the targeted image will be set to illegal.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4finished_failuregluster_brick_advanced_detailsportintegerpidintegerdevicestringmnt_optionsstringfs_namestringgluster_clientsgluster_client[]memory_poolsgluster_memory_pool[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmpermitadministrativebooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringrolerolesshportintegerfingerprintstringauthentication_methoduseruseridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringfloppyfilefileidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmexternal_hostaddressstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringexternal_host_providerexternal_host_providervmstatusstatus_detailstringstop_reasonstringstart_timedatestop_timedaterun_oncebooleanpayloadspayload[]The configuration of the virtual machine's placement policy.
This configuration can be updated to pin a virtual machine to one or more hosts.
NOTE: Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host
failure, any virtual machine configured to be highly available is automatically restarted on one of the other
hosts to which the virtual machine is pinned.
For example, to pin a virtual machine to two hosts, you would send a request like the following:
[source]
----
PUT /api/vms/123
----
With a request body like this:
[source,xml]
----
<vm>
<high_availability>
<enabled>true</enabled>
<priority>1</priority>
</high_availability>
<placement_policy>
<hosts>
<host>
<name>Host1</name>
</host>
<host>
<name>Host2</name>
</host>
</hosts>
<affinity>pinned</affinity>
</placement_policy>
</vm>
----
<div class="paragraph">
<p>The configuration of the virtual machine’s placement policy.</p>
</div>
<div class="paragraph">
<p>This configuration can be updated to pin a virtual machine to one or more hosts.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host
failure, any virtual machine configured to be highly available is automatically restarted on one of the other
hosts to which the virtual machine is pinned.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For example, to pin a virtual machine to two hosts, you would send a request like the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<high_availability>
<enabled>true</enabled>
<priority>1</priority>
</high_availability>
<placement_policy>
<hosts>
<host>
<name>Host1</name>
</host>
<host>
<name>Host2</name>
</host>
</hosts>
<affinity>pinned</affinity>
</placement_policy>
</vm></code></pre>
</div>
</div>
authorvaluePhillip Bailey <phbailey@redhat.com>datevalue14 Sep 2016statusvalueaddedplacement_policyvm_placement_policyfqdnstringuse_latest_template_versionbooleannext_run_configuration_existsbooleannuma_tune_modeguest_time_zonetime_zoneguest_operating_systemguest_operating_systemtypeThe virtual machine's memory, in bytes.
For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body like this:
[source,xml]
----
<vm>
<memory>1073741824</memory>
</vm>
----
NOTE: Memory in the previous example is converted to bytes using the following formula: +
1 GiB = 2^30^ bytes = 1073741824 bytes.
NOTE: Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
<div class="paragraph">
<p>The virtual machine’s memory, in bytes.</p>
</div>
<div class="paragraph">
<p>For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<memory>1073741824</memory>
</vm></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory in the previous example is converted to bytes using the following formula:<br>
1 GiB = 2<sup>30</sup> bytes = 1073741824 bytes.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
</td>
</tr>
</table>
</div>
authorvalueYanir Quinn <yquinn@redhat.com>datevalue14 Sep 2016statusvalueaddedmemoryintegerThe configuration of the CPU of the virtual machine.
The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.
For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body:
[source,xml]
----
<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>
----
<div class="paragraph">
<p>The configuration of the CPU of the virtual machine.</p>
</div>
<div class="paragraph">
<p>The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.</p>
</div>
<div class="paragraph">
<p>For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm></code></pre>
</div>
</div>
authorvalueJenny Tokar <jtokar@redhat.com>datevalue14 Sep 2016statusvalueaddedcpucpucpu_sharesintegerbiosbiososoperating_systemcreation_timedateoriginstringstatelessbooleandelete_protectedbooleanhigh_availabilityhigh_availabilitydisplaydisplayssossorng_devicerng_deviceconsoleconsoledomaindomainusbusbsoundcard_enabledbooleantunnel_migrationbooleanmigration_downtimeintegervirtio_scsivirtio_scsiserial_numberserial_numberstart_pausedbooleanmigrationmigration_optionsioiocustom_propertiescustom_property[]custom_emulated_machinestringcustom_cpu_modelstringtime_zonetime_zonesmall_iconiconlarge_iconiconinitializationinitializationmemory_policymemory_policyVirtual machine custom compatibility version.
This field allows to customize a virtual machine to its own compatibility version. If
`custom_compatibility_version` is set, it overrides the cluster's compatibility version
for this particular virtual machine.
The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.
<div class="paragraph">
<p>Virtual machine custom compatibility version.</p>
</div>
<div class="paragraph">
<p>This field allows to customize a virtual machine to its own compatibility version. If
<code>custom_compatibility_version</code> is set, it overrides the cluster’s compatibility version
for this particular virtual machine.</p>
</div>
<div class="paragraph">
<p>The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.</p>
</div>
custom_compatibility_versionversionidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclusterstorage_domainstorage_domaincpu_profilecpu_profilequotaquotahosthosttemplatetemplateinstance_typeinstance_typeLink to the the list of network interface devices on the virtual machine.
<div class="paragraph">
<p>Link to the the list of network interface devices on the virtual machine.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednicsnic[]snapshotssnapshot[]vm_poolvm_poolcdromscdrom[]floppiesfloppy[]reported_devicesreported_device[]watchdogswatchdog[]permissionspermission[]external_host_providerexternal_host_provideraffinity_labelsaffinity_label[]applicationsapplication[]graphics_consolesgraphics_console[]host_deviceshost_device[]katello_erratakatello_erratum[]numa_nodesnuma_node[]sessionssession[]statisticsstatistic[]tagstag[]References to the disks attached to the virtual machine.
<div class="paragraph">
<p>References to the disks attached to the virtual machine.</p>
</div>
disk_attachmentsdisk_attachment[]consoleenabledbooleanspm_statusnonecontendingspmnetwork_configurationnicsnic[]dnsdnscpu_topologysocketsintegercoresintegerthreadsintegertemplate_versionversion_numberintegerversion_namestringbase_templatetemplateEnumerated type describing all switch types currently supported by engine.
<div class="paragraph">
<p>Enumerated type describing all switch types currently supported by engine.</p>
</div>
switch_typeType representing native switch.
<div class="paragraph">
<p>Type representing native switch.</p>
</div>
legacyType representing Open vSwitch.
<div class="paragraph">
<p>Type representing Open vSwitch.</p>
</div>
ovsThis type contains the information returned by root service of the API.
<div class="paragraph">
<p>This type contains the information returned by root service of the API.</p>
</div>
apiReferences to special objects, like the blank template and the root of the hierarchy of tags.
<div class="paragraph">
<p>References to special objects, like the blank template and the root of the hierarchy of tags.</p>
</div>
special_objectsspecial_objectsInformation about the product, like its name, the name of the vendor and the version.
<div class="paragraph">
<p>Information about the product, like its name, the name of the vendor and the version.</p>
</div>
product_infoproduct_infoA summary containing the total number of relevant objects, like virtual machines, hosts and storage domains.
<div class="paragraph">
<p>A summary containing the total number of relevant objects, like virtual machines, hosts and storage domains.</p>
</div>
summaryapi_summaryThe date and time when this information was generated.
<div class="paragraph">
<p>The date and time when this information was generated.</p>
</div>
timedateRepresents a snapshot object.
[source,xml]
----
<snapshot id="456" href="/ovirt-engine/api/vms/123/snapshots/456">
<actions>
<link rel="restore" href="/ovirt-engine/api/vms/123/snapshots/456/restore"/>
</actions>
<vm id="123" href="/ovirt-engine/api/vms/123"/>
<description>Virtual Machine 1 - Snapshot A</description>
<type>active</type>
<date>2010-08-16T14:24:29</date>
<persist_memorystate>false</persist_memorystate>
</snapshot>
----
<div class="paragraph">
<p>Represents a snapshot object.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><snapshot id="456" href="/ovirt-engine/api/vms/123/snapshots/456">
<actions>
<link rel="restore" href="/ovirt-engine/api/vms/123/snapshots/456/restore"/>
</actions>
<vm id="123" href="/ovirt-engine/api/vms/123"/>
<description>Virtual Machine 1 - Snapshot A</description>
<type>active</type>
<date>2010-08-16T14:24:29</date>
<persist_memorystate>false</persist_memorystate>
</snapshot></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedsnapshotdatedatesnapshot_statuspersist_memorystatebooleansnapshot_typestatusstatus_detailstringstop_reasonstringstart_timedatestop_timedaterun_oncebooleanpayloadspayload[]The configuration of the virtual machine's placement policy.
This configuration can be updated to pin a virtual machine to one or more hosts.
NOTE: Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host
failure, any virtual machine configured to be highly available is automatically restarted on one of the other
hosts to which the virtual machine is pinned.
For example, to pin a virtual machine to two hosts, you would send a request like the following:
[source]
----
PUT /api/vms/123
----
With a request body like this:
[source,xml]
----
<vm>
<high_availability>
<enabled>true</enabled>
<priority>1</priority>
</high_availability>
<placement_policy>
<hosts>
<host>
<name>Host1</name>
</host>
<host>
<name>Host2</name>
</host>
</hosts>
<affinity>pinned</affinity>
</placement_policy>
</vm>
----
<div class="paragraph">
<p>The configuration of the virtual machine’s placement policy.</p>
</div>
<div class="paragraph">
<p>This configuration can be updated to pin a virtual machine to one or more hosts.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host
failure, any virtual machine configured to be highly available is automatically restarted on one of the other
hosts to which the virtual machine is pinned.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For example, to pin a virtual machine to two hosts, you would send a request like the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<high_availability>
<enabled>true</enabled>
<priority>1</priority>
</high_availability>
<placement_policy>
<hosts>
<host>
<name>Host1</name>
</host>
<host>
<name>Host2</name>
</host>
</hosts>
<affinity>pinned</affinity>
</placement_policy>
</vm></code></pre>
</div>
</div>
authorvaluePhillip Bailey <phbailey@redhat.com>datevalue14 Sep 2016statusvalueaddedplacement_policyvm_placement_policyfqdnstringuse_latest_template_versionbooleannext_run_configuration_existsbooleannuma_tune_modeguest_time_zonetime_zoneguest_operating_systemguest_operating_systemtypeThe virtual machine's memory, in bytes.
For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body like this:
[source,xml]
----
<vm>
<memory>1073741824</memory>
</vm>
----
NOTE: Memory in the previous example is converted to bytes using the following formula: +
1 GiB = 2^30^ bytes = 1073741824 bytes.
NOTE: Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
<div class="paragraph">
<p>The virtual machine’s memory, in bytes.</p>
</div>
<div class="paragraph">
<p>For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<memory>1073741824</memory>
</vm></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory in the previous example is converted to bytes using the following formula:<br>
1 GiB = 2<sup>30</sup> bytes = 1073741824 bytes.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
</td>
</tr>
</table>
</div>
authorvalueYanir Quinn <yquinn@redhat.com>datevalue14 Sep 2016statusvalueaddedmemoryintegerThe configuration of the CPU of the virtual machine.
The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.
For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body:
[source,xml]
----
<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>
----
<div class="paragraph">
<p>The configuration of the CPU of the virtual machine.</p>
</div>
<div class="paragraph">
<p>The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.</p>
</div>
<div class="paragraph">
<p>For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm></code></pre>
</div>
</div>
authorvalueJenny Tokar <jtokar@redhat.com>datevalue14 Sep 2016statusvalueaddedcpucpucpu_sharesintegerbiosbiososoperating_systemcreation_timedateoriginstringstatelessbooleandelete_protectedbooleanhigh_availabilityhigh_availabilitydisplaydisplayssossorng_devicerng_deviceconsoleconsoledomaindomainusbusbsoundcard_enabledbooleantunnel_migrationbooleanmigration_downtimeintegervirtio_scsivirtio_scsiserial_numberserial_numberstart_pausedbooleanmigrationmigration_optionsioiocustom_propertiescustom_property[]custom_emulated_machinestringcustom_cpu_modelstringtime_zonetime_zonesmall_iconiconlarge_iconiconinitializationinitializationmemory_policymemory_policyVirtual machine custom compatibility version.
This field allows to customize a virtual machine to its own compatibility version. If
`custom_compatibility_version` is set, it overrides the cluster's compatibility version
for this particular virtual machine.
The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.
<div class="paragraph">
<p>Virtual machine custom compatibility version.</p>
</div>
<div class="paragraph">
<p>This field allows to customize a virtual machine to its own compatibility version. If
<code>custom_compatibility_version</code> is set, it overrides the cluster’s compatibility version
for this particular virtual machine.</p>
</div>
<div class="paragraph">
<p>The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.</p>
</div>
custom_compatibility_versionversionidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclusterstorage_domainstorage_domaincpu_profilecpu_profilequotaquotahosthosttemplatetemplateinstance_typeinstance_typeLink to the the list of network interface devices on the virtual machine.
<div class="paragraph">
<p>Link to the the list of network interface devices on the virtual machine.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednicsnic[]snapshotssnapshot[]vm_poolvm_poolcdromscdrom[]floppiesfloppy[]reported_devicesreported_device[]watchdogswatchdog[]permissionspermission[]external_host_providerexternal_host_provideraffinity_labelsaffinity_label[]applicationsapplication[]graphics_consolesgraphics_console[]host_deviceshost_device[]katello_erratakatello_erratum[]numa_nodesnuma_node[]sessionssession[]statisticsstatistic[]tagstag[]References to the disks attached to the virtual machine.
<div class="paragraph">
<p>References to the disks attached to the virtual machine.</p>
</div>
disk_attachmentsdisk_attachment[]vmvmThis enum holds the types of all internal policy units types
<div class="paragraph">
<p>This enum holds the types of all internal policy units types</p>
</div>
policy_unit_typefilterweightload_balancingserial_number_policyhostvmcustomgluster_memory_pooltypestringhot_countintegercold_countintegerpadded_sizeintegeralloc_countintegermax_allocintegerpool_missesintegermax_stdallocintegeridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringpm_proxy_typeFence proxy is selected from the same cluster as fenced host.
<div class="paragraph">
<p>Fence proxy is selected from the same cluster as fenced host.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedclusterFence proxy is selected from the same data center as fenced host.
<div class="paragraph">
<p>Fence proxy is selected from the same data center as fenced host.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddeddcFence proxy is selected from a different data center than fenced host.
<div class="paragraph">
<p>Fence proxy is selected from a different data center than fenced host.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedother_dcquota_storage_limitlimitintegerusagedecimalidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringquotaquotastorage_domainstorage_domaingluster_brickserver_idstringbrick_dirstringstatusportintegerpidintegerdevicestringmnt_optionsstringfs_namestringgluster_clientsgluster_client[]memory_poolsgluster_memory_pool[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmgluster_volumegluster_volumestatisticsstatistic[]cpu_profileidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringqosqosclusterclusterpermissionspermission[]Network filter enables to filter packets send to/from the VM's nic according to defined rules.
There are several types of network filters supported based on libvirt.
More details about the different network filters can be found https://libvirt.org/firewall.html[here].
In addition to libvirt's network filters, there are two additional network filters:
The first called `vdsm-no-mac-spoofing`, composed of no-mac-spoofing and no-arp-mac-spoofing.
The second called `ovirt-no-filter` is used when no network filter is to be defined for the VM's nic.
`ovirt-no-filter` network filter is only used for internal implementation, and
doesn't exist on the nics.
This is a example of the XML representation:
[source,xml]
----
<network_filter id="00000019-0019-0019-0019-00000000026c">
<name>example-filter</name>
<version>
<major>4</major>
<minor>0</minor>
<build>-1</build>
<revision>-1</revision>
</version>
</network_filter>
----
If any part of the version is not present, it is represented by -1.
<div class="paragraph">
<p>Network filter enables to filter packets send to/from the VM’s nic according to defined rules.</p>
</div>
<div class="paragraph">
<p>There are several types of network filters supported based on libvirt.
More details about the different network filters can be found <a href="https://libvirt.org/firewall.html">here</a>.</p>
</div>
<div class="paragraph">
<p>In addition to libvirt’s network filters, there are two additional network filters:
The first called <code>vdsm-no-mac-spoofing</code>, composed of no-mac-spoofing and no-arp-mac-spoofing.
The second called <code>ovirt-no-filter</code> is used when no network filter is to be defined for the VM’s nic.
<code>ovirt-no-filter</code> network filter is only used for internal implementation, and
doesn’t exist on the nics.</p>
</div>
<div class="paragraph">
<p>This is a example of the XML representation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><network_filter id="00000019-0019-0019-0019-00000000026c">
<name>example-filter</name>
<version>
<major>4</major>
<minor>0</minor>
<build>-1</build>
<revision>-1</revision>
</version>
</network_filter></code></pre>
</div>
</div>
<div class="paragraph">
<p>If any part of the version is not present, it is represented by -1.</p>
</div>
network_filterRepresent the minimal supported version of the specific NetworkFilter for which it was first introduced.
<div class="paragraph">
<p>Represent the minimal supported version of the specific NetworkFilter for which it was first introduced.</p>
</div>
versionversionidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringreported_device_typenetworkinstance_typestatusvmvmversiontemplate_versiontypeThe virtual machine's memory, in bytes.
For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body like this:
[source,xml]
----
<vm>
<memory>1073741824</memory>
</vm>
----
NOTE: Memory in the previous example is converted to bytes using the following formula: +
1 GiB = 2^30^ bytes = 1073741824 bytes.
NOTE: Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
<div class="paragraph">
<p>The virtual machine’s memory, in bytes.</p>
</div>
<div class="paragraph">
<p>For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<memory>1073741824</memory>
</vm></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory in the previous example is converted to bytes using the following formula:<br>
1 GiB = 2<sup>30</sup> bytes = 1073741824 bytes.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
</td>
</tr>
</table>
</div>
authorvalueYanir Quinn <yquinn@redhat.com>datevalue14 Sep 2016statusvalueaddedmemoryintegerThe configuration of the CPU of the virtual machine.
The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.
For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body:
[source,xml]
----
<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>
----
<div class="paragraph">
<p>The configuration of the CPU of the virtual machine.</p>
</div>
<div class="paragraph">
<p>The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.</p>
</div>
<div class="paragraph">
<p>For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm></code></pre>
</div>
</div>
authorvalueJenny Tokar <jtokar@redhat.com>datevalue14 Sep 2016statusvalueaddedcpucpucpu_sharesintegerbiosbiososoperating_systemcreation_timedateoriginstringstatelessbooleandelete_protectedbooleanhigh_availabilityhigh_availabilitydisplaydisplayssossorng_devicerng_deviceconsoleconsoledomaindomainusbusbsoundcard_enabledbooleantunnel_migrationbooleanmigration_downtimeintegervirtio_scsivirtio_scsiserial_numberserial_numberstart_pausedbooleanmigrationmigration_optionsioiocustom_propertiescustom_property[]custom_emulated_machinestringcustom_cpu_modelstringtime_zonetime_zonesmall_iconiconlarge_iconiconinitializationinitializationmemory_policymemory_policyVirtual machine custom compatibility version.
This field allows to customize a virtual machine to its own compatibility version. If
`custom_compatibility_version` is set, it overrides the cluster's compatibility version
for this particular virtual machine.
The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.
<div class="paragraph">
<p>Virtual machine custom compatibility version.</p>
</div>
<div class="paragraph">
<p>This field allows to customize a virtual machine to its own compatibility version. If
<code>custom_compatibility_version</code> is set, it overrides the cluster’s compatibility version
for this particular virtual machine.</p>
</div>
<div class="paragraph">
<p>The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.</p>
</div>
custom_compatibility_versionversionidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclusterstorage_domainstorage_domaincpu_profilecpu_profilequotaquotacdromscdrom[]graphics_consolesgraphics_console[]nicsnic[]permissionspermission[]tagstag[]watchdogswatchdog[]References to the disks attached to the template.
<div class="paragraph">
<p>References to the disks attached to the template.</p>
</div>
disk_attachmentsdisk_attachment[]ssh_authentication_methodpasswordpublickeystorage_domain_typedataisoexportimagevolumehook_statusenableddisabledmissingnic_statusdownupdisk_profileidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringqosqosstorage_domainstorage_domainpermissionspermission[]storage_domain_statusactiveinactivelockedmixedunattachedmaintenancepreparing_for_maintenancedetachingactivatingunknownEnum representing boolean value that can be either set or inherited from higher level.
Usual inheritance order is VM -> Cluster -> engine-config.
<div class="paragraph">
<p>Enum representing boolean value that can be either set or inherited from higher level.
Usual inheritance order is VM → Cluster → engine-config.</p>
</div>
inheritable_booleanSet value to true on this level.
<div class="paragraph">
<p>Set value to true on this level.</p>
</div>
trueSet value to false on this level.
<div class="paragraph">
<p>Set value to false on this level.</p>
</div>
falseInherit value from higher level.
<div class="paragraph">
<p>Inherit value from higher level.</p>
</div>
inheritgluster_brick_memory_infomemory_poolsgluster_memory_pool[]open_stack_volume_providertenant_namestringurlstringrequires_authenticationbooleanusernamestringpasswordstringauthentication_urlstringpropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringdata_centerdata_centercertificatescertificate[]volume_typesopen_stack_volume_type[]authentication_keysopenstack_volume_authentication_key[]quota_mode_typeenableddisabledauditdisk_statusillegallockedokpower_management_statusHost is ON.
<div class="paragraph">
<p>Host is ON.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedonHost is OFF.
<div class="paragraph">
<p>Host is OFF.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedoffUnknown status.
<div class="paragraph">
<p>Unknown status.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedunknowntemplatestatusvmvmversiontemplate_versiontypeThe virtual machine's memory, in bytes.
For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body like this:
[source,xml]
----
<vm>
<memory>1073741824</memory>
</vm>
----
NOTE: Memory in the previous example is converted to bytes using the following formula: +
1 GiB = 2^30^ bytes = 1073741824 bytes.
NOTE: Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
<div class="paragraph">
<p>The virtual machine’s memory, in bytes.</p>
</div>
<div class="paragraph">
<p>For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<memory>1073741824</memory>
</vm></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory in the previous example is converted to bytes using the following formula:<br>
1 GiB = 2<sup>30</sup> bytes = 1073741824 bytes.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
</td>
</tr>
</table>
</div>
authorvalueYanir Quinn <yquinn@redhat.com>datevalue14 Sep 2016statusvalueaddedmemoryintegerThe configuration of the CPU of the virtual machine.
The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.
For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body:
[source,xml]
----
<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>
----
<div class="paragraph">
<p>The configuration of the CPU of the virtual machine.</p>
</div>
<div class="paragraph">
<p>The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.</p>
</div>
<div class="paragraph">
<p>For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm></code></pre>
</div>
</div>
authorvalueJenny Tokar <jtokar@redhat.com>datevalue14 Sep 2016statusvalueaddedcpucpucpu_sharesintegerbiosbiososoperating_systemcreation_timedateoriginstringstatelessbooleandelete_protectedbooleanhigh_availabilityhigh_availabilitydisplaydisplayssossorng_devicerng_deviceconsoleconsoledomaindomainusbusbsoundcard_enabledbooleantunnel_migrationbooleanmigration_downtimeintegervirtio_scsivirtio_scsiserial_numberserial_numberstart_pausedbooleanmigrationmigration_optionsioiocustom_propertiescustom_property[]custom_emulated_machinestringcustom_cpu_modelstringtime_zonetime_zonesmall_iconiconlarge_iconiconinitializationinitializationmemory_policymemory_policyVirtual machine custom compatibility version.
This field allows to customize a virtual machine to its own compatibility version. If
`custom_compatibility_version` is set, it overrides the cluster's compatibility version
for this particular virtual machine.
The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.
<div class="paragraph">
<p>Virtual machine custom compatibility version.</p>
</div>
<div class="paragraph">
<p>This field allows to customize a virtual machine to its own compatibility version. If
<code>custom_compatibility_version</code> is set, it overrides the cluster’s compatibility version
for this particular virtual machine.</p>
</div>
<div class="paragraph">
<p>The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.</p>
</div>
custom_compatibility_versionversionidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclusterstorage_domainstorage_domaincpu_profilecpu_profilequotaquotacdromscdrom[]graphics_consolesgraphics_console[]nicsnic[]permissionspermission[]tagstag[]watchdogswatchdog[]References to the disks attached to the template.
<div class="paragraph">
<p>References to the disks attached to the template.</p>
</div>
disk_attachmentsdisk_attachment[]external_discovered_hostipstringmacstringsubnet_namestringlast_reportstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringexternal_host_providerexternal_host_providerqos_typestoragecpunetworkhostnetworkkatello_erratumtitlestringtypestringissueddateseveritystringsolutionstringsummarystringpackagespackage[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostvmvmscheduling_policy_unittypeinternalbooleanenabledbooleanpropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringos_typeunassignedwindows_xpwindows_2003windows_2008other_linuxotherrhel_5rhel_4rhel_3windows_2003x64windows_7windows_7x64rhel_5x64rhel_4x64rhel_3x64windows_2008x64windows_2008r2x64rhel_6rhel_6x64windows_8windows_8x64windows_2012x64statistic_kindcountergaugeexternal_system_typevdsmglusterdnsservershost[]search_domainshost[]hosted_engineconfiguredbooleanactivebooleanscoreintegerglobal_maintenancebooleanlocal_maintenancebooleangluster_volume_typedistributereplicatedistributed_replicatestripedistributed_stripestriped_replicatedistributed_striped_replicatedispersedistributed_disperseThis type contains information about the product, including its name, the name of the vendor, and the version.
<div class="paragraph">
<p>This type contains information about the product, including its name, the name of the vendor, and the version.</p>
</div>
product_infoThe name of the product, for example `oVirt Engine`.
<div class="paragraph">
<p>The name of the product, for example <code>oVirt Engine</code>.</p>
</div>
namestringThe name of the vendor, for example `ovirt.org`.
<div class="paragraph">
<p>The name of the vendor, for example <code>ovirt.org</code>.</p>
</div>
vendorstringThe version number of the product.
<div class="paragraph">
<p>The version number of the product.</p>
</div>
versionversionvaluedatumdecimaldetailstringstorage_formatv1v2v3filecontentstringtypestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringstorage_domainstorage_domainproductidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringiothreadsintegerDescribes user session to a virtual machine.
<div class="paragraph">
<p>Describes user session to a virtual machine.</p>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedsessionProtocol used by the session.
Currently not used, intended for info about how is user connected: SPICE, VNC, SSH, RDP.
<div class="paragraph">
<p>Protocol used by the session.</p>
</div>
<div class="paragraph">
<p>Currently not used, intended for info about how is user connected: SPICE, VNC, SSH, RDP.</p>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedprotocolstringIP address user is connected from.
Currently only available for console users.
<div class="paragraph">
<p>IP address user is connected from.</p>
</div>
<div class="paragraph">
<p>Currently only available for console users.</p>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedipipIndicates if this is a console session.
The value will be `true` for console users: SPICE or VNC, `false` for others: e.g. RDP, SSH.
<div class="paragraph">
<p>Indicates if this is a console session.</p>
</div>
<div class="paragraph">
<p>The value will be <code>true</code> for console users: SPICE or VNC, <code>false</code> for others: e.g. RDP, SSH.</p>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedconsole_userbooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringUser related to this session.
If user is a console user, it is a link to real oVirt user. Otherwise only username is provided.
<div class="paragraph">
<p>User related to this session.</p>
</div>
<div class="paragraph">
<p>If user is a console user, it is a link to real oVirt user. Otherwise only username is provided.</p>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddeduseruserLink to virtual machine related to this session.
<div class="paragraph">
<p>Link to virtual machine related to this session.</p>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedvmvmsso_methodguest_agentvm_basetypeThe virtual machine's memory, in bytes.
For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body like this:
[source,xml]
----
<vm>
<memory>1073741824</memory>
</vm>
----
NOTE: Memory in the previous example is converted to bytes using the following formula: +
1 GiB = 2^30^ bytes = 1073741824 bytes.
NOTE: Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
<div class="paragraph">
<p>The virtual machine’s memory, in bytes.</p>
</div>
<div class="paragraph">
<p>For example, in order to update a virtual machine to contain 1 GiB of memory send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<memory>1073741824</memory>
</vm></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory in the previous example is converted to bytes using the following formula:<br>
1 GiB = 2<sup>30</sup> bytes = 1073741824 bytes.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Memory hot plug is supported from oVirt 3.6 onwards.
You can use the example above to increase memory while the virtual machine is running.
</td>
</tr>
</table>
</div>
authorvalueYanir Quinn <yquinn@redhat.com>datevalue14 Sep 2016statusvalueaddedmemoryintegerThe configuration of the CPU of the virtual machine.
The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.
For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:
[source]
----
PUT /ovirt-engine/api/vms/123
----
With a request body:
[source,xml]
----
<vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm>
----
<div class="paragraph">
<p>The configuration of the CPU of the virtual machine.</p>
</div>
<div class="paragraph">
<p>The sockets configuration can be updated without rebooting the virtual machine. The cores and the threads require
a reboot in order to take place.</p>
</div>
<div class="paragraph">
<p>For example, to change the number of sockets to 4 immediately and the number of cores and threads to 2 after
reboot send a request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<cpu>
<topology>
<sockets>4</sockets>
<cores>2</cores>
<threads>2</threads>
</topology>
</cpu>
</vm></code></pre>
</div>
</div>
authorvalueJenny Tokar <jtokar@redhat.com>datevalue14 Sep 2016statusvalueaddedcpucpucpu_sharesintegerbiosbiososoperating_systemcreation_timedateoriginstringstatelessbooleandelete_protectedbooleanhigh_availabilityhigh_availabilitydisplaydisplayssossorng_devicerng_deviceconsoleconsoledomaindomainusbusbsoundcard_enabledbooleantunnel_migrationbooleanmigration_downtimeintegervirtio_scsivirtio_scsiserial_numberserial_numberstart_pausedbooleanmigrationmigration_optionsioiocustom_propertiescustom_property[]custom_emulated_machinestringcustom_cpu_modelstringtime_zonetime_zonesmall_iconiconlarge_iconiconinitializationinitializationmemory_policymemory_policyVirtual machine custom compatibility version.
This field allows to customize a virtual machine to its own compatibility version. If
`custom_compatibility_version` is set, it overrides the cluster's compatibility version
for this particular virtual machine.
The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.
<div class="paragraph">
<p>Virtual machine custom compatibility version.</p>
</div>
<div class="paragraph">
<p>This field allows to customize a virtual machine to its own compatibility version. If
<code>custom_compatibility_version</code> is set, it overrides the cluster’s compatibility version
for this particular virtual machine.</p>
</div>
<div class="paragraph">
<p>The compatibility version of a virtual machine is limited by the data center the virtual
machine resides in and is checked against capabilities of the host the virtual machine is
planned to run on.</p>
</div>
custom_compatibility_versionversionidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclusterstorage_domainstorage_domaincpu_profilecpu_profilequotaquotaprofile_detailprofile_typestringdurationintegerstatisticsstatistic[]block_statisticsblock_statistic[]fop_statisticsfop_statistic[]guest_operating_systemarchitecturestringcodenamestringdistributionstringkernelkernelfamilystringversionversionvm_summaryactiveintegermigratingintegertotalintegerinitializationconfigurationconfigurationcloud_initcloud_inithost_namestringdomainstringtimezonestringauthorized_ssh_keysstringregenerate_ssh_keysbooleanregenerate_idsbooleandns_serversstringdns_searchstringnic_configurationsnic_configuration[]windows_license_keystringroot_passwordstringcustom_scriptstringinput_localestringui_languagestringsystem_localestringuser_localestringuser_namestringactive_directory_oustringorg_namestringDescribes the capabilities supported by a specific cluster level.
<div class="paragraph">
<p>Describes the capabilities supported by a specific cluster level.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue3 Nov 2016statusvalueupdated_by_docscluster_levelThe CPU types supported by this cluster level.
<div class="paragraph">
<p>The CPU types supported by this cluster level.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue3 Nov 2016statusvalueupdated_by_docscpu_typescpu_type[]The permits supported by this cluster level.
<div class="paragraph">
<p>The permits supported by this cluster level.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue3 Nov 2016statusvalueupdated_by_docspermitspermit[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringfencing_policyenabledbooleanskip_if_sd_activeskip_if_sd_activeskip_if_connectivity_brokenskip_if_connectivity_brokenDescribes a supported CPU type.
<div class="paragraph">
<p>Describes a supported CPU type.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue28 Oct 2016statusvalueupdated_by_docscpu_typeThe name of the CPU type, for example `Intel Conroe Family`.
<div class="paragraph">
<p>The name of the CPU type, for example <code>Intel Conroe Family</code>.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue28 Oct 2016statusvalueupdated_by_docsnamestringThe level of the CPU type.
<div class="paragraph">
<p>The level of the CPU type.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue28 Oct 2016statusvalueupdated_by_docslevelintegerThe architecture of the CPU.
<div class="paragraph">
<p>The architecture of the CPU.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue28 Oct 2016statusvalueupdated_by_docsarchitecturebootdevices[]This type contains an item of the API summary. Each item contains the total and active number of some kind of
object.
<div class="paragraph">
<p>This type contains an item of the API summary. Each item contains the total and active number of some kind of
object.</p>
</div>
api_summary_itemThe total number of objects.
<div class="paragraph">
<p>The total number of objects.</p>
</div>
totalintegerThe total number of active objects.
<div class="paragraph">
<p>The total number of active objects.</p>
</div>
activeintegerpower_managementIndicates whether power management configuration is enabled or disabled.
<div class="paragraph">
<p>Indicates whether power management configuration is enabled or disabled.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedenabledbooleanThe host name or IP address of the host.
<div class="paragraph">
<p>The host name or IP address of the host.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedaddressstringA valid user name for power management.
<div class="paragraph">
<p>A valid user name for power management.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedusernamestringA valid, robust password for power management.
<div class="paragraph">
<p>A valid, robust password for power management.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedpasswordstringFencing options for the selected type= specified with the option name="" and value="" strings.
<div class="paragraph">
<p>Fencing options for the selected type= specified with the option name="" and value="" strings.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedoptionsoption[]Determines the power status of the host.
<div class="paragraph">
<p>Determines the power status of the host.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedstatusDetermines the power management proxy.
<div class="paragraph">
<p>Determines the power management proxy.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedpm_proxiespm_proxy[]Specifies fence agent options when multiple fences are used.
Use the order sub-element to prioritize the fence agents. Agents are run sequentially according to their
order until the fence action succeeds. When two or more fence agents have the same order,
they are run concurrently. Other sub-elements include type, ip, user, password, and options.
<div class="paragraph">
<p>Specifies fence agent options when multiple fences are used.</p>
</div>
<div class="paragraph">
<p>Use the order sub-element to prioritize the fence agents. Agents are run sequentially according to their
order until the fence action succeeds. When two or more fence agents have the same order,
they are run concurrently. Other sub-elements include type, ip, user, password, and options.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedagentsagent[]Toggles the automated power control of the host in order to save energy.
When set to true, the host will be automatically powered down if the cluster's load is low,
and powered on again when required. This is set to true when a host is created, unless disabled by the user.
<div class="paragraph">
<p>Toggles the automated power control of the host in order to save energy.
When set to true, the host will be automatically powered down if the cluster’s load is low,
and powered on again when required. This is set to true when a host is created, unless disabled by the user.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedautomatic_pm_enabledbooleanToggles whether to determine if kdump is running on the host before it is shut down.
When set to `true`, the host will not shut down during a kdump process.
This is set to `true` when a host has power management enabled, unless disabled by the user.
<div class="paragraph">
<p>Toggles whether to determine if kdump is running on the host before it is shut down.
When set to <code>true</code>, the host will not shut down during a kdump process.
This is set to <code>true</code> when a host has power management enabled, unless disabled by the user.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedkdump_detectionbooleanFencing device code.
A list of valid fencing device codes are available in the `capabilities` collection.
<div class="paragraph">
<p>Fencing device code.</p>
</div>
<div class="paragraph">
<p>A list of valid fencing device codes are available in the <code>capabilities</code> collection.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedtypestringcustom_propertynamestringvaluestringregexpstringpm_proxytypeRepresents a virtual disk device.
<div class="paragraph">
<p>Represents a virtual disk device.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddeddiskaliasstringimage_idstringThe virtual size of the disk, in bytes.
This attribute is mandatory when creating a new disk.
<div class="paragraph">
<p>The virtual size of the disk, in bytes.</p>
</div>
<div class="paragraph">
<p>This attribute is mandatory when creating a new disk.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedprovisioned_sizeintegerThe actual size of the disk, in bytes.
The actual size is the number of bytes actually used by the disk, and it will be smaller than the provisioned
size for disks that use the `cow` format.
<div class="paragraph">
<p>The actual size of the disk, in bytes.</p>
</div>
<div class="paragraph">
<p>The actual size is the number of bytes actually used by the disk, and it will be smaller than the provisioned
size for disks that use the <code>cow</code> format.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedactual_sizeintegerThe status of the disk device.
<div class="paragraph">
<p>The status of the disk device.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedstatusThe type of interface driver used to connect the disk device to the virtual machine.
IMPORTANT: This attribute only makes sense for disks that are actually connected to virtual machines, and in
version 4 of the API it has been moved to the <<types/disk_attachment, DiskAttachment>> type. It is preserved
here only for backwards compatibility, and it will be removed in the future.
<div class="paragraph">
<p>The type of interface driver used to connect the disk device to the virtual machine.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
This attribute only makes sense for disks that are actually connected to virtual machines, and in
version 4 of the API it has been moved to the <a href="#types/disk_attachment">DiskAttachment</a> type. It is preserved
here only for backwards compatibility, and it will be removed in the future.
</td>
</tr>
</table>
</div>
deprecatedauthorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedinterfaceThe underlying storage format.
<div class="paragraph">
<p>The underlying storage format.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedformatIndicates if the physical storage for the disk should not be preallocated.
<div class="paragraph">
<p>Indicates if the physical storage for the disk should not be preallocated.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedsparsebooleanIndicates if the disk is marked as bootable.
IMPORTANT: This attribute only makes sense for disks that are actually connected to virtual machines, and in
version 4 of the API it has been moved to the <<types/disk_attachment, DiskAttachment>> type. It is preserved
here only for backwards compatibility, and it will be removed in the future.
<div class="paragraph">
<p>Indicates if the disk is marked as bootable.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
This attribute only makes sense for disks that are actually connected to virtual machines, and in
version 4 of the API it has been moved to the <a href="#types/disk_attachment">DiskAttachment</a> type. It is preserved
here only for backwards compatibility, and it will be removed in the future.
</td>
</tr>
</table>
</div>
deprecatedauthorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedbootablebooleanIndicates if the disk can be attached to multiple virtual machines.
IMPORTANT: When a disk is attached to multiple virtual machines it is the responsibility of the guest
operating systems of those virtual machines to coordinate access to it, to avoid corruption of the data, for
example using a shared file system like https://www.gluster.org[GlusterFS] or
http://www.sourceware.org/cluster/gfs[GFS].
<div class="paragraph">
<p>Indicates if the disk can be attached to multiple virtual machines.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
When a disk is attached to multiple virtual machines it is the responsibility of the guest
operating systems of those virtual machines to coordinate access to it, to avoid corruption of the data, for
example using a shared file system like <a href="https://www.gluster.org">GlusterFS</a> or
<a href="http://www.sourceware.org/cluster/gfs">GFS</a>.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedshareablebooleanIndicates if the disk's blocks will be read back as zeros after it is deleted:
- On block storage, the disk will be zeroed and only then deleted.
- On file storage, since the file system already guarantees that previously removed blocks are read back as
zeros, the disk will be deleted immediately.
<div class="paragraph">
<p>Indicates if the disk’s blocks will be read back as zeros after it is deleted:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>On block storage, the disk will be zeroed and only then deleted.</p>
</li>
<li>
<p>On file storage, since the file system already guarantees that previously removed blocks are read back as
zeros, the disk will be deleted immediately.</p>
</li>
</ul>
</div>
authorvalueIdan Shaby <ishaby@redhat.com>datevalue6 Nov 2016statusvalueaddedwipe_after_deletebooleanIndicates if disk errors should not cause virtual machine to be paused and, instead, disk errors should be
propagated to the the guest operating system.
<div class="paragraph">
<p>Indicates if disk errors should not cause virtual machine to be paused and, instead, disk errors should be
propagated to the the guest operating system.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedpropagate_errorsbooleanIndicates if the disk is visible to the virtual machine.
IMPORTANT: When adding a disk attachment to a virtual machine, the server accepts requests that don't contain
this attribute, but the effect is then 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 this attribute
with the desired value.
<div class="paragraph">
<p>Indicates if the disk is visible to the virtual machine.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
When adding a disk attachment to a virtual machine, the server accepts requests that don’t contain
this attribute, but the effect is then 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 this attribute
with the desired value.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue9 Nov 2016statusvalueaddedactivebooleanIndicates if the disk is in read-only mode.
<div class="paragraph">
<p>Indicates if the disk is in read-only mode.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedread_onlybooleanlun_storagehost_storagesgiouses_scsi_reservationbooleanstorage_typelogical_namestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmstorage_domainstorage_domainThe storage domains associated with this disk.
NOTE: Only required when the first disk is being added to a virtual machine that was not itself created from a
template.
<div class="paragraph">
<p>The storage domains associated with this disk.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Only required when the first disk is being added to a virtual machine that was not itself created from a
template.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedstorage_domainsstorage_domain[]quotaquotadisk_profiledisk_profilesnapshotsnapshotopenstack_volume_typeopen_stack_volume_typepermissionspermission[]statisticsstatistic[]certificateorganizationstringsubjectstringcontentstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringvlanidintegernfs_versionautov3v4v4_1versionmajorintegerminorintegerbuildintegerrevisionintegerfull_versionstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringmacaddressstringvm_placement_policyaffinityhostshost[]host_storageaddressstringtypepathstringmount_optionsstringvfs_typestringnfs_versionThe time in tenths of a second to wait for a response before retrying NFS requests. The value must be in the
range of 0 to 65535. For more details see the description of the `timeo` mount option in the `nfs` man page.
<div class="paragraph">
<p>The time in tenths of a second to wait for a response before retrying NFS requests. The value must be in the
range of 0 to 65535. For more details see the description of the <code>timeo</code> mount option in the <code>nfs</code> man page.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>Tahlia Richardson <trichard@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsnfs_timeointegerThe number of times to retry a request before attempting further recovery actions. The value must be in the
range of 0 to 65535. For more details see the description of the `retrans` mount option in the `nfs` man page.
<div class="paragraph">
<p>The number of times to retry a request before attempting further recovery actions. The value must be in the
range of 0 to 65535. For more details see the description of the <code>retrans</code> mount option in the <code>nfs</code> man page.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>Tahlia Richardson <trichard@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsnfs_retransintegerportintegertargetstringusernamestringpasswordstringportalstringlogical_unitslogical_unit[]volume_groupvolume_groupoverride_lunsbooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostproxy_ticketvaluestringnic_configurationnamestringipipboot_protocolon_bootbooleanDefines the method how the migration bandwidth is assigned.
<div class="paragraph">
<p>Defines the method how the migration bandwidth is assigned.</p>
</div>
migration_bandwidth_assignment_methodTakes the bandwidth from QoS if QoS defined.
If not, taken from detected link speed being used.
If nothing detected, falls back to hypervisor_default value.
<div class="paragraph">
<p>Takes the bandwidth from QoS if QoS defined.
If not, taken from detected link speed being used.
If nothing detected, falls back to hypervisor_default value.</p>
</div>
autoCustom defined bandwidth in Mbit/s.
<div class="paragraph">
<p>Custom defined bandwidth in Mbit/s.</p>
</div>
customTakes the value as configured on the hypervisor.
<div class="paragraph">
<p>Takes the value as configured on the hypervisor.</p>
</div>
hypervisor_defaultdisplaytypeaddressstringportintegersecure_portintegermonitorsintegersingle_qxl_pcibooleanallow_overridebooleancertificatecertificatesmartcard_enabledbooleankeyboard_layoutstringproxystringfile_transfer_enabledbooleancopy_paste_enabledbooleandisconnect_actionstringmigrate_on_errormigratedo_not_migratemigrate_highly_availablebondingoptionsoption[]slaveshost_nic[]The `ad_partner_mac` property of the partner bond in mode 4. Bond mode 4 is the 802.3ad standard,
also called dynamic link aggregation -
https://en.wikipedia.org/wiki/Link_aggregation[Wikipedia],
http://www.ieee802.org/3/hssg/public/apr07/frazier_01_0407.pdf[Presentation].
`ad_partner_mac` is the MAC address of the system (switch) at the other end of a bond.
This parameter is read only. Setting it will have no effect on the bond.
It is retrieved from `/sys/class/net/bondX/bonding/ad_partner_mac` file on the system where the bond is located.
<div class="paragraph">
<p>The <code>ad_partner_mac</code> property of the partner bond in mode 4. Bond mode 4 is the 802.3ad standard,
also called dynamic link aggregation -
<a href="https://en.wikipedia.org/wiki/Link_aggregation">Wikipedia</a>,
<a href="http://www.ieee802.org/3/hssg/public/apr07/frazier_01_0407.pdf">Presentation</a>.
<code>ad_partner_mac</code> is the MAC address of the system (switch) at the other end of a bond.
This parameter is read only. Setting it will have no effect on the bond.
It is retrieved from <code>/sys/class/net/bondX/bonding/ad_partner_mac</code> file on the system where the bond is located.</p>
</div>
authorvalueMarcin Mirecki <mmirecki@redhat.com>datevalue10 Aug 2016statusvalueaddedsincevalue4.0.3ad_partner_macmacentity_external_statusokinfowarningerrorfailureblock_statisticstatisticsstatistic[]snapshot_typeregularactivestatelesspreviewgraphics_consoleprotocolportintegertls_portintegeraddressstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringvmvmtemplatetemplateinstance_typeinstance_typeRepresents a quota object.
An example XML representation of a quota:
[source,xml]
----
<quota href="/ovirt-engine/api/datacenters/7044934e/quotas/dcad5ddc" id="dcad5ddc">
<name>My Quota</name>
<description>A quota for my oVirt environment</description>
<cluster_hard_limit_pct>0</cluster_hard_limit_pct>
<cluster_soft_limit_pct>0</cluster_soft_limit_pct>
<data_center href="/ovirt-engine/api/datacenters/7044934e" id="7044934e"/>
<storage_hard_limit_pct>0</storage_hard_limit_pct>
<storage_soft_limit_pct>0</storage_soft_limit_pct>
</quota>
----
<div class="paragraph">
<p>Represents a quota object.</p>
</div>
<div class="paragraph">
<p>An example XML representation of a quota:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><quota href="/ovirt-engine/api/datacenters/7044934e/quotas/dcad5ddc" id="dcad5ddc">
<name>My Quota</name>
<description>A quota for my oVirt environment</description>
<cluster_hard_limit_pct>0</cluster_hard_limit_pct>
<cluster_soft_limit_pct>0</cluster_soft_limit_pct>
<data_center href="/ovirt-engine/api/datacenters/7044934e" id="7044934e"/>
<storage_hard_limit_pct>0</storage_hard_limit_pct>
<storage_soft_limit_pct>0</storage_soft_limit_pct>
</quota></code></pre>
</div>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedquotadata_centerdata_centervmsvm[]disksdisk[]usersuser[]cluster_soft_limit_pctintegercluster_hard_limit_pctintegerstorage_soft_limit_pctintegerstorage_hard_limit_pctintegeridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringpermissionspermission[]quota_cluster_limitsquota_cluster_limit[]quota_storage_limitsquota_storage_limit[]role_typeadminuserqostypemax_throughputintegermax_read_throughputintegermax_write_throughputintegermax_iopsintegermax_read_iopsintegermax_write_iopsintegercpu_limitintegerinbound_averageintegerinbound_peakintegerinbound_burstintegeroutbound_averageintegeroutbound_peakintegeroutbound_burstintegeroutbound_average_linkshareintegeroutbound_average_upperlimitintegeroutbound_average_realtimeintegeridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringdata_centerdata_centerratebytesintegerperiodintegerhardware_informationmanufacturerstringversionstringserial_numberstringproduct_namestringuuidstringfamilystringsupported_rng_sources[]fop_statisticnamestringstatisticsstatistic[]applicationidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringvmvmport_mirroringDescribes type of external hypervisor system.
<div class="paragraph">
<p>Describes type of external hypervisor system.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4external_vm_provider_typekvmxenvmwarecdromfilefileidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmInformation describing the operating system. Used for virtual machines and hosts.
<div class="paragraph">
<p>Information describing the operating system. Used for virtual machines and hosts.</p>
</div>
operating_systemtypestringbootbootkernelstringinitrdstringcmdlinestringHost kernel command line as reported by a running host.
Read-only attribute. Attempts to change this attribute are silently ignored.
NOTE: This attribute is currently only used for hosts.
<div class="paragraph">
<p>Host kernel command line as reported by a running host.</p>
</div>
<div class="paragraph">
<p>Read-only attribute. Attempts to change this attribute are silently ignored.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This attribute is currently only used for hosts.
</td>
</tr>
</table>
</div>
reported_kernel_cmdlinestringA custom part of the host kernel command line. This will be merged with the existing kernel command line.
You must re-install and then reboot the host to apply the changes implemented by this attribute.
Parameters merging: During each host deploy procedure, kernel parameters that were added
in the previous host deploy procedure are removed using
`grubby --update-kernel DEFAULT --remove-args <previous_custom_params>` and the current
kernel command line customization is applied using
`grubby --update-kernel DEFAULT --args <custom_params>`. The Engine internally keeps track of the
last applied kernel parameters customization.
NOTE: This attribute is currently only used for hosts.
<div class="paragraph">
<p>A custom part of the host kernel command line. This will be merged with the existing kernel command line.</p>
</div>
<div class="paragraph">
<p>You must re-install and then reboot the host to apply the changes implemented by this attribute.</p>
</div>
<div class="paragraph">
<p>Parameters merging: During each host deploy procedure, kernel parameters that were added
in the previous host deploy procedure are removed using
<code>grubby --update-kernel DEFAULT --remove-args <previous_custom_params></code> and the current
kernel command line customization is applied using
<code>grubby --update-kernel DEFAULT --args <custom_params></code>. The Engine internally keeps track of the
last applied kernel parameters customization.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This attribute is currently only used for hosts.
</td>
</tr>
</table>
</div>
custom_kernel_cmdlinestringversionversionopenstack_volume_authentication_key_usage_typecephhookevent_namestringmd5stringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostticketvaluestringexpiryintegerhigh_availabilityenabledbooleanpriorityintegerdisk_snapshotaliasstringimage_idstringThe virtual size of the disk, in bytes.
This attribute is mandatory when creating a new disk.
<div class="paragraph">
<p>The virtual size of the disk, in bytes.</p>
</div>
<div class="paragraph">
<p>This attribute is mandatory when creating a new disk.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedprovisioned_sizeintegerThe actual size of the disk, in bytes.
The actual size is the number of bytes actually used by the disk, and it will be smaller than the provisioned
size for disks that use the `cow` format.
<div class="paragraph">
<p>The actual size of the disk, in bytes.</p>
</div>
<div class="paragraph">
<p>The actual size is the number of bytes actually used by the disk, and it will be smaller than the provisioned
size for disks that use the <code>cow</code> format.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedactual_sizeintegerThe status of the disk device.
<div class="paragraph">
<p>The status of the disk device.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedstatusThe type of interface driver used to connect the disk device to the virtual machine.
IMPORTANT: This attribute only makes sense for disks that are actually connected to virtual machines, and in
version 4 of the API it has been moved to the <<types/disk_attachment, DiskAttachment>> type. It is preserved
here only for backwards compatibility, and it will be removed in the future.
<div class="paragraph">
<p>The type of interface driver used to connect the disk device to the virtual machine.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
This attribute only makes sense for disks that are actually connected to virtual machines, and in
version 4 of the API it has been moved to the <a href="#types/disk_attachment">DiskAttachment</a> type. It is preserved
here only for backwards compatibility, and it will be removed in the future.
</td>
</tr>
</table>
</div>
deprecatedauthorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedinterfaceThe underlying storage format.
<div class="paragraph">
<p>The underlying storage format.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedformatIndicates if the physical storage for the disk should not be preallocated.
<div class="paragraph">
<p>Indicates if the physical storage for the disk should not be preallocated.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedsparsebooleanIndicates if the disk is marked as bootable.
IMPORTANT: This attribute only makes sense for disks that are actually connected to virtual machines, and in
version 4 of the API it has been moved to the <<types/disk_attachment, DiskAttachment>> type. It is preserved
here only for backwards compatibility, and it will be removed in the future.
<div class="paragraph">
<p>Indicates if the disk is marked as bootable.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
This attribute only makes sense for disks that are actually connected to virtual machines, and in
version 4 of the API it has been moved to the <a href="#types/disk_attachment">DiskAttachment</a> type. It is preserved
here only for backwards compatibility, and it will be removed in the future.
</td>
</tr>
</table>
</div>
deprecatedauthorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedbootablebooleanIndicates if the disk can be attached to multiple virtual machines.
IMPORTANT: When a disk is attached to multiple virtual machines it is the responsibility of the guest
operating systems of those virtual machines to coordinate access to it, to avoid corruption of the data, for
example using a shared file system like https://www.gluster.org[GlusterFS] or
http://www.sourceware.org/cluster/gfs[GFS].
<div class="paragraph">
<p>Indicates if the disk can be attached to multiple virtual machines.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
When a disk is attached to multiple virtual machines it is the responsibility of the guest
operating systems of those virtual machines to coordinate access to it, to avoid corruption of the data, for
example using a shared file system like <a href="https://www.gluster.org">GlusterFS</a> or
<a href="http://www.sourceware.org/cluster/gfs">GFS</a>.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedshareablebooleanIndicates if the disk's blocks will be read back as zeros after it is deleted:
- On block storage, the disk will be zeroed and only then deleted.
- On file storage, since the file system already guarantees that previously removed blocks are read back as
zeros, the disk will be deleted immediately.
<div class="paragraph">
<p>Indicates if the disk’s blocks will be read back as zeros after it is deleted:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>On block storage, the disk will be zeroed and only then deleted.</p>
</li>
<li>
<p>On file storage, since the file system already guarantees that previously removed blocks are read back as
zeros, the disk will be deleted immediately.</p>
</li>
</ul>
</div>
authorvalueIdan Shaby <ishaby@redhat.com>datevalue6 Nov 2016statusvalueaddedwipe_after_deletebooleanIndicates if disk errors should not cause virtual machine to be paused and, instead, disk errors should be
propagated to the the guest operating system.
<div class="paragraph">
<p>Indicates if disk errors should not cause virtual machine to be paused and, instead, disk errors should be
propagated to the the guest operating system.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedpropagate_errorsbooleanIndicates if the disk is visible to the virtual machine.
IMPORTANT: When adding a disk attachment to a virtual machine, the server accepts requests that don't contain
this attribute, but the effect is then 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 this attribute
with the desired value.
<div class="paragraph">
<p>Indicates if the disk is visible to the virtual machine.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
When adding a disk attachment to a virtual machine, the server accepts requests that don’t contain
this attribute, but the effect is then 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 this attribute
with the desired value.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue9 Nov 2016statusvalueaddedactivebooleanIndicates if the disk is in read-only mode.
<div class="paragraph">
<p>Indicates if the disk is in read-only mode.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedread_onlybooleanlun_storagehost_storagesgiouses_scsi_reservationbooleanstorage_typelogical_namestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmstorage_domainstorage_domainThe storage domains associated with this disk.
NOTE: Only required when the first disk is being added to a virtual machine that was not itself created from a
template.
<div class="paragraph">
<p>The storage domains associated with this disk.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
Only required when the first disk is being added to a virtual machine that was not itself created from a
template.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedstorage_domainsstorage_domain[]quotaquotadisk_profiledisk_profilesnapshotsnapshotopenstack_volume_typeopen_stack_volume_typepermissionspermission[]statisticsstatistic[]diskdiskA summary containing the total number of relevant objects, like virtual machines, hosts and storage domains.
<div class="paragraph">
<p>A summary containing the total number of relevant objects, like virtual machines, hosts and storage domains.</p>
</div>
api_summaryThe summary of virtual machines.
<div class="paragraph">
<p>The summary of virtual machines.</p>
</div>
vmsapi_summary_itemThe summary of hosts.
<div class="paragraph">
<p>The summary of hosts.</p>
</div>
hostsapi_summary_itemThe summary of users.
<div class="paragraph">
<p>The summary of users.</p>
</div>
usersapi_summary_itemThe summary of storage domains.
<div class="paragraph">
<p>The summary of storage domains.</p>
</div>
storage_domainsapi_summary_itemdata_centerlocalbooleanstorage_formatThe compatibility version of the data center.
All clusters in this data center must already be set to at least this compatibility version.
For example:
[source]
----
GET /ovirt-engine/api/datacenters/123
----
Will respond:
[source,xml]
----
<data_center>
...
<version>
<major>4</major>
<minor>0</minor>
</version>
...
</data_center>
----
To update the compatibility version, use:
[source]
----
PUT /ovirt-engine/api/datacenters/123
----
With a request body:
[source,xml]
----
<data_center>
<version>
<major>4</major>
<minor>1</minor>
</version>
</data_center>
----
<div class="paragraph">
<p>The compatibility version of the data center.</p>
</div>
<div class="paragraph">
<p>All clusters in this data center must already be set to at least this compatibility version.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/datacenters/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>Will respond:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><data_center>
...
<version>
<major>4</major>
<minor>0</minor>
</version>
...
</data_center></code></pre>
</div>
</div>
<div class="paragraph">
<p>To update the compatibility version, use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/datacenters/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><data_center>
<version>
<major>4</major>
<minor>1</minor>
</version>
</data_center></code></pre>
</div>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsversionversionsupported_versionsversion[]statusquota_modeidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringReference to the MAC pool used by this data center.
<div class="paragraph">
<p>Reference to the MAC pool used by this data center.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsmac_poolmac_poolReference to storage domains attached to this data center.
<div class="paragraph">
<p>Reference to storage domains attached to this data center.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsstorage_domainsstorage_domain[]Reference to clusters inside this data center.
<div class="paragraph">
<p>Reference to clusters inside this data center.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsclusterscluster[]Reference to networks attached to this data center.
<div class="paragraph">
<p>Reference to networks attached to this data center.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsnetworksnetwork[]Reference to permissions assigned to this data center.
<div class="paragraph">
<p>Reference to permissions assigned to this data center.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docspermissionspermission[]Reference to quotas assigned to this data center.
<div class="paragraph">
<p>Reference to quotas assigned to this data center.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsquotasquota[]Reference to quality of service used by this data center.
<div class="paragraph">
<p>Reference to quality of service used by this data center.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsqossqos[]Reference to ISCSI bonds used by this data center.
<div class="paragraph">
<p>Reference to ISCSI bonds used by this data center.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsiscsi_bondsiscsi_bond[]network_usagedisplayThe network will be used for Gluster(bricks) data traffic.
<div class="paragraph">
<p>The network will be used for Gluster(bricks) data traffic.</p>
</div>
authorvalueSahina Bose <sabose@redhat.com>datevalue23 Sep 2016statusvalueaddedglustermanagementmigrationvmvm_device_typefloppycdromtransport_typetcprdmapackagenamestringhook_stageprepostunmanaged_networkidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhost_nichost_nichosthosthost_devicecapabilitystringproductproductvendorvendoriommu_groupintegerphysical_functionhost_devicevirtual_functionsintegerplaceholderbooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostparent_devicehost_devicevmvmfence_typemanualrestartstartstopstatuswatchdog_actionnoneresetpoweroffpausedumpThe enum defines the options of the IP address assignment method to a NIC.
<div class="paragraph">
<p>The enum defines the options of the IP address assignment method to a NIC.</p>
</div>
boot_protocolStateless Address Auto-Configuration.
The mechanism is defined by http://tools.ietf.org/html/rfc4862[RFC 4862].
Please refer to https://en.wikipedia.org/wiki/IPv6_address#Stateless_address_autoconfiguration[this wikipedia article].
NOTE: The value is valid for IPv6 addresses only.
<div class="paragraph">
<p>Stateless Address Auto-Configuration.
The mechanism is defined by <a href="http://tools.ietf.org/html/rfc4862">RFC 4862</a>.
Please refer to <a href="https://en.wikipedia.org/wiki/IPv6_address#Stateless_address_autoconfiguration">this wikipedia article</a>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The value is valid for IPv6 addresses only.
</td>
</tr>
</table>
</div>
autoconfDynamic Host Configuration Protocol.
Please refer to https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol[this wikipedia article].
<div class="paragraph">
<p>Dynamic Host Configuration Protocol.
Please refer to <a href="https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol">this wikipedia article</a>.</p>
</div>
dhcpStatically (by user) defined address, mask and gateway.
<div class="paragraph">
<p>Statically (by user) defined address, mask and gateway.</p>
</div>
staticNo address configuration.
<div class="paragraph">
<p>No address configuration.</p>
</div>
nonerng_sourcerandomhwrngbalanceidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringscheduling_policyscheduling_policyscheduling_policy_unitscheduling_policy_unitstep_statusabortedfailedfinishedstartedunknownnfs_profile_detailnfs_server_ipstringprofile_detailsprofile_detail[]boot_menuenabledbooleanexternal_providerurlstringrequires_authenticationbooleanusernamestringpasswordstringauthentication_urlstringpropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringcloud_inithosthostauthorized_keysauthorized_key[]network_configurationnetwork_configurationregenerate_ssh_keysbooleantimezonestringusersuser[]filesfile[]An affinity group represents a group of virtual machines with a defined relationship.
<div class="paragraph">
<p>An affinity group represents a group of virtual machines with a defined relationship.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedaffinity_groupSpecifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are
members of that affinity group.
<div class="paragraph">
<p>Specifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are
members of that affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedpositivebooleanSpecifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines
that are members of that affinity group.
<div class="paragraph">
<p>Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines
that are members of that affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedenforcingbooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringA reference to the cluster to which the affinity group applies.
<div class="paragraph">
<p>A reference to the cluster to which the affinity group applies.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedclusterclusterList of all virtual machines assigned to this affinity group.
<div class="paragraph">
<p>List of all virtual machines assigned to this affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedvmsvm[]domainuseruseridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringgroupsgroup[]usersuser[]external_compute_resourceproviderstringuserstringurlstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringexternal_host_providerexternal_host_providervirtio_scsienabledbooleanlun_statusfreeusedunusableexternal_host_providerurlstringrequires_authenticationbooleanusernamestringpasswordstringauthentication_urlstringpropertiesproperty[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringcertificatescertificate[]compute_resourcesexternal_compute_resource[]discovered_hostsexternal_discovered_host[]host_groupsexternal_host_group[]hostshost[]step_enumvalidatingexecutingfinalizingrebalancing_volumeremoving_bricksunknownRepresents the IP configuration of a network interface.
<div class="paragraph">
<p>Represents the IP configuration of a network interface.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue3 Oct 2016stausvalueaddedipThe text representation of the IP address.
For example, an IPv4 address will be represented as follows:
[source,xml]
----
<ip>
<address>192.168.0.1</address>
...
</ip>
----
An IPv6 address will be represented as follows:
[source,xml]
----
<ip>
<address>2620:52:0:20f0:4216:7eff:feaa:1b50</address>
...
</ip>
----
<div class="paragraph">
<p>The text representation of the IP address.</p>
</div>
<div class="paragraph">
<p>For example, an IPv4 address will be represented as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ip>
<address>192.168.0.1</address>
...
</ip></code></pre>
</div>
</div>
<div class="paragraph">
<p>An IPv6 address will be represented as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><ip>
<address>2620:52:0:20f0:4216:7eff:feaa:1b50</address>
...
</ip></code></pre>
</div>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue3 Oct 2016stausvalueaddedaddressstringThe network mask.
<div class="paragraph">
<p>The network mask.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue3 Oct 2016stausvalueaddednetmaskstringThe address of the default gateway.
<div class="paragraph">
<p>The address of the default gateway.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue3 Oct 2016stausvalueaddedgatewaystringThe version of the IP protocol.
This attribute is optional, and when it isn't given the value will be inferred from the value of the `address`
attribute. If that value is a valid IPv4 address, then it will be assumed that the value of this attribute is
`v4`. If it is a valid IPv6 address, then it will be assumed that the value of this attribute is `v6`.
NOTE: This inference of the IP version from the value of the `address` is implemented since version 4.1 of the
engine, before that this attribute was mandatory.
<div class="paragraph">
<p>The version of the IP protocol.</p>
</div>
<div class="paragraph">
<p>This attribute is optional, and when it isn’t given the value will be inferred from the value of the <code>address</code>
attribute. If that value is a valid IPv4 address, then it will be assumed that the value of this attribute is
<code>v4</code>. If it is a valid IPv6 address, then it will be assumed that the value of this attribute is <code>v6</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This inference of the IP version from the value of the <code>address</code> is implemented since version 4.1 of the
engine, before that this attribute was mandatory.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue3 Oct 2016stausvalueaddedversionstorage_domaintypestatusexternal_statusmasterbooleanstoragehost_storageavailableintegerusedintegercommittedintegerstorage_formatwipe_after_deletebooleanimportbooleanwarning_low_space_indicatorintegercritical_space_action_blockerintegeridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringHost is only relevant at creation time.
<div class="paragraph">
<p>Host is only relevant at creation time.</p>
</div>
hosthostThis is used to link to the data center that the storage domain is attached to. It is preserved for backwards
compatibility, as the storage domain may be attached to multiple data centers (if it is an ISO domain). Use
the `dataCenters` element instead.
<div class="paragraph">
<p>This is used to link to the data center that the storage domain is attached to. It is preserved for backwards
compatibility, as the storage domain may be attached to multiple data centers (if it is an ISO domain). Use
the <code>dataCenters</code> element instead.</p>
</div>
data_centerdata_centerThis is a set of links to the data centers that the storage domain is attached to.
<div class="paragraph">
<p>This is a set of links to the data centers that the storage domain is attached to.</p>
</div>
data_centersdata_center[]disksdisk[]disk_profilesdisk_profile[]disk_snapshotsdisk_snapshot[]filesfile[]imagesimage[]permissionspermission[]storage_connectionsstorage_connection[]templatestemplate[]vmsvm[]vnic_profileport_mirroringbooleancustom_propertiescustom_property[]pass_throughvnic_pass_throughidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringnetworknetworkqosqosNetwork filter will enhance the admin ability to manage the network packets traffic from/to the participated VMs.
<div class="paragraph">
<p>Network filter will enhance the admin ability to manage the network packets traffic from/to the participated VMs.</p>
</div>
network_filternetwork_filterpermissionspermission[]gluster_volume_profile_detailsbrick_profile_detailsbrick_profile_detail[]nfs_profile_detailsnfs_profile_detail[]idstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringcoreindexintegersocketintegereventcodeintegerseveritytimedatecorrelation_idstringoriginstringcustom_idintegerflood_rateintegercustom_datastringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringuseruservmvmstorage_domainstorage_domainhosthosttemplatetemplateclusterclusterdata_centerdata_centertagidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostvmvmuserusergroupgrouptemplatetemplateparenttagreported_configurationnamestringexpected_valuestringactual_valuestringin_syncbooleanThe underlying storage format of disks.
<div class="paragraph">
<p>The underlying storage format of disks.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddeddisk_formatThe _Copy On Write_ format allows snapshots, with a small performance overhead.
<div class="paragraph">
<p>The <em>Copy On Write</em> format allows snapshots, with a small performance overhead.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedcowThe raw format does not allow snapshots, but offers improved performance.
<div class="paragraph">
<p>The raw format does not allow snapshots, but offers improved performance.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddedrawgluster_server_hookcontent_typestatuschecksumstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostdata_center_statusuninitializedupmaintenancenot_operationalproblematiccontendThis interface is intended to be the base for all types of the model that represents objects with an identifier.
<div class="paragraph">
<p>This interface is intended to be the base for all types of the model that represents objects with an identifier.</p>
</div>
identifiedidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringcputypestringtopologycpu_topologylevelintegernamestringspeeddecimalcpu_tunecpu_tunemodearchitecturecorescore[]scsi_generic_i_ofilteredunfilteredopen_stack_imageidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringopenstack_image_provideropen_stack_image_providervm_poolsizeintegerprestarted_vmsintegermax_user_vmsintegerdisplaydisplayrng_devicerng_devicesoundcard_enabledbooleantypeuse_latest_template_versionbooleanVirtual machine pool's stateful flag.
Virtual machines from a stateful virtual machine pool are always started in stateful mode
(stateless snapshot is not created). The state of the virtual machine is preserved
even when the virtual machine is passed to a different user.
<div class="paragraph">
<p>Virtual machine pool’s stateful flag.</p>
</div>
<div class="paragraph">
<p>Virtual machines from a stateful virtual machine pool are always started in stateful mode
(stateless snapshot is not created). The state of the virtual machine is preserved
even when the virtual machine is passed to a different user.</p>
</div>
statefulbooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclustertemplatetemplateReference to the instance type on which this pool is based. It can be
set only on pool creation and cannot be edited.
<div class="paragraph">
<p>Reference to the instance type on which this pool is based. It can be
set only on pool creation and cannot be edited.</p>
</div>
instance_typeinstance_typevmvmpermissionspermission[]gluster_clienthost_namestringclient_portintegerbytes_readintegerbytes_writtenintegerauthorized_keykeystringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringuseruserstorage_typeiscsifcpnfslocalfsposixfsglusterfsglancecindergroupdomain_entry_idstringnamespacestringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringdomaindomainUsed only to represent the initial role assignments for a new group, thereafter modification of role assignments
are only supported via the `roles` sub-collection.
<div class="paragraph">
<p>Used only to represent the initial role assignments for a new group, thereafter modification of role assignments
are only supported via the <code>roles</code> sub-collection.</p>
</div>
rolesrole[]permissionspermission[]tagstag[]cpu_modecustomhost_modelhost_passthroughoptionnamestringvaluestringtypestringhostaddressstringstatusstatus_detailstringcertificatecertificateexternal_statusportintegerIndicates if the host contains a full installation of the operating system or a scaled-down version intended
only to host virtual machines.
<div class="paragraph">
<p>Indicates if the host contains a full installation of the operating system or a scaled-down version intended
only to host virtual machines.</p>
</div>
authorvalueTahlia Richardson <trichard@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docstypespmspmThe version of VDSM.
For example:
[source]
----
GET /ovirt-engine/api/hosts/123
----
This `GET` request will return the following output:
[source,xml]
----
<host>
...
<version>
<build>999</build>
<full_version>vdsm-4.18.999-419.gitcf06367.el7</full_version>
<major>4</major>
<minor>18</minor>
<revision>0</revision>
</version>
...
</host>
----
<div class="paragraph">
<p>The version of VDSM.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/hosts/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>This <code>GET</code> request will return the following output:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><host>
...
<version>
<build>999</build>
<full_version>vdsm-4.18.999-419.gitcf06367.el7</full_version>
<major>4</major>
<minor>18</minor>
<revision>0</revision>
</version>
...
</host></code></pre>
</div>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>Tahlia Richardson <trichard@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsversionversionhardware_informationhardware_informationpower_managementpower_managementksmksmtransparent_huge_pagestransparent_huge_pagesiscsiiscsi_detailsWhen creating a new host, a root password is required if the password authentication method is chosen,
but this is not subsequently included in the representation.
<div class="paragraph">
<p>When creating a new host, a root password is required if the password authentication method is chosen,
but this is not subsequently included in the representation.</p>
</div>
authorvalueTahlia Richardson <trichard@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsroot_passwordstringsshsshcpucpumemoryintegermax_scheduling_memoryintegersummaryvm_summaryoverride_iptablesbooleanprotocolosoperating_systemlibvirt_versionversionOptionally specify the display address of this host explicitly.
<div class="paragraph">
<p>Optionally specify the display address of this host explicitly.</p>
</div>
authorvalueTahlia Richardson <trichard@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsdisplaydisplayhosted_enginehosted_enginekdump_statusse_linuxse_linuxauto_numa_statusnuma_supportedbooleanupdate_availablebooleandevice_passthroughhost_device_passthroughidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclusterhookshook[]external_host_providerexternal_host_providerstorage_connection_extensionsstorage_connection_extension[]affinity_labelsaffinity_label[]devicesdevice[]agentsagent[]katello_erratakatello_erratum[]network_attachmentsnetwork_attachment[]nicsnic[]numa_nodesnuma_node[]permissionspermission[]statisticsstatistic[]storageshost_storage[]tagstag[]unmanaged_networksunmanaged_network[]Logical network.
An example of the JSON representation of a logical network:
[source,json]
----
{
"network" : [ {
"data_center" : {
"href" : "/ovirt-engine/api/datacenters/123",
"id" : "123"
},
"stp" : "false",
"mtu" : "0",
"usages" : {
"usage" : [ "vm" ]
},
"name" : "ovirtmgmt",
"description" : "Management Network",
"href" : "/ovirt-engine/api/networks/456",
"id" : "456",
"link" : [ {
"href" : "/ovirt-engine/api/networks/456/permissions",
"rel" : "permissions"
}, {
"href" : "/ovirt-engine/api/networks/456/vnicprofiles",
"rel" : "vnicprofiles"
}, {
"href" : "/ovirt-engine/api/networks/456/labels",
"rel" : "labels"
} ]
} ]
}
----
An example of the XML representation of the same logical network:
[source,xml]
----
<network href="/ovirt-engine/api/networks/456" id="456">
<name>ovirtmgmt</name>
<description>Management Network</description>
<link href="/ovirt-engine/api/networks/456/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/networks/456/vnicprofiles" rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/456/labels" rel="labels"/>
<data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
<stp>false</stp>
<mtu>0</mtu>
<usages>
<usage>vm</usage>
</usages>
</network>
----
<div class="paragraph">
<p>Logical network.</p>
</div>
<div class="paragraph">
<p>An example of the JSON representation of a logical network:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-json" data-lang="json">{
"network" : [ {
"data_center" : {
"href" : "/ovirt-engine/api/datacenters/123",
"id" : "123"
},
"stp" : "false",
"mtu" : "0",
"usages" : {
"usage" : [ "vm" ]
},
"name" : "ovirtmgmt",
"description" : "Management Network",
"href" : "/ovirt-engine/api/networks/456",
"id" : "456",
"link" : [ {
"href" : "/ovirt-engine/api/networks/456/permissions",
"rel" : "permissions"
}, {
"href" : "/ovirt-engine/api/networks/456/vnicprofiles",
"rel" : "vnicprofiles"
}, {
"href" : "/ovirt-engine/api/networks/456/labels",
"rel" : "labels"
} ]
} ]
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>An example of the XML representation of the same logical network:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><network href="/ovirt-engine/api/networks/456" id="456">
<name>ovirtmgmt</name>
<description>Management Network</description>
<link href="/ovirt-engine/api/networks/456/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/networks/456/vnicprofiles" rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/456/labels" rel="labels"/>
<data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
<stp>false</stp>
<mtu>0</mtu>
<usages>
<usage>vm</usage>
</usages>
</network></code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednetworkipipvlanvlanSpecifies whether spanning tree protocol is enabled for the network.
<div class="paragraph">
<p>Specifies whether spanning tree protocol is enabled for the network.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedstpbooleanstatusdisplaybooleanSpecifies the maximum transmission unit for the network.
<div class="paragraph">
<p>Specifies the maximum transmission unit for the network.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedmtuintegerDefines a set of usage elements for the network.
Users can, for example, specify that the network is to be used for virtual machine traffic and also for
display traffic with the `vm` and `display` values.
<div class="paragraph">
<p>Defines a set of usage elements for the network.</p>
</div>
<div class="paragraph">
<p>Users can, for example, specify that the network is to be used for virtual machine traffic and also for
display traffic with the <code>vm</code> and <code>display</code> values.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedusages[]requiredbooleanprofile_requiredbooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringA reference to the data center of which the network is a member.
<div class="paragraph">
<p>A reference to the data center of which the network is a member.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddata_centerdata_centerclusterclusterqosqosA reference to the labels assigned to the network.
<div class="paragraph">
<p>A reference to the labels assigned to the network.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednetwork_labelsnetwork_label[]A reference to the permissions of the network.
<div class="paragraph">
<p>A reference to the permissions of the network.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedpermissionspermission[]A reference to the profiles of the network.
<div class="paragraph">
<p>A reference to the profiles of the network.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedvnic_profilesvnic_profile[]filterpositionintegeridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringscheduling_policy_unitscheduling_policy_unitnetwork_plugin_typeopen_vswitchvm_typedesktopserversteptypenumberintegerstatusstart_timedateend_timedateexternalbooleanexternal_typeidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringparent_stepstepjobjobstatisticsstatistic[]This type contains information regarding an image transfer being performed.
<div class="paragraph">
<p>This type contains information regarding an image transfer being performed.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4image_transferThe URL of the proxy server which the user should do I/O to. This attribute is
available only if the image transfer entity is in <<types/image_transfer_phase, transferring>>
phase. See `phase` for details.
<div class="paragraph">
<p>The URL of the proxy server which the user should do I/O to. This attribute is
available only if the image transfer entity is in <a href="#types/image_transfer_phase">transferring</a>
phase. See <code>phase</code> for details.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4proxy_urlstringThe signed ticket that should be attached as an `Authentication` header in the
HTTPS request for the proxy server to do I/O to (See `proxy_url` attribute).
<div class="paragraph">
<p>The signed ticket that should be attached as an <code>Authentication</code> header in the
HTTPS request for the proxy server to do I/O to (See <code>proxy_url</code> attribute).</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4signed_ticketstringThe current phase of the image transfer being made. Each transfer needs a managed
session, which must be opened in order for the user to be able to do I/O to an image.
Please refer to <<services/image_transfer, image transfer>> for further
documentation.
<div class="paragraph">
<p>The current phase of the image transfer being made. Each transfer needs a managed
session, which must be opened in order for the user to be able to do I/O to an image.
Please refer to <a href="#services/image_transfer">image transfer</a> for further
documentation.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4phaseidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringThe image which is targeted for I/O.
<div class="paragraph">
<p>The image which is targeted for I/O.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4imageimageThe host which will be used to write to the image which is targeted for I/O.
<div class="paragraph">
<p>The host which will be used to write to the image which is targeted for I/O.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4hosthostexternal_statuserrorfailureinfookwarninggluster_hookgluster_commandstringstagecontent_typechecksumstringcontentstringconflict_statusintegerconflictsstringstatusidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringclusterclusterserver_hooksgluster_server_hook[]Describes parameters of virtual machine import operation from external system.
<div class="paragraph">
<p>Describes parameters of virtual machine import operation from external system.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4external_vm_importType of external virtual machine provider.
<div class="paragraph">
<p>Type of external virtual machine provider.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4providerURL to be passed to the `virt-v2v` tool for conversion.
Example:
[source]
----
vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1
----
More examples can be found at http://libguestfs.org/virt-v2v.1.html.
<div class="paragraph">
<p>URL to be passed to the <code>virt-v2v</code> tool for conversion.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>vpx://wmware_user@vcenter-host/DataCenter/Cluster/esxi-host?no_verify=1</code></pre>
</div>
</div>
<div class="paragraph">
<p>More examples can be found at <a href="http://libguestfs.org/virt-v2v.1.html" class="bare">http://libguestfs.org/virt-v2v.1.html</a>.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4urlstringUsername to authenticate against external hypervisor system.
<div class="paragraph">
<p>Username to authenticate against external hypervisor system.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4usernamestringPassword to authenticate against external hypervisor system.
<div class="paragraph">
<p>Password to authenticate against external hypervisor system.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0passwordstringName of the virtual machine to be imported as is defined within the external system.
<div class="paragraph">
<p>Name of the virtual machine to be imported as is defined within the external system.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4namestringSpecifies the disk allocation policy of resulting virtual machine: `true` for sparse, `false` for preallocated.
<div class="paragraph">
<p>Specifies the disk allocation policy of resulting virtual machine: <code>true</code> for sparse, <code>false</code> for preallocated.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4sparsebooleanVirtual machine entity used to specify the name of the newly created virtual machine.
If name is not specified, the source virtual machine name will be used.
<div class="paragraph">
<p>Virtual machine entity used to specify the name of the newly created virtual machine.</p>
</div>
<div class="paragraph">
<p>If name is not specified, the source virtual machine name will be used.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4vmvmSpecifies the target cluster of the resulting virtual machine.
<div class="paragraph">
<p>Specifies the target cluster of the resulting virtual machine.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4clusterclusterSpecifies the target storage domain for converted disks.
<div class="paragraph">
<p>Specifies the target storage domain for converted disks.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4storage_domainstorage_domainOptionally specifies the cpu profile of the resulting virtual machine.
<div class="paragraph">
<p>Optionally specifies the cpu profile of the resulting virtual machine.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4cpu_profilecpu_profileOptionally specifies the quota that will be applied to the resulting virtual machine.
<div class="paragraph">
<p>Optionally specifies the quota that will be applied to the resulting virtual machine.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4quotaquotaOptional specification of host (using host's ID) to be used for the conversion process.
If not specified, one is selected automatically.
<div class="paragraph">
<p>Optional specification of host (using host’s ID) to be used for the conversion process.
If not specified, one is selected automatically.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4hosthostOptional name of ISO carrying drivers that can be used during the virt-v2v conversion process.
<div class="paragraph">
<p>Optional name of ISO carrying drivers that can be used during the virt-v2v conversion process.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4drivers_isofilestatistic_unitbits_per_secondbytesbytes_per_secondcount_per_secondnonepercentsecondsnetwork_labelidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringnetworknetworkhost_nichost_nicA policy describing how the migration is going to be treated (convergence,
how many parallel migrations allowed).
<div class="paragraph">
<p>A policy describing how the migration is going to be treated (convergence,
how many parallel migrations allowed).</p>
</div>
migration_policyidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhost_device_passthroughenabledbooleanpropertynamestringvaluestringcreation_statuspendingin_progresscompletefailedclustercpucpumemory_policymemory_policyThe compatibility version of the cluster.
All hosts in this cluster must support at least this compatibility version.
For example:
[source]
----
GET /ovirt-engine/api/clusters/123
----
Will respond:
[source,xml]
----
<cluster>
...
<version>
<major>4</major>
<minor>0</minor>
</version>
...
</cluster>
----
To update the compatibility version, use:
[source]
----
PUT /ovirt-engine/api/clusters/123
----
With a request body:
[source,xml]
----
<cluster>
<version>
<major>4</major>
<minor>1</minor>
</version>
</cluster>
----
In order to update the cluster compatibility version, all hosts in the cluster must support the new compatibility version.
<div class="paragraph">
<p>The compatibility version of the cluster.</p>
</div>
<div class="paragraph">
<p>All hosts in this cluster must support at least this compatibility version.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/clusters/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>Will respond:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cluster>
...
<version>
<major>4</major>
<minor>0</minor>
</version>
...
</cluster></code></pre>
</div>
</div>
<div class="paragraph">
<p>To update the compatibility version, use:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/clusters/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cluster>
<version>
<major>4</major>
<minor>1</minor>
</version>
</cluster></code></pre>
</div>
</div>
<div class="paragraph">
<p>In order to update the cluster compatibility version, all hosts in the cluster must support the new compatibility version.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue25 Oct 2016statusvalueupdated_by_docsversionversionsupported_versionsversion[]error_handlingerror_handlingvirt_servicebooleangluster_servicebooleanthreads_as_coresbooleantunnel_migrationbooleantrusted_servicebooleanha_reservationbooleanoptional_reasonbooleanmaintenance_reason_requiredbooleanballooning_enabledbooleandisplaydisplayksmksmserial_numberserial_numberrequired_rng_sources[]fencing_policyfencing_policymigrationmigration_optionsCustom scheduling policy properties of the cluster.
These optional properties override the properties of the
scheduling policy specified by the `scheduling_policy` link,
and apply only for this specific cluster.
For example, to update the custom properties of the cluster,
send a request:
[source]
----
PUT /ovirt-engine/api/clusters/123
----
With a request body:
[source,xml]
----
<cluster>
<custom_scheduling_policy_properties>
<property>
<name>HighUtilization</name>
<value>70</value>
</property>
</custom_scheduling_policy_properties>
</cluster>
----
Update operations using the `custom_scheduling_policy_properties` attribute
will not update the the properties of the scheduling policy specified by
the `scheduling_policy` link,
they will only be reflected on this specific cluster.
<div class="paragraph">
<p>Custom scheduling policy properties of the cluster.
These optional properties override the properties of the
scheduling policy specified by the <code>scheduling_policy</code> link,
and apply only for this specific cluster.</p>
</div>
<div class="paragraph">
<p>For example, to update the custom properties of the cluster,
send a request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/clusters/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cluster>
<custom_scheduling_policy_properties>
<property>
<name>HighUtilization</name>
<value>70</value>
</property>
</custom_scheduling_policy_properties>
</cluster></code></pre>
</div>
</div>
<div class="paragraph">
<p>Update operations using the <code>custom_scheduling_policy_properties</code> attribute
will not update the the properties of the scheduling policy specified by
the <code>scheduling_policy</code> link,
they will only be reflected on this specific cluster.</p>
</div>
authorvalueYanir Quinn <yquinn@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue25 Oct 2016statusvalueupdated_by_docssincevalue4.0.6custom_scheduling_policy_propertiesproperty[]Type of switch to be used by all networks in given cluster.
<div class="paragraph">
<p>Type of switch to be used by all networks in given cluster.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue25 Oct 2016statusvalueupdated_by_docsswitch_typeidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringReference to the default scheduling policy used by
this cluster.
NOTE: The scheduling policy properties are taken by
default from the referenced scheduling policy, but
they are overridden by the properties specified in
the `custom_scheduling_policy_properties` attribute
for this cluster.
<div class="paragraph">
<p>Reference to the default scheduling policy used by
this cluster.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The scheduling policy properties are taken by
default from the referenced scheduling policy, but
they are overridden by the properties specified in
the <code>custom_scheduling_policy_properties</code> attribute
for this cluster.
</td>
</tr>
</table>
</div>
authorvalueYanir Quinn <yquinn@redhat.com>Byron Gravenorst <bgraveno@redhat.com>datevalue25 Oct 2016statusvalueupdated_by_docsscheduling_policyscheduling_policydata_centerdata_centermanagement_networknetworkaffinity_groupsaffinity_group[]cpu_profilescpu_profile[]gluster_hooksgluster_hook[]gluster_volumesgluster_volume[]network_filtersnetwork_filter[]networksnetwork[]permissionspermission[]iscsi_bondidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringdata_centerdata_centerstorage_connectionsstorage_connection[]networksnetwork[]Represents a storage server connection.
Example:
[source,xml]
----
<storage_connection id="123">
<address>mynfs.example.com</address>
<type>nfs</type>
<path>/exports/mydata</path>
</storage_connection>
----
<div class="paragraph">
<p>Represents a storage server connection.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_connection id="123">
<address>mynfs.example.com</address>
<type>nfs</type>
<path>/exports/mydata</path>
</storage_connection></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedstorage_connectionaddressstringtypepathstringmount_optionsstringvfs_typestringnfs_versionnfs_timeointegernfs_retransintegerportintegertargetstringusernamestringpasswordstringportalstringidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringhosthostvendoridstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringRepresents a NIC of a virtual machine.
For example, the XML representation of a NIC will look like this:
[source,xml]
----
<nic href="/ovirt-engine/api/vms/123/nics/456" id="456">
<name>nic1</name>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
<interface>virtio</interface>
<linked>true</linked>
<mac>
<address>02:00:00:00:00:00</address>
</mac>
<plugged>true</plugged>
<vnic_profile href="/ovirt-engine/api/vnicprofiles/789" id="789"/>
</nic>
----
<div class="paragraph">
<p>Represents a NIC of a virtual machine.</p>
</div>
<div class="paragraph">
<p>For example, the XML representation of a NIC will look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><nic href="/ovirt-engine/api/vms/123/nics/456" id="456">
<name>nic1</name>
<vm href="/ovirt-engine/api/vms/123" id="123"/>
<interface>virtio</interface>
<linked>true</linked>
<mac>
<address>02:00:00:00:00:00</address>
</mac>
<plugged>true</plugged>
<vnic_profile href="/ovirt-engine/api/vnicprofiles/789" id="789"/>
</nic></code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednicDefines if the NIC is linked to the virtual machine.
<div class="paragraph">
<p>Defines if the NIC is linked to the virtual machine.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedlinkedbooleanThe type of driver used for the NIC.
<div class="paragraph">
<p>The type of driver used for the NIC.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedinterfaceThe MAC address of the interface.
<div class="paragraph">
<p>The MAC address of the interface.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedmacmacDefines if the NIC is plugged in to the virtual machine.
<div class="paragraph">
<p>Defines if the NIC is plugged in to the virtual machine.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedpluggedbooleanboot_protocolon_bootbooleanidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringtemplatetemplateinstance_typeinstance_typeReferences to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.
<div class="paragraph">
<p>References to the virtual machines that are using this device. A device may be used by several virtual machines;
for example, a shared disk my be used simultaneously by two or more virtual machines.</p>
</div>
authorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmsvm[]Don't use this element, use `vms` instead.
<div class="paragraph">
<p>Don’t use this element, use <code>vms</code> instead.</p>
</div>
deprecatedauthorvalueByron Gravenorst <bgraveno@redhat.com>datevalue31 Oct 2016statusvalueupdated_by_docsvmvmA reference to the network which the interface should be connected to. A blank network id is allowed.
Usage of this element for creating or updating a NIC is deprecated, use `vnic_profile` instead. It is preserved
because it is still in use by the `initialization` element, as a holder for IP addresses and other network
details.
<div class="paragraph">
<p>A reference to the network which the interface should be connected to. A blank network id is allowed.</p>
</div>
<div class="paragraph">
<p>Usage of this element for creating or updating a NIC is deprecated, use <code>vnic_profile</code> instead. It is preserved
because it is still in use by the <code>initialization</code> element, as a holder for IP addresses and other network
details.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednetworknetworkA link to the statistics for the NIC.
<div class="paragraph">
<p>A link to the statistics for the NIC.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedstatisticsstatistic[]vnic_profilevnic_profilenetwork_labelsnetwork_label[]network_attachmentsnetwork_attachment[]virtual_function_allowed_labelsnetwork_label[]virtual_function_allowed_networksnetwork[]reported_devicesreported_device[]usb_typelegacynativehost_statusdownerrorinitializinginstallinginstall_failedmaintenancenon_operationalnon_responsivepending_approvalpreparing_for_maintenanceconnectingrebootunassignedupinstalling_oskdumpinggluster_volume_statusVolume is started, and can be mounted and used by clients.
<div class="paragraph">
<p>Volume is started, and can be mounted and used by clients.</p>
</div>
upVolume needs to be started, for clients to be able to mount and use it.
<div class="paragraph">
<p>Volume needs to be started, for clients to be able to mount and use it.</p>
</div>
downWhen the status cannot be determined due to host being non-responsive.
<div class="paragraph">
<p>When the status cannot be determined due to host being non-responsive.</p>
</div>
unknowngluster_hook_statusHook is enabled in the cluster.
<div class="paragraph">
<p>Hook is enabled in the cluster.</p>
</div>
enabledHook is disabled in the cluster.
<div class="paragraph">
<p>Hook is disabled in the cluster.</p>
</div>
disabledUnknown/missing hook status.
<div class="paragraph">
<p>Unknown/missing hook status.</p>
</div>
missinggluster_brick_statusBrick is in `up` state, the data can be stored or retrieved from it.
<div class="paragraph">
<p>Brick is in <code>up</code> state, the data can be stored or retrieved from it.</p>
</div>
upBrick is in `down` state, the data cannot be stored or retrieved from it.
<div class="paragraph">
<p>Brick is in <code>down</code> state, the data cannot be stored or retrieved from it.</p>
</div>
downWhen the status cannot be determined due to host being non-responsive.
<div class="paragraph">
<p>When the status cannot be determined due to host being non-responsive.</p>
</div>
unknownfaultreasonstringdetailstringgrace_periodexpiryintegeractionstatusstringfaultfaultgrace_periodgrace_periodjobjobasyncbooleanbricksgluster_brick[]certificatescertificate[]check_connectivitybooleanclonebooleanclusterclustercollapse_snapshotsbooleanconnectivity_timeoutintegerdata_centerdata_centerdeploy_hosted_enginebooleandetailsgluster_volume_profile_detailsdiscard_snapshotsbooleandiskdiskdisksdisk[]exclusivebooleanfence_typestringfilterbooleanfix_layoutbooleanforcebooleanhosthostimagestringimport_as_templatebooleanis_attachedbooleaniscsiiscsi_detailsiscsi_targetsstring[]logical_unitslogical_unit[]maintenance_enabledbooleanmodified_bondshost_nic[]modified_labelsnetwork_label[]modified_network_attachmentsnetwork_attachment[]optionoptionpausebooleanpower_managementpower_managementproxy_ticketproxy_ticketreasonstringremoved_bondshost_nic[]removed_labelsnetwork_label[]removed_network_attachmentsnetwork_attachment[]resolution_typestringrestore_memorybooleanroot_passwordstringsnapshotsnapshotsshsshstop_gluster_servicebooleanstorage_domainstorage_domainstorage_domainsstorage_domain[]succeededbooleansynchronized_network_attachmentsnetwork_attachment[]templatetemplateticketticketundeploy_hosted_enginebooleanuse_cloud_initbooleanuse_sysprepbooleanvirtual_functions_configurationhost_nic_virtual_functions_configurationvmvmidstringA human readable name in plain text.
<div class="paragraph">
<p>A human readable name in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednamestringA human readable description in plain text.
<div class="paragraph">
<p>A human readable description in plain text.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddeddescriptionstringFree text containing comments about this object.
<div class="paragraph">
<p>Free text containing comments about this object.</p>
</div>
commentstringareavalueNetworkvnic_profilesaddprofiletruetruevnic_profilelistprofilesfalsefalsevnic_profile[]Sets the maximum number of profiles to return. If not specified all the profiles are returned.
<div class="paragraph">
<p>Sets the maximum number of profiles to return. If not specified all the profiles are returned.</p>
</div>
maxtruetrueintegerprofilevnic_profileidfalsefalsestringareavalueSLAscheduling_policy_unitgetunitfalsefalsescheduling_policy_unitIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworkvirtual_function_allowed_networkgetnetworkfalsefalsenetworkremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworktemplate_nicsaddnictruetrueniclistnicsfalsefalsenic[]Sets the maximum number of NICs to return. If not specified all the NICs are returned.
<div class="paragraph">
<p>Sets the maximum number of NICs to return. If not specified all the NICs are returned.</p>
</div>
maxtruetrueintegernictemplate_nicidfalsefalsestringSingle affinity label details.
<div class="paragraph">
<p>Single affinity label details.</p>
</div>
affinity_labelRetrieves details about a label.
<div class="paragraph">
<p>Retrieves details about a label.</p>
</div>
getlabelfalsefalseaffinity_labelUpdates a label.
This call will update all metadata like name
or description.
<div class="paragraph">
<p>Updates a label.</p>
</div>
<div class="paragraph">
<p>This call will update all metadata like name
or description.</p>
</div>
updatelabeltruetrueaffinity_labelRemoves a label from system and clears all assignments
of the removed label.
<div class="paragraph">
<p>Removes a label from system and clears all assignments
of the removed label.</p>
</div>
removeList all VMs with this label.
<div class="paragraph">
<p>List all VMs with this label.</p>
</div>
vmsaffinity_label_vmsList all Hosts with this label.
<div class="paragraph">
<p>List all Hosts with this label.</p>
</div>
hostsaffinity_label_hostsareavalueInfrastructurebookmarksaddbookmarktruetruebookmarklistbookmarksfalsefalsebookmark[]Sets the maximum number of bookmarks to return. If not specified all the bookmarks are returned.
<div class="paragraph">
<p>Sets the maximum number of bookmarks to return. If not specified all the bookmarks are returned.</p>
</div>
maxtruetrueintegerbookmarkbookmarkidfalsefalsestringareavalueNetworknetwork_attachmentsaddattachmenttruetruenetwork_attachmentlistattachmentsfalsefalsenetwork_attachment[]Sets the maximum number of attachments to return. If not specified all the attachments are returned.
<div class="paragraph">
<p>Sets the maximum number of attachments to return. If not specified all the attachments are returned.</p>
</div>
maxtruetrueintegerattachmentnetwork_attachmentidfalsefalsestringareavalueVirtualizationoperating_systemgetoperating_systemfalsefalseoperating_system_infoareavalueStoragetemplate_diskslistdisksfalsefalsedisk[]Sets the maximum number of disks to return. If not specified all the disks are returned.
<div class="paragraph">
<p>Sets the maximum number of disks to return. If not specified all the disks are returned.</p>
</div>
maxtruetrueintegerdisktemplate_diskidfalsefalsestringThis 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.
<div class="paragraph">
<p>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.</p>
</div>
areavalueInfrastructuresystem_permissionsaddpermissiontruetruepermissionlistpermissionsfalsefalsepermission[]Sub-resource locator method, returns individual permission resource on which the remainder of the URI is
dispatched.
<div class="paragraph">
<p>Sub-resource locator method, returns individual permission resource on which the remainder of the URI is
dispatched.</p>
</div>
permissionpermissionidfalsefalsestringareavalueVirtualizationvm_reported_devicegetreported_devicefalsefalsereported_deviceareavalueNetworksnapshot_nicslistnicsfalsefalsenic[]Sets the maximum number of NICs to return. If not specified all the NICs are returned.
<div class="paragraph">
<p>Sets the maximum number of NICs to return. If not specified all the NICs are returned.</p>
</div>
maxtruetrueintegernicsnapshot_nicidfalsefalsestringareavalueNetworkassigned_vnic_profilesaddprofiletruetruevnic_profilelistprofilesfalsefalsevnic_profile[]Sets the maximum number of profiles to return. If not specified all the profiles are returned.
<div class="paragraph">
<p>Sets the maximum number of profiles to return. If not specified all the profiles are returned.</p>
</div>
maxtruetrueintegerprofileassigned_vnic_profileidfalsefalsestringareavalueSLAquota_cluster_limitsaddlimittruetruequota_cluster_limitlistlimitsfalsefalsequota_cluster_limit[]Sets the maximum number of limits to return. If not specified all the limits are returned.
<div class="paragraph">
<p>Sets the maximum number of limits to return. If not specified all the limits are returned.</p>
</div>
maxtruetrueintegerlimitquota_cluster_limitidfalsefalsestringManages 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.
<div class="paragraph">
<p>Manages logical networks.</p>
</div>
<div class="paragraph">
<p>The engine creates a default <code>ovirtmgmt</code> network on installation. This network acts as the management network for
access to hypervisor hosts. This network is associated with the <code>Default</code> cluster and is a member of the <code>Default</code>
data center.</p>
</div>
areavalueNetworkauthorvalueOri Ben Sasson <obensass@redhat.com>datevalue20 Sep 2016statusvalueaddednetworksCreates 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:
[source]
----
POST /ovirt-engine/api/networks
----
With a request body like this:
[source,xml]
----
<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:
[source]
----
POST /ovirt-engine/api/datacenters/123/networks
----
With a request body like this:
[source,xml]
----
<network>
<name>ovirtmgmt</name>
</network>
----
<div class="paragraph">
<p>Creates a new logical network, or associates an existing network with a data center.</p>
</div>
<div class="paragraph">
<p>Creation of a new network requires the <code>name</code> and <code>data_center</code> elements.</p>
</div>
<div class="paragraph">
<p>For example, to create a network named <code>mynetwork</code> for data center <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/networks</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><network>
<name>mynetwork</name>
<data_center id="123"/>
</network></code></pre>
</div>
</div>
<div class="paragraph">
<p>To associate the existing network <code>456</code> with the data center <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/datacenters/123/networks</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><network>
<name>ovirtmgmt</name>
</network></code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue24 Oct 2016statusvalueaddedaddnetworktruetruenetworkList logical networks.
For example:
[source]
----
GET /ovirt-engine/api/networks
----
Will respond:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>List logical networks.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/networks</code></pre>
</div>
</div>
<div class="paragraph">
<p>Will respond:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueOri Ben Sasson <obensass@redhat.com>datevalue14 Sep 2016statusvalueaddedlistnetworksfalsefalsenetwork[]Sets the maximum number of networks to return. If not specified all the networks are returned.
<div class="paragraph">
<p>Sets the maximum number of networks to return. If not specified all the networks are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned networks.
<div class="paragraph">
<p>A query string used to restrict the returned networks.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleannetworknetworkidfalsefalsestringAffinity groups service manages virtual machine relationships and dependencies.
<div class="paragraph">
<p>Affinity groups service manages virtual machine relationships and dependencies.</p>
</div>
areavalueSLAauthorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedaffinity_groupsCreate a new affinity group.
Post a request like in the example below to create a new affinity group:
[source]
----
POST /ovirt-engine/api/clusters/000-000/affinitygroups
----
And use the following example in its body:
[source,xml]
----
<affinity_group>
<name>AF_GROUP_001</name>
<positive>true</positive>
<enforcing>true</enforcing>
</affinity_group>
----
<div class="paragraph">
<p>Create a new affinity group.</p>
</div>
<div class="paragraph">
<p>Post a request like in the example below to create a new affinity group:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/clusters/000-000/affinitygroups</code></pre>
</div>
</div>
<div class="paragraph">
<p>And use the following example in its body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><affinity_group>
<name>AF_GROUP_001</name>
<positive>true</positive>
<enforcing>true</enforcing>
</affinity_group></code></pre>
</div>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedaddThe affinity group object to create.
<div class="paragraph">
<p>The affinity group object to create.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedgrouptruetrueaffinity_groupList existing affinity groups.
<div class="paragraph">
<p>List existing affinity groups.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedlistThe list of existing affinity groups.
<div class="paragraph">
<p>The list of existing affinity groups.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedgroupsfalsefalseaffinity_group[]Sets the maximum number of affinity groups to return. If not specified all the affinity groups are returned.
<div class="paragraph">
<p>Sets the maximum number of affinity groups to return. If not specified all the affinity groups are returned.</p>
</div>
maxtruetrueintegerAccess affinity group service that manages the affinity group specified by an id.
<div class="paragraph">
<p>Access affinity group service that manages the affinity group specified by an id.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedgroupaffinity_groupidfalsefalsestringareavalueStoragedisk_snapshotgetsnapshotfalsefalsedisk_snapshotremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueSLAscheduling_policygetpolicyfalsefalsescheduling_policyIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanupdatepolicytruetruescheduling_policyIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanfiltersfiltersweightsweightsbalancesbalancesareavalueNetworknetwork_attachmentgetattachmentfalsefalsenetwork_attachmentupdateattachmenttruetruenetwork_attachmentIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueStoragedisk_profilesaddprofiletruetruedisk_profilelistprofilefalsefalsedisk_profile[]Sets the maximum number of profiles to return. If not specified all the profiles are returned.
<div class="paragraph">
<p>Sets the maximum number of profiles to return. If not specified all the profiles are returned.</p>
</div>
maxtruetrueintegerdisk_profiledisk_profileidfalsefalsestringareavalueVirtualizationicongeticonfalsefalseiconThis service represents one label to entity assignment
when accessed using the entities/affinitylabels subcollection.
<div class="paragraph">
<p>This service represents one label to entity assignment
when accessed using the entities/affinitylabels subcollection.</p>
</div>
assigned_affinity_labelRetrieves details about the attached label.
<div class="paragraph">
<p>Retrieves details about the attached label.</p>
</div>
getlabelfalsefalseaffinity_labelRemoves the label from an entity. Does not touch the label itself.
<div class="paragraph">
<p>Removes the label from an entity. Does not touch the label itself.</p>
</div>
removeareavalueVirtualizationcpu_profilesaddprofiletruetruecpu_profilelistprofilefalsefalsecpu_profile[]Sets the maximum number of profiles to return. If not specified all the profiles are returned.
<div class="paragraph">
<p>Sets the maximum number of profiles to return. If not specified all the profiles are returned.</p>
</div>
maxtruetrueintegerprofilecpu_profileidfalsefalsestringareavalueNetworkmac_poolsCreates 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:
[source]
----
POST /ovirt-engine/api/macpools
----
With a request body like this:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Creates a new MAC address pool.</p>
</div>
<div class="paragraph">
<p>Creation of a MAC address pool requires values for the <code>name</code> and <code>ranges</code> attributes.</p>
</div>
<div class="paragraph">
<p>For example, to create MAC address pool send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/macpools</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedaddpooltruetruemac_poollistpoolsfalsefalsemac_pool[]Sets the maximum number of pools to return. If not specified all the pools are returned.
<div class="paragraph">
<p>Sets the maximum number of pools to return. If not specified all the pools are returned.</p>
</div>
maxtruetrueintegermac_poolmac_poolidfalsefalsestringThis service manages a collection of all virtual machines assigned to an affinity group.
<div class="paragraph">
<p>This service manages a collection of all virtual machines assigned to an affinity group.</p>
</div>
areavalueSLAauthorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedaffinity_group_vmsAdd a virtual machine to the affinity group.
For example to add the virtual machine 000-000 to affinity group 123-456 send a request to:
[source]
----
POST /ovirt-engine/api/clusters/000-000/affinitygroups/123-456/vms
----
With the following body:
[source,xml]
----
<vm id="000-000"/>
----
<div class="paragraph">
<p>Add a virtual machine to the affinity group.</p>
</div>
<div class="paragraph">
<p>For example to add the virtual machine 000-000 to affinity group 123-456 send a request to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/clusters/000-000/affinitygroups/123-456/vms</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the following body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm id="000-000"/></code></pre>
</div>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedaddvmtruetruevmList all virtual machines assigned to this affinity group.
<div class="paragraph">
<p>List all virtual machines assigned to this affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedlistvmsfalsefalsevm[]Sets the maximum number of virtual machines to return. If not specified all the virtual machines are
returned.
<div class="paragraph">
<p>Sets the maximum number of virtual machines to return. If not specified all the virtual machines are
returned.</p>
</div>
maxtruetrueintegerAccess the service that manages the virtual machine assignment to this affinity group.
<div class="paragraph">
<p>Access the service that manages the virtual machine assignment to this affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedvmaffinity_group_vmidfalsefalsestringareavalueSLAqosgetqosfalsefalseqosupdateqostruetrueqosIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueInfrastructuretagsaddtagtruetruetaglisttagsfalsefalsetag[]Sets the maximum number of tags to return. If not specified all the tags are returned.
<div class="paragraph">
<p>Sets the maximum number of tags to return. If not specified all the tags are returned.</p>
</div>
maxtruetrueintegertagtagidfalsefalsestringareavalueInfrastructureexternal_provider_certificategetcertificatefalsefalsecertificateareavalueInfrastructureeventsAdds 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:
[source]
----
POST /ovirt-engine/api/events
<event>
<description>File system /home is full</description>
<severity>alert</severity>
<origin>mymonitor</origin>
<custom_id>1467879754</custom_id>
</event>
----
Events can also be linked to specific objects. For example, the above event could be linked to the specific
virtual machine where it happened, using the `vm` link:
[source]
----
POST /ovirt-engine/api/events
<event>
<description>File system /home is full</description>
<severity>alert</severity>
<origin>mymonitor</origin>
<custom_id>1467879754</custom_id>
<vm id="aae98225-5b73-490d-a252-899209af17e9"/>
</event>
----
NOTE: When using links, like the `vm` in the previous example, only the `id` attribute is accepted. The `name`
attribute, if provided, is simply ignored.
<div class="paragraph">
<p>Adds an external event to the internal audit log.</p>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>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></code></pre>
</div>
</div>
<div class="paragraph">
<p>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 <code>vm</code> link:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>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></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
When using links, like the <code>vm</code> in the previous example, only the <code>id</code> attribute is accepted. The <code>name</code>
attribute, if provided, is simply ignored.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue7 Jul 2016statusvalueaddedaddeventtruetrueeventGet list of events.
[source]
----
GET /ovirt-engine/api/events
----
To the above request we get following reponse:
[source,xml]
----
<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.
<div class="paragraph">
<p>Get list of events.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/events</code></pre>
</div>
</div>
<div class="paragraph">
<p>To the above request we get following reponse:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>The following events occur:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>id="1" - The API logs in the admin user account.</p>
</li>
<li>
<p>id="2" - The API logs out of the admin user account.</p>
</li>
</ul>
</div>
authorvaluePiotr Kliczewski <pkliczew@redhat.com>datevalue14 Sep 2016statusvalueaddedlisteventsfalsefalseevent[]Indicates the identifier of the the first event that should be returned. The identifiers of events are
strictly increasing, so when this parameter is used only the events with that identifiers equal or greater
than the given value will be returned. For example, the following request will return only the events
with identifiers greater or equal than `123`:
[source]
----
GET /ovirt-engine/api/events?from=123
----
This parameter is optional, and if not specified then the first event returned will be most recently
generated.
<div class="paragraph">
<p>Indicates the identifier of the the first event that should be returned. The identifiers of events are
strictly increasing, so when this parameter is used only the events with that identifiers equal or greater
than the given value will be returned. For example, the following request will return only the events
with identifiers greater or equal than <code>123</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/events?from=123</code></pre>
</div>
</div>
<div class="paragraph">
<p>This parameter is optional, and if not specified then the first event returned will be most recently
generated.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue6 Jul 2016statusvalueaddedfromtruetrueintegerSets the maximum number of events to return. If not specified all the events are returned.
<div class="paragraph">
<p>Sets the maximum number of events to return. If not specified all the events are returned.</p>
</div>
maxtruetrueintegerThe events service provides search queries similar to other resource services.
We can search by providing specific severity.
[source]
----
GET /ovirt-engine/api/events?search=severity%3Dnormal
----
To the above request we get a list of events which severity is equal to `normal`:
[source,xml]
----
<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:
[source]
----
sortby time asc page 1
----
Below example paginates event resources. The URL-encoded request is:
[source]
----
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201
----
Increase the page value to view the next page of results.
[source]
----
GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202
----
<div class="paragraph">
<p>The events service provides search queries similar to other resource services.</p>
</div>
<div class="paragraph">
<p>We can search by providing specific severity.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/events?search=severity%3Dnormal</code></pre>
</div>
</div>
<div class="paragraph">
<p>To the above request we get a list of events which severity is equal to <code>normal</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>sortby time asc page 1</code></pre>
</div>
</div>
<div class="paragraph">
<p>Below example paginates event resources. The URL-encoded request is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%201</code></pre>
</div>
</div>
<div class="paragraph">
<p>Increase the page value to view the next page of results.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/events?search=sortby%20time%20asc%20page%202</code></pre>
</div>
</div>
authorvaluePiotr Kliczewski <pkliczew@redhat.com>datevalue14 Sep 2016statusvalueaddedsearchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanundeleteIndicates if the un-delete should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the un-delete should be performed asynchronously.</p>
</div>
asynctruetruebooleaneventeventidfalsefalsestringareavalueVirtualizationvm_watchdoggetwatchdogfalsefalsewatchdogupdatewatchdogtruetruewatchdogIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueStorageattached_storage_domainThis operation activates an attached storage domain.
Once the storage domain is activated it is ready for use with the data center.
[source]
----
POST /ovirt-engine/api/datacenters/123/storagedomains/456/activate
----
The activate action does not take any action specific parameters,
so the request body should contain an empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>This operation activates an attached storage domain.
Once the storage domain is activated it is ready for use with the data center.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/datacenters/123/storagedomains/456/activate</code></pre>
</div>
</div>
<div class="paragraph">
<p>The activate action does not take any action specific parameters,
so the request body should contain an empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueMaor Lipchuk <mlipchuk@redhat.com>datevalue14 Sep 2016statusvalueaddedactivateIndicates if the activation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the activation should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis operation deactivates an attached storage domain.
Once the storage domain is deactivated it will not be used with the data center.
[source]
----
POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate
----
The deactivate action does not take any action specific parameters,
so the request body should contain an empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>This operation deactivates an attached storage domain.
Once the storage domain is deactivated it will not be used with the data center.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/datacenters/123/storagedomains/456/deactivate</code></pre>
</div>
</div>
<div class="paragraph">
<p>The deactivate action does not take any action specific parameters,
so the request body should contain an empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueMaor Lipchuk <mlipchuk@redhat.com>datevalue14 Sep 2016statusvalueaddeddeactivateIndicates if the deactivation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the deactivation should be performed asynchronously.</p>
</div>
asynctruetruebooleangetstorage_domainfalsefalsestorage_domainremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleandisksdisksareavalueStorageattached_storage_domainsaddstorage_domaintruetruestorage_domainliststorage_domainsfalsefalsestorage_domain[]Sets the maximum number of storage domains to return. If not specified all the storage domains are returned.
<div class="paragraph">
<p>Sets the maximum number of storage domains to return. If not specified all the storage domains are returned.</p>
</div>
maxtruetrueintegerstorage_domainattached_storage_domainidfalsefalsestringareavalueVirtualizationinstance_type_watchdoggetwatchdogfalsefalsewatchdogupdatewatchdogtruetruewatchdogIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueSLAquota_storage_limitgetlimitfalsefalsequota_storage_limitremoveIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueInfrastructurerolegetrolefalsefalseroleRemoves the role.
To remove the role you need to know its id, then send request like this:
[source]
----
DELETE /ovirt-engine/api/roles/{role_id}
----
<div class="paragraph">
<p>Removes the role.</p>
</div>
<div class="paragraph">
<p>To remove the role you need to know its id, then send request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/roles/{role_id}</code></pre>
</div>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanUpdates 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
<<services/permits, service>> that manages permits of role.
For example to update role's `name`, `description` and `administrative` attributes send a request like this:
[source]
----
PUT /ovirt-engine/api/roles/123
----
With a request body like this:
[source,xml]
----
<role>
<name>MyNewRoleName</name>
<description>My new description of the role</description>
<administrative>true</administrative>
</group>
----
<div class="paragraph">
<p>Updates a role. You are allowed to update <code>name</code>, <code>description</code> and <code>administrative</code> attributes after role is
created. Within this endpoint you can’t add or remove roles permits you need to use
<a href="#services/permits">service</a> that manages permits of role.</p>
</div>
<div class="paragraph">
<p>For example to update role’s <code>name</code>, <code>description</code> and <code>administrative</code> attributes send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/roles/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><role>
<name>MyNewRoleName</name>
<description>My new description of the role</description>
<administrative>true</administrative>
</group></code></pre>
</div>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddedupdateroletruetrueroleIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanpermitspermitsareavalueNetworkassigned_networkgetnetworkfalsefalsenetworkremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanupdatenetworktruetruenetworkIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanReturns the details of the disks attached to a virtual machine in the export domain.
<div class="paragraph">
<p>Returns the details of the disks attached to a virtual machine in the export domain.</p>
</div>
areavalueStorageauthorvalueTal Nisan <tnisan@redhat.com>datevalue6 Sep 2016statusvalueaddedsincevalue4.0.4storage_domain_vm_disk_attachmentReturns the details of the attachment with all its properties and a link to the disk.
<div class="paragraph">
<p>Returns the details of the attachment with all its properties and a link to the disk.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue6 Sep 2016statusvalueaddedsincevalue4.0.4getThe disk attachment.
<div class="paragraph">
<p>The disk attachment.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue6 Sep 2016statusvalueaddedsincevalue4.0.4attachmentfalsefalsedisk_attachmentareavalueNetworkhost_nicslistnicsfalsefalsehost_nic[]Sets the maximum number of NICs to return. If not specified all the NICs are returned.
<div class="paragraph">
<p>Sets the maximum number of NICs to return. If not specified all the NICs are returned.</p>
</div>
maxtruetrueintegernichost_nicidfalsefalsestringareavalueSLAvm_numa_nodegetnodefalsefalsevirtual_numa_nodeUpdates a virtual NUMA node.
An example of pinning a virtual NUMA node to a physical NUMA node on the host:
[source]
----
PUT /ovirt-engine/api/vms/123/numanodes/456
----
The request body should contain the following:
[source,xml]
----
<vm_numa_node>
<numa_node_pins>
<numa_node_pin>
<host_numa_node id="789"/>
<index>0</index>
<pinned>true</pinned>
</numa_node_pin>
</numa_node_pins>
</vm_numa_node>
----
<div class="paragraph">
<p>Updates a virtual NUMA node.</p>
</div>
<div class="paragraph">
<p>An example of pinning a virtual NUMA node to a physical NUMA node on the host:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123/numanodes/456</code></pre>
</div>
</div>
<div class="paragraph">
<p>The request body should contain the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm_numa_node>
<numa_node_pins>
<numa_node_pin>
<host_numa_node id="789"/>
<index>0</index>
<pinned>true</pinned>
</numa_node_pin>
</numa_node_pins>
</vm_numa_node></code></pre>
</div>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedupdatenodetruetruevirtual_numa_nodeIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves a virtual NUMA node.
An example of removing a virtual NUMA node:
[source]
----
DELETE /ovirt-engine/api/vms/123/numanodes/456
----
<div class="paragraph">
<p>Removes a virtual NUMA node.</p>
</div>
<div class="paragraph">
<p>An example of removing a virtual NUMA node:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/vms/123/numanodes/456</code></pre>
</div>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueVirtualizationtemplate_cdromslistcdromsfalsefalsecdrom[]Sets the maximum number of CDROMs to return. If not specified all the CDROMs are returned.
<div class="paragraph">
<p>Sets the maximum number of CDROMs to return. If not specified all the CDROMs are returned.</p>
</div>
maxtruetrueintegercdromtemplate_cdromidfalsefalsestringareavalueStoragesnapshotgetsnapshotfalsefalsesnapshotremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanRestores a virtual machine snapshot.
For example, to restore the snapshot with identifier `456` of virtual machine with identifier `123` send a
request like this:
[source]
----
POST /ovirt-engine/api/vms/123/snapshots/456/restore
----
With an empty `action` in the body:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>Restores a virtual machine snapshot.</p>
</div>
<div class="paragraph">
<p>For example, to restore the snapshot with identifier <code>456</code> of virtual machine with identifier <code>123</code> send a
request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/snapshots/456/restore</code></pre>
</div>
</div>
<div class="paragraph">
<p>With an empty <code>action</code> in the body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedrestorediskstruetruedisk[]restore_memorytruetruebooleanIndicates if the restore should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the restore should be performed asynchronously.</p>
</div>
asynctruetruebooleancdromssnapshot_cdromsdiskssnapshot_disksnicssnapshot_nicsareavalueSLAscheduling_policiesaddpolicytruetruescheduling_policylistpoliciesfalsefalsescheduling_policy[]Sets the maximum number of policies to return. If not specified all the policies are returned.
<div class="paragraph">
<p>Sets the maximum number of policies to return. If not specified all the policies are returned.</p>
</div>
maxtruetrueintegerIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanpolicyscheduling_policyidfalsefalsestringareavalueSLAweightsaddweighttruetrueweightlistweightsfalsefalseweight[]Sets the maximum number of weights to return. If not specified all the weights are returned.
<div class="paragraph">
<p>Sets the maximum number of weights to return. If not specified all the weights are returned.</p>
</div>
maxtruetrueintegerIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanweightweightidfalsefalsestringareavalueVirtualizationvm_host_devicesadddevicetruetruehost_devicelistdevicefalsefalsehost_device[]Sets the maximum number of devices to return. If not specified all the devices are returned.
<div class="paragraph">
<p>Sets the maximum number of devices to return. If not specified all the devices are returned.</p>
</div>
maxtruetrueintegerdevicevm_host_deviceidfalsefalsestringareavalueVirtualizationassigned_cpu_profilegetprofilefalsefalsecpu_profileremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworksnapshot_nicgetnicfalsefalsenicareavalueVirtualizationhost_devicegetdevicefalsefalsehost_deviceThis service manages image transfers, for performing Image I/O API in oVirt.
Please refer to <<services/image_transfer, image transfer>> for further
documentation.
<div class="paragraph">
<p>This service manages image transfers, for performing Image I/O API in oVirt.
Please refer to <a href="#services/image_transfer">image transfer</a> for further
documentation.</p>
</div>
areavalueStorageauthorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4image_transfersAdd a new image transfer. An image needs to be specified in order to make
a new transfer.
<div class="paragraph">
<p>Add a new image transfer. An image needs to be specified in order to make
a new transfer.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4addimage_transfertruetrueimage_transferRetrieves the list of image transfers that are currently
being performed.
<div class="paragraph">
<p>Retrieves the list of image transfers that are currently
being performed.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4listimage_transferfalsefalseimage_transfer[]Returns a reference to the service that manages an
specific image transfer.
<div class="paragraph">
<p>Returns a reference to the service that manages an
specific image transfer.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4image_transferimage_transferidfalsefalsestringareavalueInfrastructureexternal_providerimport_certificatescertificatestruetruecertificate[]test_connectivityIndicates if the test should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the test should be performed asynchronously.</p>
</div>
asynctruetruebooleancertificatesexternal_provider_certificatesareavalueInfrastructureeventgeteventfalsefalseeventRemoves an event from internal audit log.
An event can be removed by sending following request
[source]
----
DELETE /ovirt-engine/api/events/123
----
<div class="paragraph">
<p>Removes an event from internal audit log.</p>
</div>
<div class="paragraph">
<p>An event can be removed by sending following request</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/events/123</code></pre>
</div>
</div>
authorvaluePiotr Kliczewski <pkliczew@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueVirtualizationgraphics_consolesaddconsoletruetruegraphics_consoleLists all the configured graphics consoles of the virtual machine.
<div class="paragraph">
<p>Lists all the configured graphics consoles of the virtual machine.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue8 Jul 2016statusvalueaddedlistconsolesfalsefalsegraphics_console[]Sets the maximum number of consoles to return. If not specified all the consoles are returned.
<div class="paragraph">
<p>Sets the maximum number of consoles to return. If not specified all the consoles are returned.</p>
</div>
maxtruetrueintegerUse the following query to obtain the current run-time configuration of the graphics consoles.
[source]
----
GET /ovit-engine/api/vms/{vm:id}/graphicsconsoles?current=true
----
The default value is `false`.
<div class="paragraph">
<p>Use the following query to obtain the current run-time configuration of the graphics consoles.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovit-engine/api/vms/{vm:id}/graphicsconsoles?current=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>The default value is <code>false</code>.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue8 Jul 2016statusvalueaddedcurrenttruetruebooleanconsolegraphics_consoleidfalsefalsestringRepresents 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 <<services/network_filter,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:
[source]
----
GET http://localhost:8080/ovirt-engine/api/clusters/{cluster:id}/networkfilters
----
Output:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Represents a readonly network filters sub-collection.</p>
</div>
<div class="paragraph">
<p>The network filter enables to filter packets send to/from the VM’s nic according to defined rules.
For more information please refer to <a href="#services/network_filter">NetworkFilter</a> service documentation</p>
</div>
<div class="paragraph">
<p>Network filters are supported in different versions, starting from version 3.0.</p>
</div>
<div class="paragraph">
<p>A network filter is defined for each vnic profile.</p>
</div>
<div class="paragraph">
<p>A vnic profile is defined for a specific network.</p>
</div>
<div class="paragraph">
<p>A network can be assigned to several different clusters. In the future, each network will be defined in
cluster level.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>Example of listing all of the supported network filters for a specific cluster:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET http://localhost:8080/ovirt-engine/api/clusters/{cluster:id}/networkfilters</code></pre>
</div>
</div>
<div class="paragraph">
<p>Output:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
areavalueNetworknetwork_filtersRetrieves the representations of the network filters.
<div class="paragraph">
<p>Retrieves the representations of the network filters.</p>
</div>
listfiltersfalsefalsenetwork_filter[]network_filternetwork_filteridfalsefalsestringareavalueInfrastructurestatisticgetstatistictruetruestatisticProvides capability to import external virtual machines.
<div class="paragraph">
<p>Provides capability to import external virtual machines.</p>
</div>
areavalueVirtualizationauthorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4external_vm_importsThis 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:
[source]
----
POST /externalvmimports
----
With request body of type <<types/external_vm_import,ExternalVmImport>>, for example:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>This operation is used to import a virtual machine from external hypervisor, such as KVM, XEN or VMware.</p>
</div>
<div class="paragraph">
<p>For example import of a virtual machine from VMware can be facilitated using the following request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /externalvmimports</code></pre>
</div>
</div>
<div class="paragraph">
<p>With request body of type <a href="#types/external_vm_import">ExternalVmImport</a>, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0addimporttruetrueexternal_vm_importRepresents a roles sub-collection, for example scoped by user.
<div class="paragraph">
<p>Represents a roles sub-collection, for example scoped by user.</p>
</div>
areavalueInfrastructureassigned_roleslistrolesfalsefalserole[]Sets the maximum number of roles to return. If not specified all the roles are returned.
<div class="paragraph">
<p>Sets the maximum number of roles to return. If not specified all the roles are returned.</p>
</div>
maxtruetrueintegerSub-resource locator method, returns individual role resource on which the remainder of the URI is dispatched.
<div class="paragraph">
<p>Sub-resource locator method, returns individual role resource on which the remainder of the URI is dispatched.</p>
</div>
roleroleidfalsefalsestringareavalueStorageopenstack_image_providerimport_certificatescertificatestruetruecertificate[]test_connectivityIndicates if the test should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the test should be performed asynchronously.</p>
</div>
asynctruetruebooleangetproviderfalsefalseopen_stack_image_providerupdateprovidertruetrueopen_stack_image_providerIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleancertificatesexternal_provider_certificatesimagesopenstack_imagesareavalueNetworkopenstack_networkgetnetworkfalsefalseopen_stack_networkThis operation imports an external network into oVirt.
The network will be added to the data center specified.
<div class="paragraph">
<p>This operation imports an external network into oVirt.
The network will be added to the data center specified.</p>
</div>
importThe 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.
<div class="paragraph">
<p>The data center into which the network is to be imported.
Data center is mandatory, and can be specified
using the <code>id</code> or <code>name</code> attributes, the rest of
the attributes will be ignored.</p>
</div>
data_centertruetruedata_centerIndicates if the import should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the import should be performed asynchronously.</p>
</div>
asynctruetruebooleansubnetsopenstack_subnetsareavalueStorageopenstack_image_providersaddprovidertruetrueopen_stack_image_providerlistprovidersfalsefalseopen_stack_image_provider[]Sets the maximum number of providers to return. If not specified all the providers are returned.
<div class="paragraph">
<p>Sets the maximum number of providers to return. If not specified all the providers are returned.</p>
</div>
maxtruetrueintegerprovideropenstack_image_provideridfalsefalsestringareavalueStorageopenstack_volume_authentication_keygetkeyfalsefalseopenstack_volume_authentication_keyupdatekeytruetrueopenstack_volume_authentication_keyremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueStorageopenstack_imagesLists the images of a Glance image storage domain.
<div class="paragraph">
<p>Lists the images of a Glance image storage domain.</p>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedlistimagesfalsefalseopen_stack_image[]Sets the maximum number of images to return. If not specified all the images are returned.
<div class="paragraph">
<p>Sets the maximum number of images to return. If not specified all the images are returned.</p>
</div>
maxtruetrueintegerReturns a reference to the service that manages a specific image.
<div class="paragraph">
<p>Returns a reference to the service that manages a specific image.</p>
</div>
authorvalue@author Daniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedimageopenstack_imageidfalsefalsestringareavalueNetworkopenstack_network_providersThe operation adds a new network provider to the system.
If the `type` property is not present, a default value of `NEUTRON` will be used.
<div class="paragraph">
<p>The operation adds a new network provider to the system.
If the <code>type</code> property is not present, a default value of <code>NEUTRON</code> will be used.</p>
</div>
addprovidertruetrueopen_stack_network_providerlistprovidersfalsefalseopen_stack_network_provider[]Sets the maximum number of providers to return. If not specified all the providers are returned.
<div class="paragraph">
<p>Sets the maximum number of providers to return. If not specified all the providers are returned.</p>
</div>
maxtruetrueintegerprovideropenstack_network_provideridfalsefalsestringareavalueStorageopenstack_volume_providersAdds a new volume provider.
For example:
[source]
----
POST /ovirt-engine/api/openstackvolumeproviders
----
With a request body like this:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Adds a new volume provider.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/openstackvolumeproviders</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedaddprovidertruetrueopen_stack_volume_providerRetrieves the list of volume providers.
<div class="paragraph">
<p>Retrieves the list of volume providers.</p>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedlistprovidersfalsefalseopen_stack_volume_provider[]Sets the maximum number of providers to return. If not specified all the providers are returned.
<div class="paragraph">
<p>Sets the maximum number of providers to return. If not specified all the providers are returned.</p>
</div>
maxtruetrueintegerprovideropenstack_volume_provideridfalsefalsestringareavalueNetworkopenstack_networkslistnetworksfalsefalseopen_stack_network[]Sets the maximum number of networks to return. If not specified all the networks are returned.
<div class="paragraph">
<p>Sets the maximum number of networks to return. If not specified all the networks are returned.</p>
</div>
maxtruetrueintegernetworkopenstack_networkidfalsefalsestringareavalueStorageopenstack_volume_providerimport_certificatescertificatestruetruecertificate[]test_connectivityIndicates if the test should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the test should be performed asynchronously.</p>
</div>
asynctruetruebooleangetproviderfalsefalseopen_stack_volume_providerupdateprovidertruetrueopen_stack_volume_providerIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleancertificatesexternal_provider_certificatesvolume_typesopenstack_volume_typesauthentication_keysopenstack_volume_authentication_keysareavalueStorageopenstack_volume_typeslisttypesfalsefalseopen_stack_volume_type[]Sets the maximum number of volume types to return. If not specified all the volume types are returned.
<div class="paragraph">
<p>Sets the maximum number of volume types to return. If not specified all the volume types are returned.</p>
</div>
maxtruetrueintegertypeopenstack_volume_typeidfalsefalsestringareavalueStorageopenstack_volume_authentication_keysaddkeytruetrueopenstack_volume_authentication_keylistkeysfalsefalseopenstack_volume_authentication_key[]Sets the maximum number of keys to return. If not specified all the keys are returned.
<div class="paragraph">
<p>Sets the maximum number of keys to return. If not specified all the keys are returned.</p>
</div>
maxtruetrueintegerkeyopenstack_volume_authentication_keyidfalsefalsestringareavalueStorageopenstack_imagegetimagefalsefalseopen_stack_imageImports 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:
[source]
----
POST /ovirt-engine/api/openstackimageproviders/123/images/456/import
----
With a request body like this:
[source,xml]
----
<action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>images0</name>
</cluster>
</action>
----
<div class="paragraph">
<p>Imports a virtual machine from a Glance image storage domain.</p>
</div>
<div class="paragraph">
<p>For example, to import the image with identifier <code>456</code> from the
storage domain with identifier <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/openstackimageproviders/123/images/456/import</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<storage_domain>
<name>images0</name>
</storage_domain>
<cluster>
<name>images0</name>
</cluster>
</action></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedimportdisktruetruediskIndicates whether the image should be imported as a template.
<div class="paragraph">
<p>Indicates whether the image should be imported as a template.</p>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedimport_as_templatetruetruebooleanstorage_domaintruetruestorage_domaintemplatetruetruetemplateThis parameter is mandatory in case of using `import_as_template` and indicates which cluster should be used
for import glance image as template.
<div class="paragraph">
<p>This parameter is mandatory in case of using <code>import_as_template</code> and indicates which cluster should be used
for import glance image as template.</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddedclustertruetrueclusterIndicates if the import should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the import should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueStorageopenstack_volume_typegettypefalsefalseopen_stack_volume_typeareavalueNetworkopenstack_subnetgetsubnetfalsefalseopen_stack_subnetremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworkopenstack_subnetsaddsubnettruetrueopen_stack_subnetlistsubnetsfalsefalseopen_stack_subnet[]Sets the maximum number of sub-networks to return. If not specified all the sub-networks are returned.
<div class="paragraph">
<p>Sets the maximum number of sub-networks to return. If not specified all the sub-networks are returned.</p>
</div>
maxtruetrueintegersubnetopenstack_subnetidfalsefalsestringareavalueNetworkopenstack_network_providerimport_certificatescertificatestruetruecertificate[]test_connectivityIndicates if the test should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the test should be performed asynchronously.</p>
</div>
asynctruetruebooleangetproviderfalsefalseopen_stack_network_providerupdateprovidertruetrueopen_stack_network_providerIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleancertificatesexternal_provider_certificatesnetworksopenstack_networksareavalueVirtualizationtemplateExports a template to the data center export domain.
For example, the operation can be facilitated using the following request:
[source]
----
POST /ovirt-engine/api/templates/123/export
----
With a request body like this:
[source,xml]
----
<action>
<storage_domain id="456"/>
<exclusive>true<exclusive/>
</action>
----
<div class="paragraph">
<p>Exports a template to the data center export domain.</p>
</div>
<div class="paragraph">
<p>For example, the operation can be facilitated using the following request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/templates/123/export</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<storage_domain id="456"/>
<exclusive>true<exclusive/>
</action></code></pre>
</div>
</div>
authorvalueLiron Aravot <laravot@redhat.com>datevalue14 Sep 2016statusvalueaddedexportIndicates 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.
<div class="paragraph">
<p>Indicates if the existing templates with the same name should be overwritten.</p>
</div>
<div class="paragraph">
<p>The export action reports a failed action if a template of the same name exists in the destination domain.
Set this parameter to <code>true</code> to change this behavior and overwrite any existing template.</p>
</div>
authorvalueLiron Aravot <laravot@redhat.com>datevalue14 Sep 2016statusvalueaddedexclusivetruetruebooleanSpecifies the destination export storage domain.
<div class="paragraph">
<p>Specifies the destination export storage domain.</p>
</div>
authorvalueLiron Aravot <laravot@redhat.com>datevalue14 Sep 2016statusvalueaddedstorage_domaintruetruestorage_domaingettemplatefalsefalsetemplateIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanUpdates the template.
The `name`, `description`, `type`, `memory`, `cpu`, `topology`, `os`, `high_availability`, `display`,
`stateless`, `usb` and `timezone` elements can be updated after a template has been created.
For example, to update a template to so that it has 1 GiB of memory send a request like this:
[source]
----
PUT /ovirt-engine/api/templates/123
----
With the following request body:
[source,xml]
----
<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:
[source,xml]
----
<template>
<version>
<version_name>mytemplate_2</version_name>
</version>
</template>
----
<div class="paragraph">
<p>Updates the template.</p>
</div>
<div class="paragraph">
<p>The <code>name</code>, <code>description</code>, <code>type</code>, <code>memory</code>, <code>cpu</code>, <code>topology</code>, <code>os</code>, <code>high_availability</code>, <code>display</code>,
<code>stateless</code>, <code>usb</code> and <code>timezone</code> elements can be updated after a template has been created.</p>
</div>
<div class="paragraph">
<p>For example, to update a template to so that it has 1 GiB of memory send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/templates/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the following request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><template>
<memory>1073741824</memory>
</template></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>version_name</code> name attribute is the only one that can be updated within the <code>version</code> attribute used for
template versions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><template>
<version>
<version_name>mytemplate_2</version_name>
</version>
</template></code></pre>
</div>
</div>
authorvalueShahar Havivi <shavivi@redhat.com>datevalue14 Sep 2016statusvalueaddedupdatetemplatetruetruetemplateIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemovas a virtual machine template.
[source]
----
DELETE /ovirt-engine/api/templates/123
----
<div class="paragraph">
<p>Removas a virtual machine template.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/templates/123</code></pre>
</div>
</div>
authorvalueShahar Havivi <shavivi@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanpermissionsassigned_permissionstagsassigned_tagsgraphics_consolesgraphics_consolescdromstemplate_cdromsnicstemplate_nicswatchdogstemplate_watchdogsReference to the service that manages a specific
disk attachment of the template.
<div class="paragraph">
<p>Reference to the service that manages a specific
disk attachment of the template.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue7 Jul 2016statusvalueaddeddisk_attachmentstemplate_disk_attachmentsareavalueVirtualizationvm_watchdogsaddwatchdogtruetruewatchdoglistwatchdogsfalsefalsewatchdog[]Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.
<div class="paragraph">
<p>Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.</p>
</div>
maxtruetrueintegerwatchdogvm_watchdogidfalsefalsestringThis service represents a vm that has a specific
label when accessed through the affinitylabels/vms
subcollection.
<div class="paragraph">
<p>This service represents a vm that has a specific
label when accessed through the affinitylabels/vms
subcollection.</p>
</div>
affinity_label_vmRemove a label from a vm.
<div class="paragraph">
<p>Remove a label from a vm.</p>
</div>
removeRetrieves details about a vm that has this label assigned.
<div class="paragraph">
<p>Retrieves details about a vm that has this label assigned.</p>
</div>
getvmfalsefalsevmareavalueVirtualizationvmThis operation stops any migration of a virtual machine to another physical host.
[source]
----
POST /ovirt-engine/api/vms/123/cancelmigration
----
The cancel migration action does not take any action specific parameters,
so the request body should contain an empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>This operation stops any migration of a virtual machine to another physical host.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/cancelmigration</code></pre>
</div>
</div>
<div class="paragraph">
<p>The cancel migration action does not take any action specific parameters,
so the request body should contain an empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedcancel_migrationIndicates if the migration should cancelled asynchronously.
<div class="paragraph">
<p>Indicates if the migration should cancelled asynchronously.</p>
</div>
asynctruetruebooleancommit_snapshotIndicates if the snapshots should be committed asynchronously.
<div class="paragraph">
<p>Indicates if the snapshots should be committed asynchronously.</p>
</div>
asynctruetruebooleanclonevmtruetruevmIndicates if the clone should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the clone should be performed asynchronously.</p>
</div>
asynctruetruebooleanDetaches a virtual machine from a pool.
[source]
----
POST /ovirt-engine/api/vms/123/detach
----
The detach action does not take any action specific parameters, so the request body should contain an
empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>Detaches a virtual machine from a pool.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/detach</code></pre>
</div>
</div>
<div class="paragraph">
<p>The detach action does not take any action specific parameters, so the request body should contain an
empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddeddetachIndicates if the detach should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the detach should be performed asynchronously.</p>
</div>
asynctruetruebooleanExport a virtual machine to an export domain.
For example to export virtual machine `123` to the export domain `myexport`, send a request like this:
[source]
----
POST /ovirt-engine/api/vms/123/export
----
With a request body like this:
[source,xml]
----
<action>
<storage_domain>
<name>myexport</name>
</storage_domain>
<exclusive>true</exclusive>
<discard_snapshots>true</discard_snapshots>
</action>
----
<div class="paragraph">
<p>Export a virtual machine to an export domain.</p>
</div>
<div class="paragraph">
<p>For example to export virtual machine <code>123</code> to the export domain <code>myexport</code>, send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/export</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<storage_domain>
<name>myexport</name>
</storage_domain>
<exclusive>true</exclusive>
<discard_snapshots>true</discard_snapshots>
</action></code></pre>
</div>
</div>
authorvalueTal Nisan <tisan@redhat.com>datevalue19 Sep 2016statusvalueaddedexportThe `discard_snapshots` parameter is to be used when the virtual machine should be exported with all its
snapshots collapsed.
<div class="paragraph">
<p>The <code>discard_snapshots</code> parameter is to be used when the virtual machine should be exported with all its
snapshots collapsed.</p>
</div>
authorvalueTal Nisan <tisan@redhat.com>datevalue19 Sep 2016statusvalueaddeddiscard_snapshotstruetruebooleanThe `exclusive` parameter is to be used when the virtual machine should be exported even if another copy of
it already exists in the export domain (override).
<div class="paragraph">
<p>The <code>exclusive</code> parameter is to be used when the virtual machine should be exported even if another copy of
it already exists in the export domain (override).</p>
</div>
authorvalueTal Nisan <tisan@redhat.com>datevalue19 Sep 2016statusvalueaddedexclusivetruetruebooleanstorage_domaintruetruestorage_domainIndicates if the export should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the export should be performed asynchronously.</p>
</div>
asynctruetruebooleanFreeze virtual machine file systems.
This operation freezes a virtual machine's file systems using the QEMU guest agent when taking a live snapshot of
a running virtual machine. Normally, this is done automatically by the manager, but this must be executed
manually with the API for virtual machines using OpenStack Volume (Cinder) disks.
Example:
[source]
----
POST /ovirt-engine/api/vms/123/freezefilesystems
----
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>Freeze virtual machine file systems.</p>
</div>
<div class="paragraph">
<p>This operation freezes a virtual machine’s file systems using the QEMU guest agent when taking a live snapshot of
a running virtual machine. Normally, this is done automatically by the manager, but this must be executed
manually with the API for virtual machines using OpenStack Volume (Cinder) disks.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/freezefilesystems</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedfreeze_filesystemsIndicates if the freeze should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the freeze should be performed asynchronously.</p>
</div>
asynctruetruebooleanRetrieves the description of the virtual machine.
<div class="paragraph">
<p>Retrieves the description of the virtual machine.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue11 Oct 2016statusvalueaddedgetDescription of the virtual machine.
<div class="paragraph">
<p>Description of the virtual machine.</p>
</div>
authorvalueShmuel Melamud <smelamud@redhat.com>datevalue14 Sep 2016statusvalueaddedvmfalsefalsevmIndicates if the returned result describes the virtual machine as it is currently running, or if describes
it with the modifications that have already been performed but that will have effect only when it is
restarted. By default the values is `false`.
If the parameter is included in the request, but without a value, it is assumed that the value is `true`, so
the following request:
[source]
----
GET /vms/{vm:id};next_run
----
Is equivalent to using the value `true`:
[source]
----
GET /vms/{vm:id};next_run=true
----
<div class="paragraph">
<p>Indicates if the returned result describes the virtual machine as it is currently running, or if describes
it with the modifications that have already been performed but that will have effect only when it is
restarted. By default the values is <code>false</code>.</p>
</div>
<div class="paragraph">
<p>If the parameter is included in the request, but without a value, it is assumed that the value is <code>true</code>, so
the following request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /vms/{vm:id};next_run</code></pre>
</div>
</div>
<div class="paragraph">
<p>Is equivalent to using the value <code>true</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /vms/{vm:id};next_run=true</code></pre>
</div>
</div>
next_runtruetruebooleanIndicates if all 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' send a request like this:
....
GET /ovirt-engine/api/vms/123?all_content=true
....
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.
<div class="paragraph">
<p>Indicates if all the attributes of the virtual machine should be included in the response.</p>
</div>
<div class="paragraph">
<p>By default the following attributes are excluded:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>console</code></p>
</li>
<li>
<p><code>initialization.configuration.data</code> - The OVF document describing the virtual machine.</p>
</li>
<li>
<p><code>rng_source</code></p>
</li>
<li>
<p><code>soundcard</code></p>
</li>
<li>
<p><code>virtio_scsi</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For example, to retrieve the complete representation of the virtual machine '123' send a request like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/vms/123?all_content=true</pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue11 Oct 2016statusvalueaddedsincevalue4.0.6all_contenttruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanInitiates 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.
This is how an example request would look like:
[source]
----
POST /ovirt-engine/api/vms/123/logon
----
Request body:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>Initiates the automatic user logon to access a virtual machine from an external console.</p>
</div>
<div class="paragraph">
<p>This action requires the <code>ovirt-guest-agent-gdm-plugin</code> and the <code>ovirt-guest-agent-pam-module</code> packages to be
installed and the <code>ovirt-guest-agent</code> service to be running on the virtual machine.</p>
</div>
<div class="paragraph">
<p>Users require the appropriate user permissions for the virtual machine in order to access the virtual machine
from an external console.</p>
</div>
<div class="paragraph">
<p>This is how an example request would look like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/logon</code></pre>
</div>
</div>
<div class="paragraph">
<p>Request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueVinzenz Feenstra <vfeenstr@redhat.com>datevalue14 Sep 2016statusvalueaddedlogonIndicates if the logon should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the logon should be performed asynchronously.</p>
</div>
asynctruetruebooleanmaintenancemaintenance_enabledtruetruebooleanIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis operation migrates a virtual machine to another physical host.
[source]
----
POST /ovirt-engine/api/vms/123/migrate
----
One can specify a specific host to migrate the virtual machine to:
[source,xml]
----
<action>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>
----
<div class="paragraph">
<p>This operation migrates a virtual machine to another physical host.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/migrate</code></pre>
</div>
</div>
<div class="paragraph">
<p>One can specify a specific host to migrate the virtual machine to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedmigrateSpecifies 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.
<div class="paragraph">
<p>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.</p>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedclustertruetrueclusterSpecifies the virtual machine should migrate although it might be defined as non migratable. This is an
optional parameter. By default, it is set to `false`.
<div class="paragraph">
<p>Specifies the virtual machine should migrate although it might be defined as non migratable. This is an
optional parameter. By default, it is set to <code>false</code>.</p>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedforcetruetruebooleanSpecifies a specific host the virtual machine should migrate to. This is an optional parameters. By default,
the oVirt Engine 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.
<div class="paragraph">
<p>Specifies a specific host the virtual machine should migrate to. This is an optional parameters. By default,
the oVirt Engine 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 <code>id</code> or <code>name</code> parameter.</p>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedhosttruetruehostIndicates if the migration should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the migration should be performed asynchronously.</p>
</div>
asynctruetruebooleanpreview_snapshotdiskstruetruedisk[]restore_memorytruetruebooleansnapshottruetruesnapshotvmtruetruevmIndicates if the preview should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the preview should be performed asynchronously.</p>
</div>
asynctruetruebooleanupdatevmtruetruevmIndicates 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.
<div class="paragraph">
<p>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 <code>false</code>, so by default changes are applied
immediately.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue13 Oct 2016statusvalueaddednext_runtruetruebooleanIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis operation sends a reboot request to a virtual machine.
[source]
----
POST /ovirt-engine/api/vms/123/reboot
----
The reboot action does not take any action specific parameters, so the request body should contain an
empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>This operation sends a reboot request to a virtual machine.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/reboot</code></pre>
</div>
</div>
<div class="paragraph">
<p>The reboot action does not take any action specific parameters, so the request body should contain an
empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue14 Sep 2016statusvalueaddedrebootIndicates if the reboot should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the reboot should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves the virtual machine, including the virtual disks attached to it.
For example, to remove the virtual machine with identifier `123` send a request like this:
[source]
----
DELETE /ovirt-engine/api/vms/123
----
<div class="paragraph">
<p>Removes the virtual machine, including the virtual disks attached to it.</p>
</div>
<div class="paragraph">
<p>For example, to remove the virtual machine with identifier <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/vms/123</code></pre>
</div>
</div>
authorvalueMilan Zamazal <mzamazal@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the attached virtual disks should be detached first and preserved instead of being removed.
<div class="paragraph">
<p>Indicates if the attached virtual disks should be detached first and preserved instead of being removed.</p>
</div>
authorvalueMilan Zamazal <mzamazal@redhat.com>datevalue14 Sep 2016statusvalueaddeddetach_onlytruetruebooleanIndicates 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.
<div class="paragraph">
<p>Indicates if the virtual machine should be forcibly removed.</p>
</div>
<div class="paragraph">
<p>Locked virtual machines and virtual machines with locked disk images
cannot be removed without this flag set to true.</p>
</div>
authorvalueMilan Zamazal <mzamazal@redhat.com>datevalue14 Sep 2016statusvalueaddedforcetruetruebooleanreorder_mac_addressesIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis operation sends a shutdown request to a virtual machine.
[source]
----
POST /ovirt-engine/api/vms/123/shutdown
----
The shutdown action does not take any action specific parameters,
so the request body should contain an empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>This operation sends a shutdown request to a virtual machine.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/shutdown</code></pre>
</div>
</div>
<div class="paragraph">
<p>The shutdown action does not take any action specific parameters,
so the request body should contain an empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedshutdownIndicates if the shutdown should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the shutdown should be performed asynchronously.</p>
</div>
asynctruetruebooleanStarts 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:
[source]
----
POST /ovirt-engine/api/vms/123/start
----
With a request body:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>Starts the virtual machine.</p>
</div>
<div class="paragraph">
<p>If the virtual environment is complete and the virtual machine contains all necessary components to function,
it can be started.</p>
</div>
<div class="paragraph">
<p>This example starts the virtual machine:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/start</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedstartIf set to `true`, start the virtual machine in paused mode. Default is `false`.
<div class="paragraph">
<p>If set to <code>true</code>, start the virtual machine in paused mode. Default is <code>false</code>.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedpausetruetruebooleanThe definition of the virtual machine for this specific run.
For example:
[source,xml]
----
<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 will be
powered off, this definition will be reverted.
<div class="paragraph">
<p>The definition of the virtual machine for this specific run.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<vm>
<os>
<boot>
<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm>
</action></code></pre>
</div>
</div>
<div class="paragraph">
<p>This will set the boot device to the CDROM only for this specific start. After the virtual machine will be
powered off, this definition will be reverted.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddedvmtruetruevmIf set to `true`, the initialization type is set to _cloud-init_. The default value is `false`.
See https://cloudinit.readthedocs.io/en/latest[this] for details.
<div class="paragraph">
<p>If set to <code>true</code>, the initialization type is set to <em>cloud-init</em>. The default value is <code>false</code>.
See <a href="https://cloudinit.readthedocs.io/en/latest">this</a> for details.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddeduse_cloud_inittruetruebooleanIf set to `true`, the initialization type is set to _Sysprep_. The default value is `false`.
See https://en.wikipedia.org/wiki/Sysprep[this] for details.
<div class="paragraph">
<p>If set to <code>true</code>, the initialization type is set to <em>Sysprep</em>. The default value is <code>false</code>.
See <a href="https://en.wikipedia.org/wiki/Sysprep">this</a> for details.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue14 Sep 2016statusvalueaddeduse_syspreptruetruebooleanIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanThis operation forces a virtual machine to power-off.
[source]
----
POST /ovirt-engine/api/vms/123/stop
----
The stop action does not take any action specific parameters,
so the request body should contain an empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>This operation forces a virtual machine to power-off.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/stop</code></pre>
</div>
</div>
<div class="paragraph">
<p>The stop action does not take any action specific parameters,
so the request body should contain an empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedstopIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis 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.
[source]
----
POST /ovirt-engine/api/vms/123/suspend
----
The suspend action does not take any action specific parameters,
so the request body should contain an empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>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.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/suspend</code></pre>
</div>
</div>
<div class="paragraph">
<p>The suspend action does not take any action specific parameters,
so the request body should contain an empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedsuspendIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanThaw virtual machine file systems.
This operation thaws a virtual machine's file systems using the QEMU guest agent when taking a live snapshot of a
running virtual machine. Normally, this is done automatically by the manager, but this must be executed manually
with the API for virtual machines using OpenStack Volume (Cinder) disks.
Example:
[source]
----
POST /api/vms/123/thawfilesystems
----
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>Thaw virtual machine file systems.</p>
</div>
<div class="paragraph">
<p>This operation thaws a virtual machine’s file systems using the QEMU guest agent when taking a live snapshot of a
running virtual machine. Normally, this is done automatically by the manager, but this must be executed manually
with the API for virtual machines using OpenStack Volume (Cinder) disks.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /api/vms/123/thawfilesystems</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedthaw_filesystemsIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanGenerates a time-sensitive authentication token for accessing a virtual machine's display.
[source]
----
POST /ovirt-engine/api/vms/123/ticket
----
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.
[source,xml]
----
<action>
<ticket>
<value>abcd12345</value>
<expiry>120</expiry>
</ticket>
</action>
----
<div class="paragraph">
<p>Generates a time-sensitive authentication token for accessing a virtual machine’s display.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/ticket</code></pre>
</div>
</div>
<div class="paragraph">
<p>The client-provided action optionally includes a desired ticket value and/or an expiry time in seconds.</p>
</div>
<div class="paragraph">
<p>In any case, the response specifies the actual ticket value and expiry used.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<ticket>
<value>abcd12345</value>
<expiry>120</expiry>
</ticket>
</action></code></pre>
</div>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue14 Sep 2016statusvalueaddedtickettickettruetrueticketIndicates if the generation of the ticket should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the generation of the ticket should be performed asynchronously.</p>
</div>
asynctruetruebooleanundo_snapshotIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanstatisticsstatisticspermissionsassigned_permissionstagsassigned_tagsgraphics_consolesgraphics_consoleskatello_erratakatello_erratasnapshotssnapshotsapplicationsvm_applicationscdromsvm_cdromshost_devicesvm_host_devicesnicsvm_nicsnuma_nodesvm_numa_nodesreported_devicesvm_reported_devicesReference to the service that provides information about virtual machine user sessions.
<div class="paragraph">
<p>Reference to the service that provides information about virtual machine user sessions.</p>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedsessionsvm_sessionswatchdogsvm_watchdogsList of disks attached to this virtual machine.
<div class="paragraph">
<p>List of disks attached to this virtual machine.</p>
</div>
disk_attachmentsdisk_attachmentsList of scheduling labels assigned to this VM.
<div class="paragraph">
<p>List of scheduling labels assigned to this VM.</p>
</div>
affinity_labelsassigned_affinity_labelsareavalueStoragestorage_domain_vmgetvmfalsefalsevmImports a virtual machine from an export storage domain.
For example, send a request like this:
[source]
----
POST /ovirt-engine/api/storagedomains/123/vms/456/import
----
With a request body like this:
[source,xml]
----
<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:
[source,xml]
----
<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:
[source,xml]
----
<action>
<cluster>
<name>mycluster</name>
</cluster>
<vm>
<name>myvm</name>
</vm>
<disks>
<disk id="123"/>
<disk id="456"/>
</disks>
</action>
----
<div class="paragraph">
<p>Imports a virtual machine from an export storage domain.</p>
</div>
<div class="paragraph">
<p>For example, send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/storagedomains/123/vms/456/import</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<storage_domain>
<name>mydata</name>
</storage_domain>
<cluster>
<name>mycluster</name>
</cluster>
</action></code></pre>
</div>
</div>
<div class="paragraph">
<p>To import a virtual machine as a new entity add the <code>clone</code> parameter:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<storage_domain>
<name>mydata</name>
</storage_domain>
<cluster>
<name>mycluster</name>
</cluster>
<clone>true</clone>
<vm>
<name>myvm</name>
</vm>
</action></code></pre>
</div>
</div>
<div class="paragraph">
<p>Include an optional <code>disks</code> parameter to choose which disks to import. For example, to import the disks
of the template that have the identifiers <code>123</code> and <code>456</code> send the following request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<cluster>
<name>mycluster</name>
</cluster>
<vm>
<name>myvm</name>
</vm>
<disks>
<disk id="123"/>
<disk id="456"/>
</disks>
</action></code></pre>
</div>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue14 Sep 2016statusvalueaddedimportIndicates 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`.
<div class="paragraph">
<p>Indicates if the identifiers of the imported virtual machine
should be regenerated.</p>
</div>
<div class="paragraph">
<p>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 <code>true</code>, as the default is <code>false</code>.</p>
</div>
clonetruetruebooleanclustertruetrueclusterstorage_domaintruetruestorage_domainvmtruetruevmIndicates 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`.
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>This parameter is optional, and if it isn’t explicitly specified the
default value is <code>false</code>.</p>
</div>
collapse_snapshotstruetruebooleanIndicates if the import should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the import should be performed asynchronously.</p>
</div>
asynctruetruebooleanregisterclonetruetruebooleanclustertruetrueclustervmtruetruevmIndicates if the registration should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the registration should be performed asynchronously.</p>
</div>
asynctruetruebooleanDeletes 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:
[source]
----
DELETE /ovirt-engine/api/storagedomains/123/vms/456
----
<div class="paragraph">
<p>Deletes a virtual machine from an export storage domain.</p>
</div>
<div class="paragraph">
<p>For example, to delete the virtual machine <code>456</code> from the storage domain <code>123</code>, send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/storagedomains/123/vms/456</code></pre>
</div>
</div>
authorvalueLiron Aravot <laravot@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleandisksstorage_domain_content_disksReturns a reference to the service that manages the disk attachments of the virtual machine.
<div class="paragraph">
<p>Returns a reference to the service that manages the disk attachments of the virtual machine.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue6 Sep 2016statusvalueaddedsincevalue4.0.4disk_attachmentsstorage_domain_vm_disk_attachmentsareavalueVirtualizationclustergetclusterfalsefalseclusterIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanUpdates information about the cluster.
Only specified fields are updated, others remain unchanged.
E.g. update cluster's CPU:
[source]
----
PUT /ovirt-engine/api/clusters/123
----
With request body like:
[source,xml]
----
<cluster>
<cpu>
<type>Intel Haswell-noTSX Family</type>
</cpu>
</cluster>
----
<div class="paragraph">
<p>Updates information about the cluster.</p>
</div>
<div class="paragraph">
<p>Only specified fields are updated, others remain unchanged.</p>
</div>
<div class="paragraph">
<p>E.g. update cluster’s CPU:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/clusters/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With request body like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cluster>
<cpu>
<type>Intel Haswell-noTSX Family</type>
</cpu>
</cluster></code></pre>
</div>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedupdateclustertruetrueclusterIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves cluster from the system.
[source]
----
DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000
----
<div class="paragraph">
<p>Removes cluster from the system.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/clusters/00000000-0000-0000-0000-000000000000</code></pre>
</div>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanreset_emulated_machineIndicates if the reset should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the reset should be performed asynchronously.</p>
</div>
asynctruetruebooleanaffinity_groupsaffinity_groupscpu_profilesassigned_cpu_profilesnetworksassigned_networkspermissionsassigned_permissionsgluster_hooksgluster_hooksgluster_volumesgluster_volumesA sub collection with all the supported network filters for this cluster.
<div class="paragraph">
<p>A sub collection with all the supported network filters for this cluster.</p>
</div>
network_filtersnetwork_filtersareavalueStoragesnapshot_diskslistdisksfalsefalsedisk[]Sets the maximum number of disks to return. If not specified all the disks are returned.
<div class="paragraph">
<p>Sets the maximum number of disks to return. If not specified all the disks are returned.</p>
</div>
maxtruetrueintegerdisksnapshot_diskidfalsefalsestringareavalueVirtualizationvm_poolThis operation allocates a virtual machine in the virtual machine pool.
[source]
----
POST /ovirt-engine/api/vmpools/123/allocatevm
----
The allocate virtual machine action does not take any action specific parameters, so the request body should
contain an empty `action`:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>This operation allocates a virtual machine in the virtual machine pool.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vmpools/123/allocatevm</code></pre>
</div>
</div>
<div class="paragraph">
<p>The allocate virtual machine action does not take any action specific parameters, so the request body should
contain an empty <code>action</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedallocate_vmIndicates if the allocation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the allocation should be performed asynchronously.</p>
</div>
asynctruetruebooleangetpoolfalsefalsevm_poolIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanUpdate the virtual machine pool.
[source]
----
PUT /ovirt-engine/api/vmpools/123
----
The `name`, `description`, `size`, `prestarted_vms` and `max_user_vms`
attributes can be updated after the virtual machine pool has been
created.
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Update the virtual machine pool.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vmpools/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>name</code>, <code>description</code>, <code>size</code>, <code>prestarted_vms</code> and <code>max_user_vms</code>
attributes can be updated after the virtual machine pool has been
created.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueShmuel Melamud <smelamud@redhat.com>datevalue14 Sep 2016statusvalueaddedupdateThe virtual machine pool that is being updated.
<div class="paragraph">
<p>The virtual machine pool that is being updated.</p>
</div>
authorvalueShmuel Melamud <smelamud@redhat.com>datevalue14 Sep 2016statusvalueaddedpooltruetruevm_poolIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves a virtual machine pool.
[source]
----
DELETE /ovirt-engine/api/vmpools/123
----
<div class="paragraph">
<p>Removes a virtual machine pool.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/vmpools/123</code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanpermissionsassigned_permissionsareavalueSLAquotasCreates a new quota.
An example of creating a new quota:
[source]
----
POST /ovirt-engine/api/datacenters/123/quotas
----
[source,xml]
----
<quota>
<name>myquota</name>
<description>My new quota for virtual machines</description>
</quota>
----
<div class="paragraph">
<p>Creates a new quota.</p>
</div>
<div class="paragraph">
<p>An example of creating a new quota:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/datacenters/123/quotas</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><quota>
<name>myquota</name>
<description>My new quota for virtual machines</description>
</quota></code></pre>
</div>
</div>
authorvalueRoman Mohr <rmohr@redhat.com>datevalue14 Sep 2016statusvalueaddedaddquotatruetruequotaLists quotas of a data center
<div class="paragraph">
<p>Lists quotas of a data center</p>
</div>
authorvalueRoman Mohr <rmohr@redhat.com>datevalue14 Sep 2016statusvalueaddedlistquotasfalsefalsequota[]Sets the maximum number of quota descriptors to return. If not specified all the descriptors are returned.
<div class="paragraph">
<p>Sets the maximum number of quota descriptors to return. If not specified all the descriptors are returned.</p>
</div>
maxtruetrueintegerquotaquotaidfalsefalsestringProvides information about a specific cluster level. See the <<services/cluster_levels,ClusterLevels>> service for
more information.
<div class="paragraph">
<p>Provides information about a specific cluster level. See the <a href="#services/cluster_levels">ClusterLevels</a> service for
more information.</p>
</div>
cluster_levelProvides the information about the capabilities of the specific cluster level managed by this service.
<div class="paragraph">
<p>Provides the information about the capabilities of the specific cluster level managed by this service.</p>
</div>
getlevelfalsefalsecluster_levelareavalueStoragestorage_domain_content_diskgetdiskfalsefalsediskIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanareavalueVirtualizationvm_applicationslistapplicationsfalsefalseapplication[]Sets the maximum number of applications to return. If not specified all the applications are returned.
<div class="paragraph">
<p>Sets the maximum number of applications to return. If not specified all the applications are returned.</p>
</div>
maxtruetrueintegerIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanapplicationvm_applicationidfalsefalsestringProvides a way for clients to list available files.
This services is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks
(VFDs) that an administrator uploads.
The addition of a CDROM device to a virtual machine requires an ISO image from the files of an ISO storage domain.
<div class="paragraph">
<p>Provides a way for clients to list available files.</p>
</div>
<div class="paragraph">
<p>This services is specifically targeted to ISO storage domains, which contain ISO images and virtual floppy disks
(VFDs) that an administrator uploads.</p>
</div>
<div class="paragraph">
<p>The addition of a CDROM device to a virtual machine requires an ISO image from the files of an ISO storage domain.</p>
</div>
areavalueVirtualizationauthorvalueMaor Lipchuk <mlipchuk@redhat.com>datevalue14 Sep 2016statusvalueaddedfileslistfilefalsefalsefile[]Sets the maximum number of files to return. If not specified all the files are returned.
<div class="paragraph">
<p>Sets the maximum number of files to return. If not specified all the files are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned files.
<div class="paragraph">
<p>A query string used to restrict the returned files.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanfilefileidfalsefalsestringThis service manages a single virtual machine to affinity group assignment.
<div class="paragraph">
<p>This service manages a single virtual machine to affinity group assignment.</p>
</div>
areavalueSLAauthorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedaffinity_group_vmRemove this virtual machine from the affinity group.
<div class="paragraph">
<p>Remove this virtual machine from the affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanManages a CDROM device of a virtual machine.
If there is a disk inserted then the `file` attribute will contain a reference to the ISO image:
[source,xml]
----
<cdrom>
<file id="mycd.iso"/>
</cdrom>
----
If there is no disk inserted then the `file` attribute won't be reported:
[source,xml]
----
<cdrom>
</cdrom>
----
Changing and ejecting the disk is done using always the `update` method, to change the value of the `file` attribute.
For example, to insert or change the disk send a request like this:
[source]
----
PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000
----
The body should contain the new value for the `file` attribute:
[source,xml]
----
<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`:
[source,xml]
----
<cdrom>
<file id=""/>
</cdrom>
----
By default the above operations change permanently the disk that will be visible to the virtual machine after the
next boot, but they don't have any effect on the currently running virtual machine. If you want to change the disk
that is visible to the current running virtual machine, add the `current=true` parameter. For example, to eject the
current disk send a request like this:
[source]
----
PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000?current=true
----
With a request body like this:
[source,xml]
----
<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.
<div class="paragraph">
<p>Manages a CDROM device of a virtual machine.</p>
</div>
<div class="paragraph">
<p>If there is a disk inserted then the <code>file</code> attribute will contain a reference to the ISO image:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cdrom>
<file id="mycd.iso"/>
</cdrom></code></pre>
</div>
</div>
<div class="paragraph">
<p>If there is no disk inserted then the <code>file</code> attribute won’t be reported:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cdrom>
</cdrom></code></pre>
</div>
</div>
<div class="paragraph">
<p>Changing and ejecting the disk is done using always the <code>update</code> method, to change the value of the <code>file</code> attribute.
For example, to insert or change the disk send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000</code></pre>
</div>
</div>
<div class="paragraph">
<p>The body should contain the new value for the <code>file</code> attribute:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cdrom>
<file id="mycd.iso"/>
</cdrom></code></pre>
</div>
</div>
<div class="paragraph">
<p>The value of the <code>id</code> attribute, <code>mycd.iso</code> in this example, should correspond to a file available in an attached
ISO storage domain.</p>
</div>
<div class="paragraph">
<p>To eject the disk use a <code>file</code> with an empty <code>id</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cdrom>
<file id=""/>
</cdrom></code></pre>
</div>
</div>
<div class="paragraph">
<p>By default the above operations change permanently the disk that will be visible to the virtual machine after the
next boot, but they don’t have any effect on the currently running virtual machine. If you want to change the disk
that is visible to the current running virtual machine, add the <code>current=true</code> parameter. For example, to eject the
current disk send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123/cdroms/00000000-0000-0000-0000-000000000000?current=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cdrom>
<file id=""/>
</cdrom></code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The changes made with the <code>current=true</code> parameter are never persisted, so they won’t have any effect
after the virtual machine is rebooted.
</td>
</tr>
</table>
</div>
areavalueVirtualizationauthorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedvm_cdromReturns the information about this CDROM device.
<div class="paragraph">
<p>Returns the information about this CDROM device.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedgetThe information about the CDROM device.
<div class="paragraph">
<p>The information about the CDROM device.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedcdromfalsefalsecdromIndicates if the operation should return the information for the currently running virtual machine. This
parameter is optional, and the default value is `false`.
<div class="paragraph">
<p>Indicates if the operation should return the information for the currently running virtual machine. This
parameter is optional, and the default value is <code>false</code>.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedcurrenttruetruebooleanUpdates the information about this CDROM device.
<div class="paragraph">
<p>Updates the information about this CDROM device.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedupdateThe information about the CDROM device.
<div class="paragraph">
<p>The information about the CDROM device.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedcdromtruetruecdromIndicates if the update should apply to the currently running virtual machine, or to the virtual machine
after the next boot. This parameter is optional, and the default value is `false`, which means that by
default the update will have effect only after the next boot.
<div class="paragraph">
<p>Indicates if the update should apply to the currently running virtual machine, or to the virtual machine
after the next boot. This parameter is optional, and the default value is <code>false</code>, which means that by
default the update will have effect only after the next boot.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedcurrenttruetruebooleanareavalueSLAquota_cluster_limitgetlimitfalsefalsequota_cluster_limitremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis service manages the attachment of a disk to a virtual machine.
<div class="paragraph">
<p>This service manages the attachment of a disk to a virtual machine.</p>
</div>
disk_attachmentReturns the details of the attachment, including the bootable flag and link to the disk.
<div class="paragraph">
<p>Returns the details of the attachment, including the bootable flag and link to the disk.</p>
</div>
getattachmentfalsefalsedisk_attachmentRemoves 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`.
<div class="paragraph">
<p>Removes the disk attachment. This will only detach the disk from the virtual machine, but won’t remove it from
the system, unless the <code>detach_only</code> parameter is <code>false</code>.</p>
</div>
removeIndicates 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.
<div class="paragraph">
<p>Indicates if the disk should only be detached from the virtual machine, but not removed from the system.
The default value is <code>true</code>, which won’t remove the disk from the system.</p>
</div>
detach_onlytruetruebooleanUpdate the disk attachment and the disk properties within it.
[source]
----
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>
----
<div class="paragraph">
<p>Update the disk attachment and the disk properties within it.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>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></code></pre>
</div>
</div>
updatedisk_attachmenttruetruedisk_attachmentareavalueInfrastructurebookmarkgetbookmarkfalsefalsebookmarkupdatebookmarktruetruebookmarkIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworkinstance_type_nicgetnicfalsefalsenicupdatenictruetruenicIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueStorageassigned_disk_profilegetdisk_profilefalsefalsedisk_profileremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworknetwork_labelsAttaches 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:
[source]
----
POST /ovirt-engine/api/networks/123/labels
----
With a request body like this:
[source,xml]
----
<label id="mylabel"/>
----
<div class="paragraph">
<p>Attaches label to logical network.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>For example, to attach the label <code>mylabel</code> to a logical network having id <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/networks/123/labels</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><label id="mylabel"/></code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedaddlabeltruetruenetwork_labellistlabelsfalsefalsenetwork_label[]Sets the maximum number of labels to return. If not specified all the labels are returned.
<div class="paragraph">
<p>Sets the maximum number of labels to return. If not specified all the labels are returned.</p>
</div>
maxtruetrueintegerlabelnetwork_labelidfalsefalsestringareavalueStoragestorage_domaingetstorage_domainfalsefalsestorage_domainIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanis_attachedhosttruetruehostis_attachedfalsefalsebooleanIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanUpdates a storage domain.
Not all of the <<types/storage_domain,StorageDomain>>'s attributes are updatable post-creation. Those that can be
updated are: `name`, `description`, `comment`, `warning_low_space_indicator`, `critical_space_action_blocker` and
`wipe_after_delete` (note that changing the `wipe_after_delete` attribute will not change the wipe after delete
property of disks that already exist).
To update the `name` and `wipe_after_delete` attributes of a storage domain with an identifier `123`, send a
request as follows:
[source]
----
PUT /ovirt-engine/api/storagedomains/123
----
With a request body as follows:
[source,xml]
----
<storage_domain>
<name>data2</name>
<wipe_after_delete>true</wipe_after_delete>
</storage_domain>
----
<div class="paragraph">
<p>Updates a storage domain.</p>
</div>
<div class="paragraph">
<p>Not all of the <a href="#types/storage_domain">StorageDomain</a>'s attributes are updatable post-creation. Those that can be
updated are: <code>name</code>, <code>description</code>, <code>comment</code>, <code>warning_low_space_indicator</code>, <code>critical_space_action_blocker</code> and
<code>wipe_after_delete</code> (note that changing the <code>wipe_after_delete</code> attribute will not change the wipe after delete
property of disks that already exist).</p>
</div>
<div class="paragraph">
<p>To update the <code>name</code> and <code>wipe_after_delete</code> attributes of a storage domain with an identifier <code>123</code>, send a
request as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/storagedomains/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_domain>
<name>data2</name>
<wipe_after_delete>true</wipe_after_delete>
</storage_domain></code></pre>
</div>
</div>
authorvalueIdan Shaby <ishaby@redhat.com>datevalue14 Sep 2016statusvalueaddedupdatestorage_domaintruetruestorage_domainIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis operation forces the update of the `OVF_STORE`
of this storage domain.
The `OVF_STORE` is a disk image that contains the meta-data
of virtual machines and disks that reside in the
storage domain. This meta-data is used in case the
domain is imported or exported to or from a different
data center or a different installation.
By default the `OVF_STORE` is updated periodically
(set by default to 60 minutes) but users might want to force an
update after an important change, or when the they believe the
`OVF_STORE` is corrupt.
When initiated by the user, `OVF_STORE` update will be performed whether
an update is needed or not.
<div class="paragraph">
<p>This operation forces the update of the <code>OVF_STORE</code>
of this storage domain.</p>
</div>
<div class="paragraph">
<p>The <code>OVF_STORE</code> is a disk image that contains the meta-data
of virtual machines and disks that reside in the
storage domain. This meta-data is used in case the
domain is imported or exported to or from a different
data center or a different installation.</p>
</div>
<div class="paragraph">
<p>By default the <code>OVF_STORE</code> 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
<code>OVF_STORE</code> is corrupt.</p>
</div>
<div class="paragraph">
<p>When initiated by the user, <code>OVF_STORE</code> update will be performed whether
an update is needed or not.</p>
</div>
update_ovf_storeIndicates if the `OVF_STORE` update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the <code>OVF_STORE</code> update should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis 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:
[source]
----
POST /ovirt-engine/api/storagedomains/262b056b-aede-40f1-9666-b883eff59d40/refreshluns
----
With a request body like this:
[source,xml]
----
<action>
<logical_units>
<logical_unit id="1IET_00010001"/>
<logical_unit id="1IET_00010002"/>
</logical_units>
</action>
----
<div class="paragraph">
<p>This operation refreshes the LUN size.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>For example, in order to refresh the size of two LUNs send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/storagedomains/262b056b-aede-40f1-9666-b883eff59d40/refreshluns</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"> <action>
<logical_units>
<logical_unit id="1IET_00010001"/>
<logical_unit id="1IET_00010002"/>
</logical_units>
</action></code></pre>
</div>
</div>
authorvalueFred Rolland <frolland@redhat.com>datevalue13 Sep 2016statusvalueaddedrefresh_lunsThe LUNs that need to be refreshed.
<div class="paragraph">
<p>The LUNs that need to be refreshed.</p>
</div>
authorvalueFred Rolland <frolland@redhat.com>datevalue13 Sep 2016statusvalueaddedlogical_unitstruetruelogical_unit[]Indicates if the refresh should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the refresh should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves the storage domain.
Without any special parameters, the storage domain is detached from the system and removed from the database. The
storage domain can then be imported to the same or different setup, with all the data on it. If the storage isn't
accessible the operation will fail.
If the `destroy` parameter is `true` then the operation will always succeed, even if the storage isn't
accessible, the failure is just ignored and the storage domain is removed from the database anyway.
If the `format` parameter is `true` then the actual storage is formatted, and the metadata is removed from the
LUN or directory, so it can no longer be imported to the same or a different setup.
<div class="paragraph">
<p>Removes the storage domain.</p>
</div>
<div class="paragraph">
<p>Without any special parameters, the storage domain is detached from the system and removed from the database. The
storage domain can then be imported to the same or different setup, with all the data on it. If the storage isn’t
accessible the operation will fail.</p>
</div>
<div class="paragraph">
<p>If the <code>destroy</code> parameter is <code>true</code> then the operation will always succeed, even if the storage isn’t
accessible, the failure is just ignored and the storage domain is removed from the database anyway.</p>
</div>
<div class="paragraph">
<p>If the <code>format</code> parameter is <code>true</code> then the actual storage is formatted, and the metadata is removed from the
LUN or directory, so it can no longer be imported to the same or a different setup.</p>
</div>
removeIndicates what host should be used to remove the storage domain.
This parameter is mandatory, and it can contain the name or the identifier of the host. For example, to use
the host named `myhost` to remove the storage domain with identifier `123` send a request like this:
[source]
----
DELETE /ovirt-engine/api/storagedomains/123?host=myhost
----
<div class="paragraph">
<p>Indicates what host should be used to remove the storage domain.</p>
</div>
<div class="paragraph">
<p>This parameter is mandatory, and it can contain the name or the identifier of the host. For example, to use
the host named <code>myhost</code> to remove the storage domain with identifier <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/storagedomains/123?host=myhost</code></pre>
</div>
</div>
hosttruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the actual storage should be formatted, removing all the metadata from the underlying LUN or
directory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/storagedomains/123?format=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>This parameter is optional, and the default value is <code>false</code>.</p>
</div>
authorvalueAllon Mureinik <amureini@redhat.com>datevalue14 Sep 2016statusvalueaddedformattruetruebooleanIndicates if the operation should succeed, and the storage domain removed from the database, even if the
storage isn't accessible.
[source]
----
DELETE /ovirt-engine/api/storagedomains/123?destroy=true
----
This parameter is optional, and the default value is `false`.
<div class="paragraph">
<p>Indicates if the operation should succeed, and the storage domain removed from the database, even if the
storage isn’t accessible.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/storagedomains/123?destroy=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>This parameter is optional, and the default value is <code>false</code>.</p>
</div>
authorvalueAllon Mureinik <amureini@redhat.com>datevalue14 Sep 2016statusvalueaddeddestroytruetruebooleanIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleandisk_profilesassigned_disk_profilespermissionsassigned_permissionsdisk_snapshotsdisk_snapshotsdisksdisksReturns a reference to the service that manages the files available in the storage domain.
<div class="paragraph">
<p>Returns a reference to the service that manages the files available in the storage domain.</p>
</div>
authorvalueMaor Lipchuk <mlipchuk@redhat.com>datevalue14 Sep 2016statusvalueaddedfilesfilesimagesimagesReturns a reference to the service that manages the storage connections.
<div class="paragraph">
<p>Returns a reference to the service that manages the storage connections.</p>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedstorage_connectionsstorage_domain_server_connectionstemplatesstorage_domain_templatesvmsstorage_domain_vmsareavalueVirtualizationdata_centersCreates 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:
[source]
----
POST /ovirt-engine/api/datacenters
----
With a request body like this:
[source,xml]
----
<data_center>
<name>mydc</name>
<local>false</local>
</data_center>
----
<div class="paragraph">
<p>Creates a new data center.</p>
</div>
<div class="paragraph">
<p>Creation of a new data center requires the <code>name</code> and <code>local</code> elements. For example, to create a data center
named <code>mydc</code> that uses shared storage (NFS, iSCSI or fibre channel) send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/datacenters</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><data_center>
<name>mydc</name>
<local>false</local>
</data_center></code></pre>
</div>
</div>
authorvalueShmuel Melamud <smelamud@redhat.com>datevalue14 Sep 2016statusvalueaddedaddThe data center that is being added.
<div class="paragraph">
<p>The data center that is being added.</p>
</div>
authorvalueShmuel Melamud <smelamud@redhat.com>datevalue14 Sep 2016statusvalueaddeddata_centertruetruedata_centerLists the data centers.
The following request retrieves a representation of the data centers:
[source]
----
GET /ovirt-engine/api/datacenters
----
The above request performed with `curl`:
[source,bash]
----
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:
[source,xml]
----
<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.
<div class="paragraph">
<p>Lists the data centers.</p>
</div>
<div class="paragraph">
<p>The following request retrieves a representation of the data centers:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/datacenters</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above request performed with <code>curl</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">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</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is what an example response could look like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note the <code>id</code> code of your <code>Default</code> data center. This code identifies this data center in relation to other
resources of your virtual environment.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
authorvalueVinzenz Feenstra <vfeenstr@redhat.com>datevalue14 Sep 2016statusvalueaddedlistdata_centersfalsefalsedata_center[]Sets the maximum number of data centers to return. If not specified all the data centers are returned.
<div class="paragraph">
<p>Sets the maximum number of data centers to return. If not specified all the data centers are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned data centers.
<div class="paragraph">
<p>A query string used to restrict the returned data centers.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleandata_centerdata_centeridfalsefalsestringareavalueVirtualizationvm_applicationgetapplicationfalsefalseapplicationIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanareavalueSLAquota_storage_limitsaddlimittruetruequota_storage_limitlistlimitsfalsefalsequota_storage_limit[]Sets the maximum number of limits to return. If not specified all the limits are returned.
<div class="paragraph">
<p>Sets the maximum number of limits to return. If not specified all the limits are returned.</p>
</div>
maxtruetrueintegerlimitquota_storage_limitidfalsefalsestringareavalueNetworktemplate_nicgetnicfalsefalsenicupdatenictruetruenicIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanManages 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
<<services/vm_cdrom/methods/update, update>> method of the <<services/vm_cdrom, service>> that manages the
CDROM device.
<div class="paragraph">
<p>Manages the CDROM devices of a virtual machine.</p>
</div>
<div class="paragraph">
<p>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 <code>add</code> or <code>remove</code> methods. Changing and ejecting CDROM disks is done with the
<a href="#services/vm_cdrom/methods/update">update</a> method of the <a href="#services/vm_cdrom">service</a> that manages the
CDROM device.</p>
</div>
areavalueVirtualizationauthorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedvm_cdromsReturns the list of CDROM devices of the virtual machine.
<div class="paragraph">
<p>Returns the list of CDROM devices of the virtual machine.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedlistThe list of CDROM devices of the virtual machine.
<div class="paragraph">
<p>The list of CDROM devices of the virtual machine.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedcdromsfalsefalsecdrom[]Sets the maximum number of CDROMs to return. If not specified all the CDROMs are returned.
<div class="paragraph">
<p>Sets the maximum number of CDROMs to return. If not specified all the CDROMs are returned.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedmaxtruetrueintegerReturns a reference to the service that manages a specific CDROM device.
<div class="paragraph">
<p>Returns a reference to the service that manages a specific CDROM device.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue25 Aug 2016statusvalueaddedcdromvm_cdromidfalsefalsestringProvides information about virtual machine user sessions.
<div class="paragraph">
<p>Provides information about virtual machine user sessions.</p>
</div>
areavalueVirtualizationauthorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedvm_sessionsLists all user sessions for this virtual machine.
For example, to retrieve the session information for virtual machine `123` send a request like this:
[source]
----
GET /ovirt-engine/api/vms/123/sessions
----
The response body will contain something like this:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Lists all user sessions for this virtual machine.</p>
</div>
<div class="paragraph">
<p>For example, to retrieve the session information for virtual machine <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/vms/123/sessions</code></pre>
</div>
</div>
<div class="paragraph">
<p>The response body will contain something like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedlistsessionsfalsefalsesession[]Sets the maximum number of sessions to return. If not specified all the sessions are returned.
<div class="paragraph">
<p>Sets the maximum number of sessions to return. If not specified all the sessions are returned.</p>
</div>
maxtruetrueintegerReference to the service that manages a specific session.
<div class="paragraph">
<p>Reference to the service that manages a specific session.</p>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>datevalue14 Sep 2016statusvalueaddedsessionvm_sessionidfalsefalsestringareavalueStoragevm_diskactivateIndicates if the activation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the activation should be performed asynchronously.</p>
</div>
asynctruetruebooleandeactivateIndicates if the deactivation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the deactivation should be performed asynchronously.</p>
</div>
asynctruetruebooleanexportIndicates if the export should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the export should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleangetdiskfalsefalsediskmoveIndicates if the move should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the move should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanupdatedisktruetruediskIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanDetach 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 <<services/disk/methods/remove,remove
method of the top level disk service>>.
<div class="paragraph">
<p>Detach the disk from the virtual machine.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
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 <a href="#services/disk/methods/remove">remove
method of the top level disk service</a>.
</td>
</tr>
</table>
</div>
removeIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanstatisticsstatisticspermissionsassigned_permissionsareavalueStoragestorage_server_connectiongetconectionfalsefalsestorage_connectionUpdates the storage connection.
For example, to change the address of the storage server send a request like this:
[source,xml]
----
PUT /ovirt-engine/api/storageconnections/123
----
With a request body like this:
[source,xml]
----
<storage_connection>
<address>mynewnfs.example.com</address>
<host>
<name>myhost</name>
</host>
</storage_connection>
----
<div class="paragraph">
<p>Updates the storage connection.</p>
</div>
<div class="paragraph">
<p>For example, to change the address of the storage server send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml">PUT /ovirt-engine/api/storageconnections/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_connection>
<address>mynewnfs.example.com</address>
<host>
<name>myhost</name>
</host>
</storage_connection></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedupdateconnectiontruetruestorage_connectionIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates 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`.
<div class="paragraph">
<p>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).</p>
</div>
<div class="paragraph">
<p>This parameter is optional, and the default value is <code>false</code>.</p>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue21 Sep 2016statusvalueaddedsincevalue4.0.6forcetruetruebooleanRemoves 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.
<div class="paragraph">
<p>Removes a storage connection.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveThe 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:
[source]
----
DELETE /ovirt-engine/api/storageconnections/123?host=456
----
<div class="paragraph">
<p>The name or identifier of the host from which the connection would be unmounted (disconnected). If not
provided, no host will be disconnected.</p>
</div>
<div class="paragraph">
<p>For example, to use the host with identifier <code>456</code> to delete the storage connection with identifier <code>123</code>
send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/storageconnections/123?host=456</code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedhosttruetruestringIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueInfrastructurehostActivate the host for use, such as running virtual machines.
<div class="paragraph">
<p>Activate the host for use, such as running virtual machines.</p>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddedactivateIndicates if the activation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the activation should be performed asynchronously.</p>
</div>
asynctruetruebooleanApprove 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.
<div class="paragraph">
<p>Approve a pre-installed Hypervisor host for usage in the virtualization environment.</p>
</div>
<div class="paragraph">
<p>This action also accepts an optional cluster element to define the target cluster for this host.</p>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddedapproveclustertruetrueclusterIndicates if the approval should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the approval should be performed asynchronously.</p>
</div>
asynctruetruebooleanMarks the network configuration as good and persists it inside the host.
An API user commits the network configuration to persist a host network interface attachment or detachment, or
persist the creation and deletion of a bonded interface.
IMPORTANT: Networking configuration is only committed after the engine has established that host connectivity is
not lost as a result of the configuration changes. If host connectivity is lost, the host requires a reboot and
automatically reverts to the previous networking configuration.
For example, to commit the network configuration of host with id `123` send a request like this:
[source]
----
POST /ovirt-engine/api/hosts/123/commitnetconfig
----
With a request body like this:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>Marks the network configuration as good and persists it inside the host.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Networking configuration is only committed after the engine has established that host connectivity is
not lost as a result of the configuration changes. If host connectivity is lost, the host requires a reboot and
automatically reverts to the previous networking configuration.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For example, to commit the network configuration of host with id <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/hosts/123/commitnetconfig</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>Martin Mucha <mmucha@redhat.com>datevalue16 Aug 2016statusvalueaddedcommit_net_configIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanDeactivate the host to perform maintenance tasks.
<div class="paragraph">
<p>Deactivate the host to perform maintenance tasks.</p>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddeddeactivatereasontruetruestringIndicates if the deactivation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the deactivation should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates 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`.
<div class="paragraph">
<p>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 <code>false</code>.</p>
</div>
stop_gluster_servicetruetruebooleanEnroll certificate of the host. Useful in case you get a warning that it is about to, or already expired.
<div class="paragraph">
<p>Enroll certificate of the host. Useful in case you get a warning that it is about to, or already expired.</p>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddedenroll_certificateIndicates if the enrollment should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the enrollment should be performed asynchronously.</p>
</div>
asynctruetruebooleanControls host's power management device.
For example, let's assume you want to start the host. This can be done via:
[source]
----
#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
<fence_type>start</fence_type>
</action>
' \
"${url}/hosts/123/fence"
----
<div class="paragraph">
<p>Controls host’s power management device.</p>
</div>
<div class="paragraph">
<p>For example, let’s assume you want to start the host. This can be done via:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
<fence_type>start</fence_type>
</action>
' \
"${url}/hosts/123/fence"</code></pre>
</div>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddedfencefence_typetruetruestringpower_managementfalsefalsepower_managementIndicates if the fencing should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the fencing should be performed asynchronously.</p>
</div>
asynctruetruebooleanManually set a host as the storage pool manager (SPM).
[source]
----
POST /ovirt-engine/api/hosts/123/forceselectspm
----
With a request body like this:
[source,xml]
----
<action/>
----
<div class="paragraph">
<p>Manually set a host as the storage pool manager (SPM).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/hosts/123/forceselectspm</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action/></code></pre>
</div>
</div>
authorvalueLiron Aravot <laravot@redhat.com>datevalue14 Sep 2016statusvalueaddedforce_select_spmIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanGet the host details.
<div class="paragraph">
<p>Get the host details.</p>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddedgethostfalsefalsehostIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanInstall VDSM and related software on the host. The host type defines additional parameters for the action.
Example of installing a host, using `curl` and JSON, plain:
[source,bash]
----
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:
[source,bash]
----
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"
----
<div class="paragraph">
<p>Install VDSM and related software on the host. The host type defines additional parameters for the action.</p>
</div>
<div class="paragraph">
<p>Example of installing a host, using <code>curl</code> and JSON, plain:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">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"</code></pre>
</div>
</div>
<div class="paragraph">
<p>Example of installing a host, using <code>curl</code> and JSON, with hosted engine components:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">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"</code></pre>
</div>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>Roy Golan <rgolan@redhat.com>datevalue14 Sep 2016statusvalueaddedinstallThe password of of the `root` user, used to connect to the host via SSH.
<div class="paragraph">
<p>The password of of the <code>root</code> user, used to connect to the host via SSH.</p>
</div>
root_passwordtruetruestringThe SSH details used to connect to the host.
<div class="paragraph">
<p>The SSH details used to connect to the host.</p>
</div>
sshtruetruesshThis `override_iptables` property is used to indicate if the firewall configuration should be
replaced by the default one.
<div class="paragraph">
<p>This <code>override_iptables</code> property is used to indicate if the firewall configuration should be
replaced by the default one.</p>
</div>
hosttruetruehostWhen installing an oVirt node a image ISO file is needed.
<div class="paragraph">
<p>When installing an oVirt node a image ISO file is needed.</p>
</div>
imagetruetruestringIndicates if the installation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the installation should be performed asynchronously.</p>
</div>
asynctruetruebooleanWhen 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.
<div class="paragraph">
<p>When set to <code>true</code> it means this host should deploy also hosted
engine components. Missing value is treated as <code>true</code> i.e deploy.
Omitting this parameter means <code>false</code> and will perform no operation
in hosted engine area.</p>
</div>
deploy_hosted_enginetruetruebooleanWhen 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.
<div class="paragraph">
<p>When set to <code>true</code> 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 <code>true</code> i.e un-deploy
Omitting this parameter means <code>false</code> and will perform no operation
in hosted engine area.</p>
</div>
undeploy_hosted_enginetruetruebooleaniscsi_discoveriscsitruetrueiscsi_detailsiscsi_targetsfalsefalsestring[]Indicates if the discovery should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the discovery should be performed asynchronously.</p>
</div>
asynctruetruebooleaniscsi_loginiscsitruetrueiscsi_detailsIndicates if the login should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the login should be performed asynchronously.</p>
</div>
asynctruetruebooleanunregistered_storage_domains_discoveriscsitruetrueiscsi_detailsstorage_domainsfalsefalsestorage_domain[]Indicates if the discovery should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the discovery should be performed asynchronously.</p>
</div>
asynctruetruebooleanUpdate the host properties.
For example, to update a the kernel command line of a host send a request like this:
[source]
----
PUT /ovirt-engine/api/hosts/123
----
With request body like this:
[source, xml]
----
<host>
<os>
<custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline>
</os>
</host>
----
<div class="paragraph">
<p>Update the host properties.</p>
</div>
<div class="paragraph">
<p>For example, to update a the kernel command line of a host send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/hosts/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><host>
<os>
<custom_kernel_cmdline>vfio_iommu_type1.allow_unsafe_interrupts=1</custom_kernel_cmdline>
</os>
</host></code></pre>
</div>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>Oved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddedupdatehosttruetruehostIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanUpgrade VDSM and selected software on the host.
<div class="paragraph">
<p>Upgrade VDSM and selected software on the host.</p>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddedupgradeIndicates if the upgrade should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the upgrade should be performed asynchronously.</p>
</div>
asynctruetruebooleanrefreshIndicates if the refresh should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the refresh should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemove the host from the system.
[source]
----
#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request DELETE \
--header "Version: 4" \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc"
----
<div class="paragraph">
<p>Remove the host from the system.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request DELETE \
--header "Version: 4" \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc"</code></pre>
</div>
</div>
authorvalueOved Ourfali <oourfali@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis method is used to change the configuration of the network interfaces of a host.
For example, lets assume that you have a host with three network interfaces `eth0`, `eth1` and `eth2` and that
you want to configure a new bond using `eth0` and `eth1`, and put a VLAN on top of it. Using a simple shell
script and the `curl` command line HTTP client that can be done as follows:
[source]
----
#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
<modified_bonds>
<host_nic>
<name>bond0</name>
<bonding>
<options>
<option>
<name>mode</name>
<value>4</value>
</option>
<option>
<name>miimon</name>
<value>100</value>
</option>
</options>
<slaves>
<host_nic>
<name>eth1</name>
</host_nic>
<host_nic>
<name>eth2</name>
</host_nic>
</slaves>
</bonding>
</host_nic>
</modified_bonds>
<modified_network_attachments>
<network_attachment>
<network>
<name>myvlan</name>
</network>
<host_nic>
<name>bond0</name>
</host_nic>
<ip_address_assignments>
<assignment_method>static</assignment_method>
<ip_address_assignment>
<ip>
<address>192.168.122.10</address>
<netmask>255.255.255.0</netmask>
</ip>
</ip_address_assignment>
</ip_address_assignments>
</network_attachment>
</modified_network_attachments>
</action>
' \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc/setupnetworks"
----
Note that this is valid for version 4 of the API. In previous versions some elements were represented as XML
attributes instead of XML elements. In particular the `options` and `ip` elements were represented as follows:
[source,xml]
----
<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:
[source,python]
----
host.setupnetworks(
params.Action(
modified_bonds=params.HostNics(
host_nic=[
params.HostNIC(
name="bond0",
bonding=params.Bonding(
options=params.Options(
option=[
params.Option(name="mode", value="4"),
params.Option(name="miimon", value="100"),
],
),
slaves=params.Slaves(
host_nic=[
params.HostNIC(name="eth1"),
params.HostNIC(name="eth2"),
],
),
),
),
],
),
modified_network_attachments=params.NetworkAttachments(
network_attachment=[
params.NetworkAttachment(
network=params.Network(name="myvlan"),
host_nic=params.HostNIC(name="bond0"),
ip_address_assignments=params.IpAddressAssignments(
ip_address_assignment=[
params.IpAddressAssignment(
assignment_method="static",
ip=params.IP(
address="192.168.122.10",
netmask="255.255.255.0",
),
),
],
),
),
],
),
),
)
----
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 <<services/host/methods/commit_net_config, commitnetconfig>>.
<div class="paragraph">
<p>This method is used to change the configuration of the network interfaces of a host.</p>
</div>
<div class="paragraph">
<p>For example, lets assume that you have a host with three network interfaces <code>eth0</code>, <code>eth1</code> and <code>eth2</code> and that
you want to configure a new bond using <code>eth0</code> and <code>eth1</code>, and put a VLAN on top of it. Using a simple shell
script and the <code>curl</code> command line HTTP client that can be done as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<action>
<modified_bonds>
<host_nic>
<name>bond0</name>
<bonding>
<options>
<option>
<name>mode</name>
<value>4</value>
</option>
<option>
<name>miimon</name>
<value>100</value>
</option>
</options>
<slaves>
<host_nic>
<name>eth1</name>
</host_nic>
<host_nic>
<name>eth2</name>
</host_nic>
</slaves>
</bonding>
</host_nic>
</modified_bonds>
<modified_network_attachments>
<network_attachment>
<network>
<name>myvlan</name>
</network>
<host_nic>
<name>bond0</name>
</host_nic>
<ip_address_assignments>
<assignment_method>static</assignment_method>
<ip_address_assignment>
<ip>
<address>192.168.122.10</address>
<netmask>255.255.255.0</netmask>
</ip>
</ip_address_assignment>
</ip_address_assignments>
</network_attachment>
</modified_network_attachments>
</action>
' \
"${url}/hosts/1ff7a191-2f3b-4eff-812b-9f91a30c3acc/setupnetworks"</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that this is valid for version 4 of the API. In previous versions some elements were represented as XML
attributes instead of XML elements. In particular the <code>options</code> and <code>ip</code> elements were represented as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><options name="mode" value="4"/>
<options name="miimon" value="100"/>
<ip address="192.168.122.10" netmask="255.255.255.0"/></code></pre>
</div>
</div>
<div class="paragraph">
<p>Using the Python SDK the same can be done with the following code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python">host.setupnetworks(
params.Action(
modified_bonds=params.HostNics(
host_nic=[
params.HostNIC(
name="bond0",
bonding=params.Bonding(
options=params.Options(
option=[
params.Option(name="mode", value="4"),
params.Option(name="miimon", value="100"),
],
),
slaves=params.Slaves(
host_nic=[
params.HostNIC(name="eth1"),
params.HostNIC(name="eth2"),
],
),
),
),
],
),
modified_network_attachments=params.NetworkAttachments(
network_attachment=[
params.NetworkAttachment(
network=params.Network(name="myvlan"),
host_nic=params.HostNIC(name="bond0"),
ip_address_assignments=params.IpAddressAssignments(
ip_address_assignment=[
params.IpAddressAssignment(
assignment_method="static",
ip=params.IP(
address="192.168.122.10",
netmask="255.255.255.0",
),
),
],
),
),
],
),
),
)</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
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 <a href="#services/host/methods/commit_net_config">commitnetconfig</a>.
</td>
</tr>
</table>
</div>
setup_networksmodified_network_attachmentstruetruenetwork_attachment[]removed_network_attachmentstruetruenetwork_attachment[]synchronized_network_attachmentstruetruenetwork_attachment[]modified_bondstruetruehost_nic[]removed_bondstruetruehost_nic[]modified_labelstruetruenetwork_label[]removed_labelstruetruenetwork_label[]check_connectivitytruetruebooleanconnectivity_timeouttruetrueintegerIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanstatisticsstatisticspermissionsassigned_permissionstagsassigned_tagsfence_agentsfence_agentsdeviceshost_deviceshookshost_hooksReference to the service that manages the network interface devices on the host.
<div class="paragraph">
<p>Reference to the service that manages the network interface devices on the host.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddednicshost_nicsnuma_nodeshost_numa_nodesstoragehost_storagekatello_erratakatello_erratanetwork_attachmentsnetwork_attachmentsstorage_connection_extensionsstorage_server_connection_extensionsunmanaged_networksunmanaged_networksList of scheduling labels assigned to this host.
<div class="paragraph">
<p>List of scheduling labels assigned to this host.</p>
</div>
affinity_labelsassigned_affinity_labelsareavalueInfrastructureexternal_provider_certificateslistcertificatesfalsefalsecertificate[]Sets the maximum number of certificates to return. If not specified all the certificates are returned.
<div class="paragraph">
<p>Sets the maximum number of certificates to return. If not specified all the certificates are returned.</p>
</div>
maxtruetrueintegercertificateexternal_provider_certificateidfalsefalsestringareavalueVirtualizationvm_host_devicegetdevicefalsefalsehost_deviceremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueInfrastructuretaggettagfalsefalsetagupdatetagtruetruetagIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueSLAhost_numa_nodeslistnodesfalsefalsenuma_node[]Sets the maximum number of nodes to return. If not specified all the nodes are returned.
<div class="paragraph">
<p>Sets the maximum number of nodes to return. If not specified all the nodes are returned.</p>
</div>
maxtruetrueintegernodehost_numa_nodeidfalsefalsestringareavalueInfrastructureassigned_tagsaddtagtruetruetaglisttagsfalsefalsetag[]Sets the maximum number of tags to return. If not specified all the tags are returned.
<div class="paragraph">
<p>Sets the maximum number of tags to return. If not specified all the tags are returned.</p>
</div>
maxtruetrueintegertagassigned_tagidfalsefalsestringareavalueInfrastructurejobclearIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanendforcetruetruebooleanIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleangetjobfalsefalsejobstepsstepsareavalueVirtualizationfilegetfilefalsefalsefileareavalueInfrastructurestepsaddsteptruetruestepliststepsfalsefalsestep[]Sets the maximum number of steps to return. If not specified all the steps are returned.
<div class="paragraph">
<p>Sets the maximum number of steps to return. If not specified all the steps are returned.</p>
</div>
maxtruetrueintegerstepstepidfalsefalsestringareavalueStoragestorage_domain_server_connectiongetconnectionfalsefalsestorage_connectionDetaches a storage connection from storage.
<div class="paragraph">
<p>Detaches a storage connection from storage.</p>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanProvides read-only access to the global set of roles
<div class="paragraph">
<p>Provides read-only access to the global set of roles</p>
</div>
areavalueInfrastructurerolesCreate 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):
[source]
----
POST /ovirt-engine/api/roles
----
With a request body like this:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Create a new role. The role can be administrative or non-administrative and can have different permits.</p>
</div>
<div class="paragraph">
<p>For example, to add the <code>MyRole</code> non-administrative role with permits to login and create virtual machines
send a request like this (note that you have to pass permit id):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/roles</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddedaddroletruetruerolelistrolesfalsefalserole[]Sets the maximum number of roles to return. If not specified all the roles are returned.
<div class="paragraph">
<p>Sets the maximum number of roles to return. If not specified all the roles are returned.</p>
</div>
maxtruetrueintegerSub-resource locator method, returns individual role resource on which the remainder of the URI is dispatched.
<div class="paragraph">
<p>Sub-resource locator method, returns individual role resource on which the remainder of the URI is dispatched.</p>
</div>
roleroleidfalsefalsestringThis service provides a mechanism to control an image transfer. The client will have
to create a transfer by using <<services/image_transfers/methods/add, add>>
of the <<services/image_transfers>> service, stating the image to transfer
data to/from.
After doing that, the transfer is managed by this service.
E.g., for uploading to the disk image with id `52cb593f-837c-4633-a444-35a0a0383706`,
the client can use oVirt's Python's SDK as follows:
[source,python]
----
transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
types.ImageTransfer(
image=types.Image(
id='52cb593f-837c-4633-a444-35a0a0383706'
)
)
)
----
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
<<types/image_transfer_phase, ImageTransferPhase>>.
After adding a new transfer, its phase will be <<types/image_transfer_phase, initializing>>.
The client will have to poll on the transfer's phase until it changes.
When the phase becomes <<types/image_transfer_phase, transferring>>,
the session is ready to start the transfer.
For example:
[source,python]
----
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 <<types/image_transfer_phase, 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 <<services/image_transfer/methods/resume, resume>>
of the service that manages it.
If the session was successfully established - the returned transfer entity will
contain the <<types/image_transfer, proxy_url>> and <<types/image_transfer, 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 an upload,
so an `upload_headers` dict is set for the upcoming upload:
[source,python]
----
upload_headers = {
'Authorization' : transfer.signed_ticket,
}
----
Using Python's `HTTPSConnection`, a new connection is established:
[source,python]
----
# Extract the URI, port, and path from the transfer's proxy_url.
url = urlparse(transfer.proxy_url)
# Create a new instance of the connection.
proxy_connection = HTTPSConnection(
url.hostname,
url.port,
context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)
)
----
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:
[source,python]
----
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()
upload_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=upload_headers
)
r = proxy_connection.getresponse()
print r.status, r.reason, "Completed", "{:.0%}".format(pos/ float(size))
pos += chunk_size
----
When finishing the transfer, the user should call
<<services/image_transfer/methods/finalize, finalize>>. This will make the
final adjustments and verifications for finishing the transfer process.
For example:
[source,python]
----
transfer_service.finalize()
----
In case of an error, the transfer's phase will be changed to
<<types/image_transfer_phase, finished_failure>>, and
the disk's status will be changed to `Illegal`. Otherwise it will be changed to
<<types/image_transfer_phase, finished_success>>, and the disk will be ready
to be used. In both cases, the transfer entity will be removed shortly after.
<div class="paragraph">
<p>This service provides a mechanism to control an image transfer. The client will have
to create a transfer by using <a href="#services/image_transfers/methods/add">add</a>
of the <a href="#services/image_transfers">[services/image_transfers]</a> service, stating the image to transfer
data to/from.</p>
</div>
<div class="paragraph">
<p>After doing that, the transfer is managed by this service.</p>
</div>
<div class="paragraph">
<p>E.g., for uploading to the disk image with id <code>52cb593f-837c-4633-a444-35a0a0383706</code>,
the client can use oVirt’s Python’s SDK as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python">transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
types.ImageTransfer(
image=types.Image(
id='52cb593f-837c-4633-a444-35a0a0383706'
)
)
)</code></pre>
</div>
</div>
<div class="paragraph">
<p>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
<a href="#types/image_transfer_phase">ImageTransferPhase</a>.</p>
</div>
<div class="paragraph">
<p>After adding a new transfer, its phase will be <a href="#types/image_transfer_phase">initializing</a>.
The client will have to poll on the transfer’s phase until it changes.
When the phase becomes <a href="#types/image_transfer_phase">transferring</a>,
the session is ready to start the transfer.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python">transfer_service = transfers_service.image_transfer_service(transfer.id)
while transfer.phase == types.ImageTransferPhase.INITIALIZING:
time.sleep(3)
transfer = transfer_service.get()</code></pre>
</div>
</div>
<div class="paragraph">
<p>At that stage, if the transfer’s phase is <a href="#types/image_transfer_phase">paused_system</a>, 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 <a href="#services/image_transfer/methods/resume">resume</a>
of the service that manages it.</p>
</div>
<div class="paragraph">
<p>If the session was successfully established - the returned transfer entity will
contain the <a href="#types/image_transfer">proxy_url</a> and <a href="#types/image_transfer">signed_ticket</a> 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.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>proxy_url</code> is the address of a proxy server to the image, to do I/O to.</p>
</li>
<li>
<p><code>signed_ticket</code> is the content that needs to be added to the <code>Authentication</code>
header in the HTTPS request, in order to perform a trusted communication.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For example, Python’s HTTPSConnection can be used in order to perform an upload,
so an <code>upload_headers</code> dict is set for the upcoming upload:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python">upload_headers = {
'Authorization' : transfer.signed_ticket,
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Using Python’s <code>HTTPSConnection</code>, a new connection is established:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python"># Extract the URI, port, and path from the transfer's proxy_url.
url = urlparse(transfer.proxy_url)
# Create a new instance of the connection.
proxy_connection = HTTPSConnection(
url.hostname,
url.port,
context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)
)</code></pre>
</div>
</div>
<div class="paragraph">
<p>The specific content range being sent must be noted in the <code>Content-Range</code> HTTPS
header. This can be used in order to split the transfer into several requests for
a more flexible process.</p>
</div>
<div class="paragraph">
<p>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 <code>paused_system</code> phase, and HTTPS requests to the server will be rejected.</p>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python">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()
upload_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=upload_headers
)
r = proxy_connection.getresponse()
print r.status, r.reason, "Completed", "{:.0%}".format(pos/ float(size))
pos += chunk_size</code></pre>
</div>
</div>
<div class="paragraph">
<p>When finishing the transfer, the user should call
<a href="#services/image_transfer/methods/finalize">finalize</a>. This will make the
final adjustments and verifications for finishing the transfer process.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python">transfer_service.finalize()</code></pre>
</div>
</div>
<div class="paragraph">
<p>In case of an error, the transfer’s phase will be changed to
<a href="#types/image_transfer_phase">finished_failure</a>, and
the disk’s status will be changed to <code>Illegal</code>. Otherwise it will be changed to
<a href="#types/image_transfer_phase">finished_success</a>, and the disk will be ready
to be used. In both cases, the transfer entity will be removed shortly after.</p>
</div>
areavalueStorageauthorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4image_transferGet the image transfer entity.
<div class="paragraph">
<p>Get the image transfer entity.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4getimage_transferfalsefalseimage_transferExtend the image transfer session.
<div class="paragraph">
<p>Extend the image transfer session.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4extendPause the image transfer session.
<div class="paragraph">
<p>Pause the image transfer session.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4pauseResume the image transfer session. The client will need to poll the transfer's phase until
it is different than `resuming`. For example:
[source,python]
----
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()
----
<div class="paragraph">
<p>Resume the image transfer session. The client will need to poll the transfer’s phase until
it is different than <code>resuming</code>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-python" data-lang="python">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()</code></pre>
</div>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4resumeAfter 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.
<div class="paragraph">
<p>After finishing to transfer the data, finalize the transfer.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4finalizeareavalueNetworkassigned_vnic_profilegetprofilefalsefalsevnic_profileremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanpermissionsassigned_permissionsareavalueVirtualizationtemplate_watchdoggetwatchdogfalsefalsewatchdogupdatewatchdogtruetruewatchdogIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueVirtualizationvm_sessiongetsessionfalsefalsesessionareavalueNetworkvm_nicactivateIndicates if the activation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the activation should be performed asynchronously.</p>
</div>
asynctruetruebooleandeactivateIndicates if the deactivation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the deactivation should be performed asynchronously.</p>
</div>
asynctruetruebooleangetnicfalsefalsenicUpdates the NIC.
For example, to update the NIC having with `456` belonging to virtual the machine with id `123` send a request
like this:
[source]
----
PUT /ovirt-engine/api/vms/123/nics/456
----
With a request body like this:
[source,xml]
----
<nic>
<name>mynic</name>
<interface>e1000</interface>
</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
====
<div class="paragraph">
<p>Updates the NIC.</p>
</div>
<div class="paragraph">
<p>For example, to update the NIC having with <code>456</code> belonging to virtual the machine with id <code>123</code> send a request
like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/vms/123/nics/456</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><nic>
<name>mynic</name>
<interface>e1000</interface>
</nic></code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
<div class="paragraph">
<p>The hotplugging feature only supports virtual machine operating systems with hotplugging operations.
Example operating systems include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Red Hat Enterprise Linux 6</p>
</li>
<li>
<p>Red Hat Enterprise Linux 5</p>
</li>
<li>
<p>Windows Server 2008 and</p>
</li>
<li>
<p>Windows Server 2003</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedupdatenictruetruenicIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves the NIC.
For example, to remove the NIC with id `456` from the virtual machine with id `123` send a request like this:
[source]
----
DELETE /ovirt-engine/api/vms/123/nics/456
----
[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
====
<div class="paragraph">
<p>Removes the NIC.</p>
</div>
<div class="paragraph">
<p>For example, to remove the NIC with id <code>456</code> from the virtual machine with id <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/vms/123/nics/456</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
<div class="paragraph">
<p>The hotplugging feature only supports virtual machine operating systems with hotplugging operations.
Example operating systems include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Red Hat Enterprise Linux 6</p>
</li>
<li>
<p>Red Hat Enterprise Linux 5</p>
</li>
<li>
<p>Windows Server 2008 and</p>
</li>
<li>
<p>Windows Server 2003</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanstatisticsstatisticsreported_devicesvm_reported_devicesareavalueStoragesnapshotsCreates a virtual machine snapshot.
For example, to create a new snapshot for virtual machine `123` send a request like this:
[source]
----
POST /ovirt-engine/api/vms/123/snapshots
----
With a request body like this:
[source,xml]
----
<snapshot>
<description>My snapshot</description>
</snapshot>
----
<div class="paragraph">
<p>Creates a virtual machine snapshot.</p>
</div>
<div class="paragraph">
<p>For example, to create a new snapshot for virtual machine <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/snapshots</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><snapshot>
<description>My snapshot</description>
</snapshot></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedaddsnapshottruetruesnapshotlistsnapshotsfalsefalsesnapshot[]Sets the maximum number of snapshots to return. If not specified all the snapshots are returned.
<div class="paragraph">
<p>Sets the maximum number of snapshots to return. If not specified all the snapshots are returned.</p>
</div>
maxtruetrueintegersnapshotsnapshotidfalsefalsestringReturns the details of a disk attached to a virtual machine in the export domain.
<div class="paragraph">
<p>Returns the details of a disk attached to a virtual machine in the export domain.</p>
</div>
areavalueStorageauthorvalueTal Nisan <tnisan@redhat.com>datevalue6 Sep 2016statusvalueaddedsincevalue4.0.4storage_domain_vm_disk_attachmentsList the disks that are attached to the virtual machine.
<div class="paragraph">
<p>List the disks that are attached to the virtual machine.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue6 Sep 2016statusvalueaddedsincevalue4.0.4listattachmentsfalsefalsedisk_attachment[]Reference to the service that manages a specific attachment.
<div class="paragraph">
<p>Reference to the service that manages a specific attachment.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue6 Sep 2016statusvalueaddedsincevalue4.0.4attachmentstorage_domain_vm_disk_attachmentidfalsefalsestringareavalueStorageimagegetimagefalsefalseimageimportCluster where the image should be imported. Has effect only in case `import_as_template` parameter
is set to `true`.
<div class="paragraph">
<p>Cluster where the image should be imported. Has effect only in case <code>import_as_template</code> parameter
is set to <code>true</code>.</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue11 Oct 2016statusvalueaddedclustertruetrueclusterThe disk which should be imported.
<div class="paragraph">
<p>The disk which should be imported.</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue11 Oct 2016statusvalueaddeddisktruetruediskSpecify if template should be created from the imported disk.
<div class="paragraph">
<p>Specify if template should be created from the imported disk.</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue11 Oct 2016statusvalueaddedimport_as_templatetruetruebooleanName of the template, which should be created. Has effect only in case `import_as_template` parameter
is set to `true`.
<div class="paragraph">
<p>Name of the template, which should be created. Has effect only in case <code>import_as_template</code> parameter
is set to <code>true</code>.</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue11 Oct 2016statusvalueaddedtemplatetruetruetemplateStorage domain where disk should be imported.
<div class="paragraph">
<p>Storage domain where disk should be imported.</p>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue11 Oct 2016statusvalueaddedstorage_domaintruetruestorage_domainIndicates if the import should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the import should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworkinstance_type_nicsaddnictruetrueniclistnicsfalsefalsenic[]Sets the maximum number of NICs to return. If not specified all the NICs are returned.
<div class="paragraph">
<p>Sets the maximum number of NICs to return. If not specified all the NICs are returned.</p>
</div>
maxtruetrueintegernicinstance_type_nicidfalsefalsestringareavalueVirtualizationoperating_systemslistoperating_systemfalsefalseoperating_system_info[]Sets the maximum number of networks to return. If not specified all the networks are returned.
<div class="paragraph">
<p>Sets the maximum number of networks to return. If not specified all the networks are returned.</p>
</div>
maxtruetrueintegeroperating_systemoperating_systemidfalsefalsestringareavalueNetworkhost_nicgetnicfalsefalsehost_nicThe 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.
<div class="paragraph">
<p>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:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>allNetworksAllowed</code></p>
</li>
<li>
<p><code>numberOfVirtualFunctions</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Please see the <code>HostNicVirtualFunctionsConfiguration</code> type for the meaning of the properties.</p>
</div>
update_virtual_functions_configurationvirtual_functions_configurationtruetruehost_nic_virtual_functions_configurationIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanstatisticsstatisticsnetwork_labelsnetwork_labelsnetwork_attachmentsnetwork_attachmentsRetrieves sub-collection resource of network labels that are allowed on an the virtual functions
in case that the current resource represents an SR-IOV physical function NIC.
<div class="paragraph">
<p>Retrieves sub-collection resource of network labels that are allowed on an the virtual functions
in case that the current resource represents an SR-IOV physical function NIC.</p>
</div>
virtual_function_allowed_labelsnetwork_labelsRetrieves sub-collection resource of networks that are allowed on an the virtual functions
in case that the current resource represents an SR-IOV physical function NIC.
<div class="paragraph">
<p>Retrieves sub-collection resource of networks that are allowed on an the virtual functions
in case that the current resource represents an SR-IOV physical function NIC.</p>
</div>
virtual_function_allowed_networksvirtual_function_allowed_networksareavalueStorageiscsi_bondsCreate 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:
[source]
----
POST /ovirt-engine/api/datacenters/123/iscsibonds
----
The request body should look like this:
[source,xml]
----
<iscsi_bond>
<name>mybond</name>
<storage_connections>
<storage_connection id="456"/>
<storage_connection id="789"/>
</storage_connections>
<networks>
<network id="abc"/>
</networks>
</iscsi_bond>
----
<div class="paragraph">
<p>Create a new iSCSI bond on a data center.</p>
</div>
<div class="paragraph">
<p>For example, to create a new iSCSI bond on data center <code>123</code> using storage connections <code>456</code> and <code>789</code>, send a
request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/datacenters/123/iscsibonds</code></pre>
</div>
</div>
<div class="paragraph">
<p>The request body should look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><iscsi_bond>
<name>mybond</name>
<storage_connections>
<storage_connection id="456"/>
<storage_connection id="789"/>
</storage_connections>
<networks>
<network id="abc"/>
</networks>
</iscsi_bond></code></pre>
</div>
</div>
authorvalueMaor Lipchuk <mlipchuk@redhat.com>datevalue14 Sep 2016statusvalueaddedaddbondtruetrueiscsi_bondlistbondsfalsefalseiscsi_bond[]Sets the maximum number of bonds to return. If not specified all the bonds are returned.
<div class="paragraph">
<p>Sets the maximum number of bonds to return. If not specified all the bonds are returned.</p>
</div>
maxtruetrueintegeriscsi_bondiscsi_bondidfalsefalsestringareavalueInfrastructureusersAdd user from a directory service.
For example, to add the `myuser` user from the `myextension-authz` authorization provider send a request
like this:
[source]
----
POST /ovirt-engine/api/users
----
With a request body like this:
[source,xml]
----
<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 https://bugzilla.redhat.com/1147900[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:
[source,xml]
----
<user>
<principal>myuser@mysubdomain.mydomain.com</principal>
<user_name>myuser@mysubdomain.mydomain.com@myextension-authz</user_name>
<domain>
<name>myextension-authz</name>
</domain>
</user>
----
<div class="paragraph">
<p>Add user from a directory service.</p>
</div>
<div class="paragraph">
<p>For example, to add the <code>myuser</code> user from the <code>myextension-authz</code> authorization provider send a request
like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/users</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><user>
<user_name>myuser@myextension-authz</user_name>
<domain>
<name>myextension-authz</name>
</domain>
</user></code></pre>
</div>
</div>
<div class="paragraph">
<p>In case you are working with Active Directory you have to pass user principal name (UPN) as <code>username</code>, followed
by authorization provider name. Due to <a href="https://bugzilla.redhat.com/1147900">bug 1147900</a> you need to provide
also <code>principal</code> parameter set to UPN of the user.</p>
</div>
<div class="paragraph">
<p>For example, to add the user with UPN <code>myuser@mysubdomain.mydomain.com</code> from the <code>myextension-authz</code>
authorization provider send a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><user>
<principal>myuser@mysubdomain.mydomain.com</principal>
<user_name>myuser@mysubdomain.mydomain.com@myextension-authz</user_name>
<domain>
<name>myextension-authz</name>
</domain>
</user></code></pre>
</div>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddedaddusertruetrueuserlistusersfalsefalseuser[]Sets the maximum number of users to return. If not specified all the users are returned.
<div class="paragraph">
<p>Sets the maximum number of users to return. If not specified all the users are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned users.
<div class="paragraph">
<p>A query string used to restrict the returned users.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanuseruseridfalsefalsestringareavalueInfrastructuregroupsAdd 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:
[source]
----
POST /ovirt-engine/api/groups
----
With a request body like this:
[source,xml]
----
<group>
<name>Developers</name>
<domain>
<name>internal-authz</name>
</domain>
</group>
----
<div class="paragraph">
<p>Add group from a directory service. Please note that domain name is name of the authorization provider.</p>
</div>
<div class="paragraph">
<p>For example, to add the <code>Developers</code> group from the <code>internal-authz</code> authorization provider send a request
like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/groups</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><group>
<name>Developers</name>
<domain>
<name>internal-authz</name>
</domain>
</group></code></pre>
</div>
</div>
authorvalueOndra Machacek <omachace@redhat.com>datevalue14 Sep 2016statusvalueaddedaddgrouptruetruegrouplistgroupsfalsefalsegroup[]Sets the maximum number of groups to return. If not specified all the groups are returned.
<div class="paragraph">
<p>Sets the maximum number of groups to return. If not specified all the groups are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned groups.
<div class="paragraph">
<p>A query string used to restrict the returned groups.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleangroupgroupidfalsefalsestringareavalueInfrastructuredomaingetdomainfalsefalsedomainusersdomain_usersgroupsdomain_groupsareavalueInfrastructuressh_public_keysaddkeytruetruessh_public_keylistkeysfalsefalsessh_public_key[]Sets the maximum number of keys to return. If not specified all the keys are returned.
<div class="paragraph">
<p>Sets the maximum number of keys to return. If not specified all the keys are returned.</p>
</div>
maxtruetrueintegerkeyssh_public_keyidfalsefalsestringareavalueInfrastructuredomain_usergetuserfalsefalseuserareavalueInfrastructureusergetuserfalsefalseuserremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanrolesassigned_rolespermissionsassigned_permissionstagsassigned_tagsssh_public_keysssh_public_keysareavalueInfrastructuredomainslistdomainsfalsefalsedomain[]Sets the maximum number of domains to return. If not specified all the domains are returned.
<div class="paragraph">
<p>Sets the maximum number of domains to return. If not specified all the domains are returned.</p>
</div>
maxtruetrueintegerdomaindomainidfalsefalsestringareavalueInfrastructuredomain_userslistusersfalsefalseuser[]Sets the maximum number of users to return. If not specified all the users are returned.
<div class="paragraph">
<p>Sets the maximum number of users to return. If not specified all the users are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned users.
<div class="paragraph">
<p>A query string used to restrict the returned users.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanuserdomain_useridfalsefalsestringareavalueInfrastructuredomain_groupslistgroupsfalsefalsegroup[]Sets the maximum number of groups to return. If not specified all the groups are returned.
<div class="paragraph">
<p>Sets the maximum number of groups to return. If not specified all the groups are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned groups.
<div class="paragraph">
<p>A query string used to restrict the returned groups.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleangroupdomain_groupidfalsefalsestringareavalueInfrastructuregroupgetgetfalsefalsegroupremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanrolesassigned_rolespermissionsassigned_permissionstagsassigned_tagsareavalueInfrastructuredomain_groupgetgetfalsefalsegroupareavalueInfrastructuressh_public_keygetkeyfalsefalsessh_public_keyupdatekeytruetruessh_public_keyIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueInfrastructurefence_agentgetagentfalsefalseagentupdateagenttruetrueagentIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworkmac_poolgetpoolfalsefalsemac_poolUpdates 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:
[source]
----
PUT /ovirt-engine/api/macpools/123
----
With a request body like this:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Updates a MAC address pool.</p>
</div>
<div class="paragraph">
<p>The <code>name</code>, <code>description</code>, <code>allow_duplicates</code>, and <code>ranges</code> attributes can be updated.</p>
</div>
<div class="paragraph">
<p>For example, to update the MAC address pool of id <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/macpools/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedupdatepooltruetruemac_poolIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves a MAC address pool.
For example, to remove the MAC address pool having id `123` send a request like this:
[source]
----
DELETE /ovirt-engine/api/macpools/123
----
<div class="paragraph">
<p>Removes a MAC address pool.</p>
</div>
<div class="paragraph">
<p>For example, to remove the MAC address pool having id <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/macpools/123</code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueVirtualizationassigned_cpu_profilesaddprofiletruetruecpu_profilelistprofilesfalsefalsecpu_profile[]Sets the maximum number of profiles to return. If not specified all the profiles are returned.
<div class="paragraph">
<p>Sets the maximum number of profiles to return. If not specified all the profiles are returned.</p>
</div>
maxtruetrueintegerprofileassigned_cpu_profileidfalsefalsestringareavalueStoragestorage_server_connection_extensionsCreates 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:
[source]
----
POST /ovirt-engine/api/hosts/123/storageconnectionextensions
----
With a request body like this:
[source,xml]
----
<storage_connection_extension>
<target>iqn.2016-01.com.example:mytarget</target>
<username>myuser</username>
<password>mypassword</password>
</storage_connection_extension>
----
<div class="paragraph">
<p>Creates a new storage server connection extension for the given host.</p>
</div>
<div class="paragraph">
<p>The extension lets the user define credentials for an iSCSI target for a specific host. For example to use
<code>myuser</code> and <code>mypassword</code> as the credentials when connecting to the iSCSI target from host <code>123</code> send a request
like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/hosts/123/storageconnectionextensions</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_connection_extension>
<target>iqn.2016-01.com.example:mytarget</target>
<username>myuser</username>
<password>mypassword</password>
</storage_connection_extension></code></pre>
</div>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue20 Sep 2016statusvalueaddedaddextensiontruetruestorage_connection_extensionlistextensionsfalsefalsestorage_connection_extension[]Sets the maximum number of extensions to return. If not specified all the extensions are returned.
<div class="paragraph">
<p>Sets the maximum number of extensions to return. If not specified all the extensions are returned.</p>
</div>
maxtruetrueintegerstorage_connection_extensionstorage_server_connection_extensionidfalsefalsestringareavalueInfrastructurepermissiongetpermissionfalsefalsepermissionremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueStoragedisk_profilegetprofilefalsefalsedisk_profileupdateprofiletruetruedisk_profileIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanpermissionsassigned_permissionsThis service manages a single affinity group.
<div class="paragraph">
<p>This service manages a single affinity group.</p>
</div>
areavalueSLAauthorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedaffinity_groupRetrieve the affinity group details.
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Retrieve the affinity group details.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedgetThe affinity group.
<div class="paragraph">
<p>The affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedgroupfalsefalseaffinity_groupUpdate the affinity group.
<div class="paragraph">
<p>Update the affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedupdateThe affinity group.
<div class="paragraph">
<p>The affinity group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedgrouptruetrueaffinity_groupIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemove the affinity group.
[source]
----
DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456
----
<div class="paragraph">
<p>Remove the affinity group.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/clusters/000-000/affinitygroups/123-456</code></pre>
</div>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanReturns a reference to the service that manages the
list of all virtual machines attached to this affinity
group.
<div class="paragraph">
<p>Returns a reference to the service that manages the
list of all virtual machines attached to this affinity
group.</p>
</div>
authorvalueMartin Sivak <msivak@redhat.com>datevalue14 Sep 2016statusvalueaddedvmsaffinity_group_vmsareavalueNetworkunmanaged_networkslistnetworksfalsefalseunmanaged_network[]Sets the maximum number of networks to return. If not specified all the networks are returned.
<div class="paragraph">
<p>Sets the maximum number of networks to return. If not specified all the networks are returned.</p>
</div>
maxtruetrueintegerunmanaged_networkunmanaged_networkidfalsefalsestringareavalueVirtualizationvmsCreates 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:
[source,bash]
----
#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
<name>myvm</name>
<template>
<name>Blank</name>
</template>
<cluster>
<name>mycluster</name>
</cluster>
</vm>
' \
"${url}/vms"
----
- From a snapshot. In this case the identifier of the snapshot has to be provided. For example, using a plain
shel script and XML:
[source,bash]
----
#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
<name>myvm</name>
<snapshots>
<snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/>
</snapshots>
<cluster>
<name>mycluster</name>
</cluster>
</vm>
' \
"${url}/vms"
----
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:
[source,xml]
----
<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`.
[source,xml]
----
<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:
[source,xml]
----
<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:
[source,xml]
----
<vm>
...
<os>
<boot dev="cdrom"/>
</os>
</vm>
----
In order to boot from CDROM, you first need to insert a disk, as described in the
<<services/vm_cdrom, CDROM service>>. Then booting from that CDROM can be specified using the `os.boot.devices`
attribute:
[source,xml]
----
<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.
<div class="paragraph">
<p>Creates a new virtual machine.</p>
</div>
<div class="paragraph">
<p>The virtual machine can be created in different ways:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>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:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
<name>myvm</name>
<template>
<name>Blank</name>
</template>
<cluster>
<name>mycluster</name>
</cluster>
</vm>
' \
"${url}/vms"</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>From a snapshot. In this case the identifier of the snapshot has to be provided. For example, using a plain
shel script and XML:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">#!/bin/sh -ex
url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
<name>myvm</name>
<snapshots>
<snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/>
</snapshots>
<cluster>
<name>mycluster</name>
</cluster>
</vm>
' \
"${url}/vms"</code></pre>
</div>
</div>
<div class="paragraph">
<p>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 <code>disk_attachment</code> elements that indicate the mapping:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>When the virtual machine is created from a snapshot this set of disks is slightly different, it uses the
<code>image_id</code> attribute instead of <code>id</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>It is possible to specify additional virtual machine parameters in the XML description, e.g. a virtual machine
of <code>desktop</code> type, with 2 GiB of RAM and additional description can be added sending a request body like the
following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<name>myvm</name>
<description>My Desktop Virtual Machine</description>
<type>desktop</type>
<memory>2147483648</memory>
...
</vm></code></pre>
</div>
</div>
<div class="paragraph">
<p>A bootable CDROM device can be set like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
...
<os>
<boot dev="cdrom"/>
</os>
</vm></code></pre>
</div>
</div>
<div class="paragraph">
<p>In order to boot from CDROM, you first need to insert a disk, as described in the
<a href="#services/vm_cdrom">CDROM service</a>. Then booting from that CDROM can be specified using the <code>os.boot.devices</code>
attribute:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
...
<os>
<boot>
<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm></code></pre>
</div>
</div>
<div class="paragraph">
<p>In all cases the name or identifier of the cluster where the virtual machine will be created is mandatory.</p>
</div>
authorvalueMilan Zamazal <mzamazal@redhat.com>datevalue14 Sep 2016statusvalueaddedaddvmtruetruevmSpecifies 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 https://en.wikipedia.org/wiki/Copy-on-write[_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:
[source]
----
POST /ovirt-engine/vms?clone=true
----
With a request body like this:
[source,xml]
----
<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`.
<div class="paragraph">
<p>Specifies if the virtual machine should be independent of the template.</p>
</div>
<div class="paragraph">
<p>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 <a href="https://en.wikipedia.org/wiki/Copy-on-write"><em>copy on write</em></a>
mechanism so that only the differences from the template take up real storage space. If this parameter is
specified and the value is <code>true</code> then the disks of the created virtual machine will be <em>cloned</em>, and
independent of the template. For example, to create an independent virtual machine, send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/vms?clone=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<name>myvm<name>
<template>
<name>mytemplate<name>
</template>
<cluster>
<name>mycluster<name>
</cluster>
</vm></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
When this parameter is <code>true</code> the permissions of the template will also be copied, as when using
<code>clone_permissions=true</code>.
</td>
</tr>
</table>
</div>
clonetruetruebooleanSpecifies 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:
[source]
----
POST /ovirt-engine/api/vms?clone_permissions=true
----
With a request body like this:
[source,xml]
----
<vm>
<name>myvm<name>
<template>
<name>mytemplate<name>
</template>
<cluster>
<name>mycluster<name>
</cluster>
</vm>
----
<div class="paragraph">
<p>Specifies if the permissions of the template should be copied to the virtual machine.</p>
</div>
<div class="paragraph">
<p>If this optional parameter is provided, and its values is <code>true</code> 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 <code>mytemplate</code> template copying its permissions, send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms?clone_permissions=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<name>myvm<name>
<template>
<name>mytemplate<name>
</template>
<cluster>
<name>mycluster<name>
</cluster>
</vm></code></pre>
</div>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue16 Aug 2016statusvalueaddedsincevalue4.0.0clone_permissionstruetruebooleanlistvmsfalsefalsevm[]A query string used to restrict the returned virtual machines.
<div class="paragraph">
<p>A query string used to restrict the returned virtual machines.</p>
</div>
searchtruetruestringThe maximum number of results to return.
<div class="paragraph">
<p>The maximum number of results to return.</p>
</div>
maxtruetrueintegerIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanIndicates if all the attributes of the virtual machines should be included in the response.
By default the following attributes are excluded:
- `console`
- `initialization.configuration.data` - The OVF document describing the virtual machine.
- `rng_source`
- `soundcard`
- `virtio_scsi`
For example, to retrieve the complete representation of the virtual machines send a request like this:
....
GET /ovirt-engine/api/vms?all_content=true
....
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.
<div class="paragraph">
<p>Indicates if all the attributes of the virtual machines should be included in the response.</p>
</div>
<div class="paragraph">
<p>By default the following attributes are excluded:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>console</code></p>
</li>
<li>
<p><code>initialization.configuration.data</code> - The OVF document describing the virtual machine.</p>
</li>
<li>
<p><code>rng_source</code></p>
</li>
<li>
<p><code>soundcard</code></p>
</li>
<li>
<p><code>virtio_scsi</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For example, to retrieve the complete representation of the virtual machines send a request like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/vms?all_content=true</pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue11 Oct 2016statusvalueaddedsincevalue4.0.6all_contenttruetruebooleanvmvmidfalsefalsestringareavalueStoragestorage_domain_templategettemplatefalsefalsetemplateimportclonetruetruebooleanclustertruetrueclusterexclusivetruetruebooleanstorage_domaintruetruestorage_domaintemplatetruetruetemplatevmtruetruevmIndicates if the import should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the import should be performed asynchronously.</p>
</div>
asynctruetruebooleanregisterclonetruetruebooleanclustertruetrueclusterexclusivetruetruebooleantemplatetruetruetemplateIndicates if the registration should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the registration should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleandisksstorage_domain_content_disksareavalueVirtualizationvm_poolsCreates 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:
[source]
----
POST /ovirt-engine/api/vmpools
----
With the following body:
[source,xml]
----
<vmpool>
<name>mypool</name>
<cluster id="123"/>
<template id="456"/>
</vmpool>
----
<div class="paragraph">
<p>Creates a new virtual machine pool.</p>
</div>
<div class="paragraph">
<p>A new pool requires the <code>name</code>, <code>cluster</code> and <code>template</code> attributes. Identify the cluster and template with the
<code>id</code> or <code>name</code> nested attributes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vmpools</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the following body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vmpool>
<name>mypool</name>
<cluster id="123"/>
<template id="456"/>
</vmpool></code></pre>
</div>
</div>
authorvalueShahar Havivi <shavivi@redhat.com>datevalue14 Sep 2016statusvalueaddedaddpooltruetruevm_poollistpoolsfalsefalsevm_pool[]Sets the maximum number of pools to return. If this value is not specified, all of the pools are returned.
<div class="paragraph">
<p>Sets the maximum number of pools to return. If this value is not specified, all of the pools are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned pools.
<div class="paragraph">
<p>A query string used to restrict the returned pools.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanpoolvm_poolidfalsefalsestringareavalueStorageassigned_disk_profilesaddprofiletruetruedisk_profilelistprofilesfalsefalsedisk_profile[]Sets the maximum number of profiles to return. If not specified all the profiles are returned.
<div class="paragraph">
<p>Sets the maximum number of profiles to return. If not specified all the profiles are returned.</p>
</div>
maxtruetrueintegerprofileassigned_disk_profileidfalsefalsestringareavalueInfrastructurestependforcetruetruebooleansucceededtruetruebooleanIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleangetstepfalsefalsestepstatisticsstatisticsManages a network filter.
[source,xml]
----
<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.
<div class="paragraph">
<p>Manages a network filter.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>Please note that version is referring to the minimal support version for the specific filter.</p>
</div>
areavalueNetworknetwork_filterRetrieves a representation of the network filter.
<div class="paragraph">
<p>Retrieves a representation of the network filter.</p>
</div>
getnetwork_filterfalsefalsenetwork_filterareavalueStoragevm_disksadddisktruetruedisklistdisksfalsefalsedisk[]Sets the maximum number of disks to return. If not specified all the disks are returned.
<div class="paragraph">
<p>Sets the maximum number of disks to return. If not specified all the disks are returned.</p>
</div>
maxtruetrueintegerdiskvm_diskidfalsefalsestringThis service manages the set of disks attached to a virtual machine. Each attached disk is represented by a
<<types/disk_attachment,DiskAttachment>>, containing the bootable flag, the disk interface and the reference to
the disk.
<div class="paragraph">
<p>This service manages the set of disks attached to a virtual machine. Each attached disk is represented by a
<a href="#types/disk_attachment">DiskAttachment</a>, containing the bootable flag, the disk interface and the reference to
the disk.</p>
</div>
disk_attachmentsAdds a new disk attachment to the virtual machine. The `attachment` parameter can contain just a reference, if
the disk already exists:
[source,xml]
----
<disk_attachment>
<bootable>true</bootable>
<interface>ide</interface>
<active>true</active>
<disk id="123"/>
</disk_attachment>
----
Or it can contain the complete representation of the disk, if the disk doesn't exist yet:
[source,xml]
----
<disk_attachment>
<bootable>true</bootable>
<interface>ide</interface>
<active>true</active>
<disk>
<name>mydisk</name>
<provisioned_size>1024</provisioned_size>
...
</disk>
</disk_attachment>
----
In this case the disk will be created and then attached to the virtual machine.
In both cases, use the following URL for a virtual machine with an id `345`:
[source]
----
POST /ovirt-engine/api/vms/345/diskattachments
----
IMPORTANT: The server accepts requests that don't contain the `active` attribute, but the effect is
undefined. In some cases the disk will be automatically activated and in other cases it won't. To
avoid issues it is strongly recommended to always include the `active` attribute with the desired
value.
<div class="paragraph">
<p>Adds a new disk attachment to the virtual machine. The <code>attachment</code> parameter can contain just a reference, if
the disk already exists:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><disk_attachment>
<bootable>true</bootable>
<interface>ide</interface>
<active>true</active>
<disk id="123"/>
</disk_attachment></code></pre>
</div>
</div>
<div class="paragraph">
<p>Or it can contain the complete representation of the disk, if the disk doesn’t exist yet:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><disk_attachment>
<bootable>true</bootable>
<interface>ide</interface>
<active>true</active>
<disk>
<name>mydisk</name>
<provisioned_size>1024</provisioned_size>
...
</disk>
</disk_attachment></code></pre>
</div>
</div>
<div class="paragraph">
<p>In this case the disk will be created and then attached to the virtual machine.</p>
</div>
<div class="paragraph">
<p>In both cases, use the following URL for a virtual machine with an id <code>345</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/345/diskattachments</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The server accepts requests that don’t contain the <code>active</code> 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 <code>active</code> attribute with the desired
value.
</td>
</tr>
</table>
</div>
authorvalueIdan Shaby <ishaby@redhat.com>datevalue15 Sep 2016statusvalueaddedaddattachmenttruetruedisk_attachmentList the disk that are attached to the virtual machine.
<div class="paragraph">
<p>List the disk that are attached to the virtual machine.</p>
</div>
listattachmentsfalsefalsedisk_attachment[]Reference to the service that manages a specific attachment.
<div class="paragraph">
<p>Reference to the service that manages a specific attachment.</p>
</div>
attachmentdisk_attachmentidfalsefalsestringareavalueVirtualizationhost_hookslisthooksfalsefalsehook[]Sets the maximum number of hooks to return. If not specified all the hooks are returned.
<div class="paragraph">
<p>Sets the maximum number of hooks to return. If not specified all the hooks are returned.</p>
</div>
maxtruetrueintegerhookhost_hookidfalsefalsestringareavalueStoragestorage_domainsAdds a new storage domain.
Creation of a new <<types/storage_domain,StorageDomain>> requires the `name`, `type`, `host` and `storage`
attributes. Identify the `host` attribute with the `id` or `name` attributes. In oVirt 3.6 and later you can
enable the wipe after delete option by default on the storage domain. To configure this, specify
`wipe_after_delete` in the POST request. This option can be edited after the domain is created, but doing so will
not change the wipe after delete property of disks that already exist.
To add a new storage domain with specified `name`, `type`, `storage.type`, `storage.address` and `storage.path`
and by using a host with an id `123`, send a request as follows:
[source]
----
POST /ovirt-engine/api/storagedomains
----
With a request body as follows:
[source,xml]
----
<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:
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Adds a new storage domain.</p>
</div>
<div class="paragraph">
<p>Creation of a new <a href="#types/storage_domain">StorageDomain</a> requires the <code>name</code>, <code>type</code>, <code>host</code> and <code>storage</code>
attributes. Identify the <code>host</code> attribute with the <code>id</code> or <code>name</code> attributes. In oVirt 3.6 and later you can
enable the wipe after delete option by default on the storage domain. To configure this, specify
<code>wipe_after_delete</code> 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.</p>
</div>
<div class="paragraph">
<p>To add a new storage domain with specified <code>name</code>, <code>type</code>, <code>storage.type</code>, <code>storage.address</code> and <code>storage.path</code>
and by using a host with an id <code>123</code>, send a request as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/storagedomains</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>To create a new NFS ISO storage domain send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueIdan Shaby <ishaby@redhat.com>Tal Nisan <tnisan@redhat.com>datevalue14 Sep 2016statusvalueaddedaddstorage_domaintruetruestorage_domainliststorage_domainsfalsefalsestorage_domain[]Sets the maximum number of storage domains to return. If not specified all the storage domains are returned.
<div class="paragraph">
<p>Sets the maximum number of storage domains to return. If not specified all the storage domains are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned storage domains.
<div class="paragraph">
<p>A query string used to restrict the returned storage domains.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanstorage_domainstorage_domainidfalsefalsestringareavalueNetworknetwork_labelgetlabelfalsefalsenetwork_labelRemoves a label from a logical network.
For example, to remove the label `exemplary` from a logical network having id `123` send the following request:
[source]
----
DELETE /ovirt-engine/api/networks/123/labels/exemplary
----
<div class="paragraph">
<p>Removes a label from a logical network.</p>
</div>
<div class="paragraph">
<p>For example, to remove the label <code>exemplary</code> from a logical network having id <code>123</code> send the following request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/networks/123/labels/exemplary</code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueVirtualizationinstance_typesaddinstance_typetruetrueinstance_typelistinstance_typefalsefalseinstance_type[]Sets the maximum number of instance types to return. If not specified all the instance types are returned.
<div class="paragraph">
<p>Sets the maximum number of instance types to return. If not specified all the instance types are returned.</p>
</div>
maxtruetrueintegerinstance_typeinstance_typeidfalsefalsestringareavalueStoragestorage_domain_server_connectionsaddconnectiontruetruestorage_connectionlistconnectionsfalsefalsestorage_connection[]Sets the maximum number of connections to return. If not specified all the connections are returned.
<div class="paragraph">
<p>Sets the maximum number of connections to return. If not specified all the connections are returned.</p>
</div>
maxtruetrueintegerconnectionstorage_domain_server_connectionidfalsefalsestringareavalueStorageiscsi_bondgetbondfalsefalseiscsi_bondUpdates 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:
[source]
----
PUT /ovirt-engine/api/datacenters/123/iscsibonds/1234
----
The request body should look like this:
[source,xml]
----
<iscsi_bond>
<name>mybond</name>
<description>My iSCSI bond</description>
</iscsi_bond>
----
<div class="paragraph">
<p>Updates an iSCSI bond.</p>
</div>
<div class="paragraph">
<p>Updating of an iSCSI bond can be done on the <code>name</code> and the <code>description</code> attributes only. For example, to
update the iSCSI bond <code>456</code> of data center <code>123</code>, send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/datacenters/123/iscsibonds/1234</code></pre>
</div>
</div>
<div class="paragraph">
<p>The request body should look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><iscsi_bond>
<name>mybond</name>
<description>My iSCSI bond</description>
</iscsi_bond></code></pre>
</div>
</div>
authorvalueMaor Lipchuk <mlipchuk@redhat.com>datevalue14 Sep 2016statusvalueaddedupdatebondtruetrueiscsi_bondIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves of an exisitng iSCSI bond.
For example, to remove the iSCSI bond `456` send a request like this:
[source]
----
DELETE /ovirt-engine/api/datacenters/123/iscsibonds/456
----
<div class="paragraph">
<p>Removes of an exisitng iSCSI bond.</p>
</div>
<div class="paragraph">
<p>For example, to remove the iSCSI bond <code>456</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/datacenters/123/iscsibonds/456</code></pre>
</div>
</div>
authorvalueMaor Lipchuk <mlipchuk@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleannetworksnetworksstorage_server_connectionsstorage_server_connectionsThis service manages the attachment of a disk to a template.
<div class="paragraph">
<p>This service manages the attachment of a disk to a template.</p>
</div>
areavalueStorageauthorvalueTal Nisan <tnisan@redhat.com>datevalue7 Jul 2016statusvalueaddedtemplate_disk_attachmentReturns the details of the attachment.
<div class="paragraph">
<p>Returns the details of the attachment.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue7 Jul 2016statusvalueaddedgetattachmentfalsefalsedisk_attachmentRemoves 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).
[source]
----
DELETE /ovirt-engine/api/templates/{template:id}/diskattachments/{attachment:id}?storage_domain=072fbaa1-08f3-4a40-9f34-a5ca22dd1d74
----
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/templates/{template:id}/diskattachments/{attachment:id}?storage_domain=072fbaa1-08f3-4a40-9f34-a5ca22dd1d74</code></pre>
</div>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue7 Jul 2016statusvalueaddedremoveSpecifies the identifier of the storage domain the image to be removed resides on.
<div class="paragraph">
<p>Specifies the identifier of the storage domain the image to be removed resides on.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue7 Jul 2016statusvalueaddedstorage_domaintruetruestringforcetruetruebooleanareavalueStoragehost_storageliststoragesfalsefalsehost_storage[]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 :
[source,xml]
----
<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 :
[source,xml]
----
<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>
----
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>The default is <code>true</code> for backward compatibility.</p>
</div>
<div class="paragraph">
<p>Here an example with the LUN status :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>Here an example without the LUN status :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
report_statustruetruebooleanstoragestorageidfalsefalsestringareavalueSLAweightgetweightfalsefalseweightIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueSLAvm_numa_nodesCreates a new virtual NUMA node for the virtual machine.
An example of creating a NUMA node:
[source]
----
POST /ovirt-engine/api/vms/c7ecd2dc/numanodes
Accept: application/xml
Content-type: application/xml
----
The request body can contain the following:
[source,xml]
----
<vm_numa_node>
<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>1024</memory>
</vm_numa_node>
----
<div class="paragraph">
<p>Creates a new virtual NUMA node for the virtual machine.</p>
</div>
<div class="paragraph">
<p>An example of creating a NUMA node:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/c7ecd2dc/numanodes
Accept: application/xml
Content-type: application/xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>The request body can contain the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm_numa_node>
<cpu>
<cores>
<core>
<index>0</index>
</core>
</cores>
</cpu>
<index>0</index>
<memory>1024</memory>
</vm_numa_node></code></pre>
</div>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedaddnodetruetruevirtual_numa_nodeLists virtual NUMA nodes of a virtual machine.
<div class="paragraph">
<p>Lists virtual NUMA nodes of a virtual machine.</p>
</div>
authorvalueAndrej Krejcir <akrejcir@redhat.com>datevalue14 Sep 2016statusvalueaddedlistnodesfalsefalsevirtual_numa_node[]Sets the maximum number of nodes to return. If not specified all the nodes are returned.
<div class="paragraph">
<p>Sets the maximum number of nodes to return. If not specified all the nodes are returned.</p>
</div>
maxtruetrueintegernodevm_numa_nodeidfalsefalsestringareavalueVirtualizationtemplate_watchdogsaddwatchdogtruetruewatchdoglistwatchdogsfalsefalsewatchdog[]Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.
<div class="paragraph">
<p>Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.</p>
</div>
maxtruetrueintegerwatchdogtemplate_watchdogidfalsefalsestringSince 4.0 it is possible to have a customized network filter to each 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 <<services/network_filters,NetworkFilters>>.
The basic POST command of adding a new VNIC profile is as follows:
[source]
----
http://{engine_ip_address}:8080/ovirt-engine/api/networks/{network_id}/vnicprofiles
----
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:
[source,xml]
----
<vnic_profile>
<name>use_default_network_filter</name>
<network id="00000000-0000-0000-0000-000000000009"/>
</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:
[source,xml]
----
<vnic_profile>
<name>no_network_filter</name>
<network id="00000000-0000-0000-0000-000000000009"/>
<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:
[source,xml]
----
<vnic_profile>
<name>user_choice_network_filter</name>
<network id="00000000-0000-0000-0000-000000000009"/>
<network_filter id= "0000001b-001b-001b-001b-0000000001d5"/>
</vnic_profile>
----
<div class="paragraph">
<p>Since 4.0 it is possible to have a customized network filter to each 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 <a href="#services/network_filters">NetworkFilters</a>.</p>
</div>
<div class="paragraph">
<p>The basic POST command of adding a new VNIC profile is as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>http://{engine_ip_address}:8080/ovirt-engine/api/networks/{network_id}/vnicprofiles</code></pre>
</div>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vnic_profile>
<name>use_default_network_filter</name>
<network id="00000000-0000-0000-0000-000000000009"/>
</vnic_profile></code></pre>
</div>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vnic_profile>
<name>no_network_filter</name>
<network id="00000000-0000-0000-0000-000000000009"/>
<network_filter/>
</vnic_profile></code></pre>
</div>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vnic_profile>
<name>user_choice_network_filter</name>
<network id="00000000-0000-0000-0000-000000000009"/>
<network_filter id= "0000001b-001b-001b-001b-0000000001d5"/>
</vnic_profile></code></pre>
</div>
</div>
areavalueNetworkvnic_profilegetprofilefalsefalsevnic_profileupdateprofiletruetruevnic_profileIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanpermissionsassigned_permissionsareavalueInfrastructurepermitgetpermitfalsefalsepermitremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueVirtualizationdata_centergetdata_centerfalsefalsedata_centerIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanUpdates 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:
[source]
----
PUT /ovirt-engine/api/datacenters/123
----
With a request body like this:
[source,xml]
----
<data_center>
<name>myupdatedname</name>
<description>An updated description for the data center</description>
</data_center>
----
<div class="paragraph">
<p>Updates the data center.</p>
</div>
<div class="paragraph">
<p>The <code>name</code>, <code>description</code>, <code>storage_type</code>, <code>version</code>, <code>storage_format</code> and <code>mac_pool</code> elements are updatable
post-creation. For example, to change the name and description of data center <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/datacenters/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><data_center>
<name>myupdatedname</name>
<description>An updated description for the data center</description>
</data_center></code></pre>
</div>
</div>
authorvalueShmuel Melamud <smelamud@redhat.com>datevalue14 Sep 2016statusvalueaddedupdateThe data center that is being updated.
<div class="paragraph">
<p>The data center that is being updated.</p>
</div>
authorvalueShmuel Melamud <smelamud@redhat.com>datevalue14 Sep 2016statusvalueaddeddata_centertruetruedata_centerIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves the data center.
[source]
----
DELETE /ovirt-engine/api/datacenters/123
----
Without any special parameters, the storage domains attached to the data center are detached and then removed
from the storage. If something fails when performing this operation, for example if there is no host available to
remove the storage domains from the storage, the complete operation will fail.
If the `force` parameter is `true` then the operation will always succeed, even if something fails while removing
one storage domain, for example. The failure is just ignored and the data center is removed from the database
anyway.
<div class="paragraph">
<p>Removes the data center.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/datacenters/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>If the <code>force</code> parameter is <code>true</code> 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.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue15 Aug 2016statusvalueaddedsincevalue4.0.0removeIndicates 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`.
<div class="paragraph">
<p>Indicates if the operation should succeed, and the storage domain removed from the database, even if
something fails during the operation.</p>
</div>
<div class="paragraph">
<p>This parameter is optional, and the default value is <code>false</code>.</p>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue15 Aug 2016statusvalueaddedsincevalue4.0.4forcetruetruebooleanIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanAttach and detach storage domains to and from a data center.
For attaching a single storage domain we should use the folowing POST request:
[source]
----
POST /ovirt-engine/api/datacenters/123/storagedomains
----
With a request body like this:
[source,xml]
----
<storage_domain>
<name>data1</name>
</storage_domain>
----
For detaching a single storage domain we should use the folowing DELETE request:
[source]
----
DELETE /ovirt-engine/api/datacenters/123/storagedomains/123
----
<div class="paragraph">
<p>Attach and detach storage domains to and from a data center.</p>
</div>
<div class="paragraph">
<p>For attaching a single storage domain we should use the folowing POST request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/datacenters/123/storagedomains</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_domain>
<name>data1</name>
</storage_domain></code></pre>
</div>
</div>
<div class="paragraph">
<p>For detaching a single storage domain we should use the folowing DELETE request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/datacenters/123/storagedomains/123</code></pre>
</div>
</div>
authorvalueMaor Lipchuk <mlipchuk@redhat.com>datevalue14 Sep 2016statusvalueaddedstorage_domainsattached_storage_domainsclustersclustersReturns a reference to the service, that manages the networks, that are associated with the data center.
<div class="paragraph">
<p>Returns a reference to the service, that manages the networks, that are associated with the data center.</p>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue24 Oct 2016statusvalueaddednetworksnetworkspermissionsassigned_permissionsquotasquotasqossqossiscsi_bondsiscsi_bondsareavalueInfrastructurestatisticsliststatisticsfalsefalsestatistic[]Sets the maximum number of statistics to return. If not specified all the statistics are returned.
<div class="paragraph">
<p>Sets the maximum number of statistics to return. If not specified all the statistics are returned.</p>
</div>
maxtruetrueintegerstatisticstatisticidfalsefalsestringareavalueSLAscheduling_policy_unitslistunitsfalsefalsescheduling_policy_unit[]Sets the maximum number of policy units to return. If not specified all the policy units are returned.
<div class="paragraph">
<p>Sets the maximum number of policy units to return. If not specified all the policy units are returned.</p>
</div>
maxtruetrueintegerIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanunitscheduling_policy_unitidfalsefalsestringareavalueStoragetemplate_diskcopyIndicates if the copy should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the copy should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanexportIndicates if the export should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the export should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleangetdiskfalsefalsediskremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis service represents list of vms that have a specific
label when accessed through the affinitylabels/vms
subcollection.
<div class="paragraph">
<p>This service represents list of vms that have a specific
label when accessed through the affinitylabels/vms
subcollection.</p>
</div>
affinity_label_vmsAdd a label to a vm.
<div class="paragraph">
<p>Add a label to a vm.</p>
</div>
addvmtruetruevmList all vms with the label.
<div class="paragraph">
<p>List all vms with the label.</p>
</div>
listvmsfalsefalsevm[]A link to the specific label-vm assignment to
allow label removal.
<div class="paragraph">
<p>A link to the specific label-vm assignment to
allow label removal.</p>
</div>
vmaffinity_label_vmidfalsefalsestringareavalueStoragecopyablecopyIndicates if the copy should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the copy should be performed asynchronously.</p>
</div>
asynctruetruebooleanManages the affinity labels available in the system.
<div class="paragraph">
<p>Manages the affinity labels available in the system.</p>
</div>
affinity_labelsCreates a new label. The label is automatically attached
to all entities mentioned in the vms or hosts lists.
<div class="paragraph">
<p>Creates a new label. The label is automatically attached
to all entities mentioned in the vms or hosts lists.</p>
</div>
addlabeltruetrueaffinity_labelLists all labels present in the system.
<div class="paragraph">
<p>Lists all labels present in the system.</p>
</div>
listlabelsfalsefalseaffinity_label[]Sets the maximum number of labels to return. If not specified all the labels are returned.
<div class="paragraph">
<p>Sets the maximum number of labels to return. If not specified all the labels are returned.</p>
</div>
maxtruetrueintegerLink to a single label details.
<div class="paragraph">
<p>Link to a single label details.</p>
</div>
labelaffinity_labelidfalsefalsestringareavalueVirtualizationvm_graphics_consoleGets the configuration of the graphics console.
<div class="paragraph">
<p>Gets the configuration of the graphics console.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue8 Jul 2016statusvalueaddedgetconsolefalsefalsegraphics_consoleUse the following query to obtain the current run-time configuration of the graphics console.
[source]
----
GET /ovit-engine/api/vms/{vm:id}/graphicsconsoles/{console:id}?current=true
----
The default value is `false`.
<div class="paragraph">
<p>Use the following query to obtain the current run-time configuration of the graphics console.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovit-engine/api/vms/{vm:id}/graphicsconsoles/{console:id}?current=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>The default value is <code>false</code>.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue8 Jul 2016statusvalueaddedcurrenttruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanproxy_ticketproxy_ticketfalsefalseproxy_ticketIndicates if the generation of the ticket should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the generation of the ticket should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis service represents a host that has a specific
label when accessed through the affinitylabels/hosts
subcollection.
<div class="paragraph">
<p>This service represents a host that has a specific
label when accessed through the affinitylabels/hosts
subcollection.</p>
</div>
affinity_label_hostRemove a label from a host.
<div class="paragraph">
<p>Remove a label from a host.</p>
</div>
removeRetrieves details about a host that has this label assigned.
<div class="paragraph">
<p>Retrieves details about a host that has this label assigned.</p>
</div>
gethostfalsefalsehostareavalueInfrastructureassigned_taggettagfalsefalsetagremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanManages a single disk.
<div class="paragraph">
<p>Manages a single disk.</p>
</div>
areavalueStorageauthorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddeddiskThis operation copies a disk to the specified storage domain.
For example, copy of a disk can be facilitated using the following request:
[source]
----
POST /ovirt-engine/api/disks/123/copy
----
With a request body like this:
[source,xml]
----
<action>
<storage_domain id="456"/>
<disk>
<name>mydisk</name>
</disk>
</action>
----
<div class="paragraph">
<p>This operation copies a disk to the specified storage domain.</p>
</div>
<div class="paragraph">
<p>For example, copy of a disk can be facilitated using the following request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/disks/123/copy</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<storage_domain id="456"/>
<disk>
<name>mydisk</name>
</disk>
</action></code></pre>
</div>
</div>
authorvalueLiron Aravot <laravot@redhat.com>datevalue14 Sep 2016statusvalueaddedcopydisktruetruediskstorage_domaintruetruestorage_domainIndicates if the copy should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the copy should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanexportstorage_domaintruetruestorage_domainIndicates if the export should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the export should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleangetdiskfalsefalsediskMoves 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:
[source]
----
POST /ovirt-engine/api/disks/123/move
----
With the following request body:
[source,xml]
----
<action>
<storage_domain id="456"/>
</action>
----
<div class="paragraph">
<p>Moves a disk to another storage domain.</p>
</div>
<div class="paragraph">
<p>For example, to move the disk with identifier <code>123</code> to a storage domain with identifier <code>456</code> send the following
request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/disks/123/move</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the following request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<storage_domain id="456"/>
</action></code></pre>
</div>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue14 Sep 2016statusvalueaddedmovestorage_domaintruetruestorage_domainIndicates if the move should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the move should be performed asynchronously.</p>
</div>
asynctruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanstatisticsstatisticspermissionsassigned_permissionsThis service manages the set of disks attached to a template. Each attached disk is represented by a
<<types/disk_attachment,DiskAttachment>>.
<div class="paragraph">
<p>This service manages the set of disks attached to a template. Each attached disk is represented by a
<a href="#types/disk_attachment">DiskAttachment</a>.</p>
</div>
areavalueStorageauthorvalueTal Nisan <tnisan@redhat.com>datevalue7 Jul 2016statusvalueaddedtemplate_disk_attachmentsList the disks that are attached to the template.
<div class="paragraph">
<p>List the disks that are attached to the template.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue7 Jul 2016statusvalueaddedlistattachmentsfalsefalsedisk_attachment[]Reference to the service that manages a specific attachment.
<div class="paragraph">
<p>Reference to the service that manages a specific attachment.</p>
</div>
authorvalueTal Nisan <tnisan@redhat.com>datevalue7 Jul 2016statusvalueaddedattachmenttemplate_disk_attachmentidfalsefalsestringareavalueStoragestorage_domain_content_diskslistdisksfalsefalsedisk[]Sets the maximum number of disks to return. If not specified all the disks are returned.
<div class="paragraph">
<p>Sets the maximum number of disks to return. If not specified all the disks are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned disks.
<div class="paragraph">
<p>A query string used to restrict the returned disks.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleandiskstorage_domain_content_diskidfalsefalsestringareavalueVirtualizationhost_deviceslistdevicesfalsefalsehost_device[]Sets the maximum number of devices to return. If not specified all the devices are returned.
<div class="paragraph">
<p>Sets the maximum number of devices to return. If not specified all the devices are returned.</p>
</div>
maxtruetrueintegerdevicehost_deviceidfalsefalsestringareavalueNetworkassigned_networksaddnetworktruetruenetworklistnetworksfalsefalsenetwork[]Sets the maximum number of networks to return. If not specified all the networks are returned.
<div class="paragraph">
<p>Sets the maximum number of networks to return. If not specified all the networks are returned.</p>
</div>
maxtruetrueintegernetworkassigned_networkidfalsefalsestringareavalueStoragestoragegetstoragefalsefalsehost_storageIndicates 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 :
[source,xml]
----
<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 :
[source,xml]
----
<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>
----
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>The default is <code>true</code> for backward compatibility.</p>
</div>
<div class="paragraph">
<p>Here an example with the LUN status :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>Here an example without the LUN status :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
report_statustruetruebooleanareavalueNetworkunmanaged_networkgetnetworkfalsefalseunmanaged_networkremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueSLAquotaRetrieves a quota.
An example of retrieving a quota:
[source]
----
GET /ovirt-engine/api/datacenters/123/quotas/456
----
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Retrieves a quota.</p>
</div>
<div class="paragraph">
<p>An example of retrieving a quota:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/datacenters/123/quotas/456</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueRoman Mohr <rmohr@redhat.com>datevalue14 Sep 2016statusvalueaddedgetquotafalsefalsequotaUpdates a quota.
An example of updating a quota:
[source]
----
PUT /ovirt-engine/api/datacenters/123/quotas/456
----
[source,xml]
----
<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>
----
<div class="paragraph">
<p>Updates a quota.</p>
</div>
<div class="paragraph">
<p>An example of updating a quota:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/datacenters/123/quotas/456</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
authorvalueRoman Mohr <rmohr@redhat.com>datevalue14 Sep 2016statusvalueaddedupdatequotatruetruequotaIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanDelete a quota.
An example of deleting a quota:
[source]
----
DELETE /ovirt-engine/api/datacenters/123-456/quotas/654-321
-0472718ab224 HTTP/1.1
Accept: application/xml
Content-type: application/xml
----
<div class="paragraph">
<p>Delete a quota.</p>
</div>
<div class="paragraph">
<p>An example of deleting a quota:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/datacenters/123-456/quotas/654-321
-0472718ab224 HTTP/1.1
Accept: application/xml
Content-type: application/xml</code></pre>
</div>
</div>
authorvalueRoman Mohr <rmohr@redhat.com>datevalue14 Sep 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanquota_storage_limitsquota_storage_limitsquota_cluster_limitsquota_cluster_limitspermissionsassigned_permissionsareavalueStoragesnapshot_diskgetdiskfalsefalsediskareavalueSLAqossaddqostruetrueqoslistqossfalsefalseqos[]Sets the maximum number of QoS descriptors to return. If not specified all the descriptors are returned.
<div class="paragraph">
<p>Sets the maximum number of QoS descriptors to return. If not specified all the descriptors are returned.</p>
</div>
maxtruetrueintegerqosqosidfalsefalsestringareavalueNetworknetworkgetnetworkfalsefalsenetworkUpdates a logical network.
The `name`, `description`, `ip`, `vlan`, `stp` and `display` attributes can be updated.
For example, to update the description of the logcial network `123` send a request like this:
[source]
----
PUT /ovirt-engine/api/networks/123
----
With a request body like this:
[source,xml]
----
<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:
[source]
----
PUT /ovirt-engine/api/datacenters/123/networks/456
----
With a request body like this:
[source,xml]
----
<network>
<mtu>1500</mtu>
</network>
----
<div class="paragraph">
<p>Updates a logical network.</p>
</div>
<div class="paragraph">
<p>The <code>name</code>, <code>description</code>, <code>ip</code>, <code>vlan</code>, <code>stp</code> and <code>display</code> attributes can be updated.</p>
</div>
<div class="paragraph">
<p>For example, to update the description of the logcial network <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/networks/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><network>
<description>My updated description</description>
</network></code></pre>
</div>
</div>
<div class="paragraph">
<p>The maximum transmission unit of a network is set using a PUT request to
specify the integer value of the <code>mtu</code> attribute.</p>
</div>
<div class="paragraph">
<p>For example, to set the maximum transmission unit send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/datacenters/123/networks/456</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><network>
<mtu>1500</mtu>
</network></code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue24 Oct 2016statusvalueaddedupdatenetworktruetruenetworkIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves 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:
[source]
----
DELETE /ovirt-engine/api/networks/123
----
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:
[source]
----
DELETE /ovirt-engine/api/datacenters/123/networks/456
----
<div class="paragraph">
<p>Removes a logical network, or the association of a logical network to a data center.</p>
</div>
<div class="paragraph">
<p>For example, to remove the logical network <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/networks/123</code></pre>
</div>
</div>
<div class="paragraph">
<p>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
<code>456</code> of data center <code>123</code>.</p>
</div>
<div class="paragraph">
<p>For example, to remove the association of network <code>456</code> to data center <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>DELETE /ovirt-engine/api/datacenters/123/networks/456</code></pre>
</div>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>datevalue24 Oct 2016statusvalueaddedremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanpermissionsassigned_permissionsvnic_profilesassigned_vnic_profilesnetwork_labelsnetwork_labelsareavalueVirtualizationinstance_typegetinstance_typefalsefalseinstance_typeupdateinstance_typetruetrueinstance_typeIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleannicsinstance_type_nicswatchdogsinstance_type_watchdogsgraphics_consolesgraphics_consolesareavalueNetworkvirtual_function_allowed_networksaddnetworktruetruenetworklistnetworksfalsefalsenetwork[]Sets the maximum number of networks to return. If not specified all the networks are returned.
<div class="paragraph">
<p>Sets the maximum number of networks to return. If not specified all the networks are returned.</p>
</div>
maxtruetrueintegernetworkvirtual_function_allowed_networkidfalsefalsestringareavalueVirtualizationhost_hookgethookfalsefalsehookareavalueStorageimageslistimagesfalsefalseimage[]Sets the maximum number of images to return. If not specified all the images are returned.
<div class="paragraph">
<p>Sets the maximum number of images to return. If not specified all the images are returned.</p>
</div>
maxtruetrueintegerimageimageidfalsefalsestringareavalueStoragesnapshot_cdromslistcdromsfalsefalsecdrom[]Sets the maximum number of CDROMS to return. If not specified all the CDROMS are returned.
<div class="paragraph">
<p>Sets the maximum number of CDROMS to return. If not specified all the CDROMS are returned.</p>
</div>
maxtruetrueintegercdromsnapshot_cdromidfalsefalsestringareavalueSLAbalancesaddbalancetruetruebalancelistbalancesfalsefalsebalance[]Sets the maximum number of balances to return. If not specified all the balances are returned.
<div class="paragraph">
<p>Sets the maximum number of balances to return. If not specified all the balances are returned.</p>
</div>
maxtruetrueintegerIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanbalancebalanceidfalsefalsestringareavalueVirtualizationtemplate_cdromgetcdromfalsefalsecdromareavalueStoragemoveablemoveIndicates if the move should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the move should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueVirtualizationcpu_profilegetprofilefalsefalsecpu_profileupdateprofiletruetruecpu_profileIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanpermissionsassigned_permissionsareavalueInfrastructuremeasurablestatisticsstatisticsareavalueStoragestorage_server_connection_extensiongetextensionfalsefalsestorage_connection_extensionUpdate a storage server connection extension for the given host.
To update the storage connection `456` of host `123` send a request like this:
[source]
----
PUT /ovirt-engine/api/hosts/123/storageconnectionextensions/456
----
With a request body like this:
[source,xml]
----
<storage_connection_extension>
<target>iqn.2016-01.com.example:mytarget</target>
<username>myuser</username>
<password>mypassword</password>
</storage_connection_extension>
----
<div class="paragraph">
<p>Update a storage server connection extension for the given host.</p>
</div>
<div class="paragraph">
<p>To update the storage connection <code>456</code> of host <code>123</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>PUT /ovirt-engine/api/hosts/123/storageconnectionextensions/456</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_connection_extension>
<target>iqn.2016-01.com.example:mytarget</target>
<username>myuser</username>
<password>mypassword</password>
</storage_connection_extension></code></pre>
</div>
</div>
authorvalueTal Nisan <tnisanredhat.com>datevalue15 Sep 2016statusvalueaddedupdateextensiontruetruestorage_connection_extensionIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanProvides 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. For example, to find what CPU types are supported by level 3.6 the you can send
a request like this:
[source]
----
GET /ovirt-engine/api/clusterlevels/3.6
----
That will return a <<types/cluster_level, ClusterLevel>> object containing the supported CPU types, and other
information describing the cluster level:
[source,xml]
----
<cluster_level id="3.6" href="/ovirt-engine/api/clusterlevel/3.6">
<cpu_types>
<cpu_type>
<name>Intel Conroe Family</name>
<level>3</level>
<architecture>x86_64</architecture>
</cpu_type>
...
</cpu_types>
...
</cluster_level>
----
<div class="paragraph">
<p>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. For example, to find what CPU types are supported by level 3.6 the you can send
a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/clusterlevels/3.6</code></pre>
</div>
</div>
<div class="paragraph">
<p>That will return a <a href="#types/cluster_level">ClusterLevel</a> object containing the supported CPU types, and other
information describing the cluster level:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cluster_level id="3.6" href="/ovirt-engine/api/clusterlevel/3.6">
<cpu_types>
<cpu_type>
<name>Intel Conroe Family</name>
<level>3</level>
<architecture>x86_64</architecture>
</cpu_type>
...
</cpu_types>
...
</cluster_level></code></pre>
</div>
</div>
cluster_levelsLists the cluster levels supported by the system.
<div class="paragraph">
<p>Lists the cluster levels supported by the system.</p>
</div>
listlevelsfalsefalsecluster_level[]Reference to the service that provides information about an specific cluster level.
<div class="paragraph">
<p>Reference to the service that provides information about an specific cluster level.</p>
</div>
levelcluster_levelidfalsefalsestringareavalueVirtualizationgraphics_consoleGets the configuration of the graphics console.
<div class="paragraph">
<p>Gets the configuration of the graphics console.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue8 Jul 2016statusvalueaddedgetconsolefalsefalsegraphics_consoleUse the following query to obtain the current run-time configuration of the graphics console.
[source]
----
GET /ovit-engine/api/vms/{vm:id}/graphicsconsoles/{console:id}?current=true
----
The default value is `false`.
<div class="paragraph">
<p>Use the following query to obtain the current run-time configuration of the graphics console.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovit-engine/api/vms/{vm:id}/graphicsconsoles/{console:id}?current=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>The default value is <code>false</code>.</p>
</div>
authorvalueTomas Jelinek <tjelinek@redhat.com>datevalue8 Jul 2016statusvalueaddedcurrenttruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueNetworkvm_nicsAdds a NIC to the virtual machine.
The following example adds a network interface named `mynic` using `virtio` and the `ovirtmgmt` network to the
virtual machine.
[source]
----
POST /ovirt-engine/api/vms/123/nics
----
[source,xml]
----
<nic>
<interface>virtio</interface>
<name>mynic</name>
<network>
<name>ovirtmgmt</name>
</network>
</nic>
----
The following example sends that request using `curl`:
[source,bash]
----
curl \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \
--cacert /etc/pki/ovirt-engine/ca.pem \
--data '
<nic>
<name>mynic</name>
<network>
<name>ovirtmgmt</name>
</network>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/123/nics
----
[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
====
<div class="paragraph">
<p>Adds a NIC to the virtual machine.</p>
</div>
<div class="paragraph">
<p>The following example adds a network interface named <code>mynic</code> using <code>virtio</code> and the <code>ovirtmgmt</code> network to the
virtual machine.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/vms/123/nics</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><nic>
<interface>virtio</interface>
<name>mynic</name>
<network>
<name>ovirtmgmt</name>
</network>
</nic></code></pre>
</div>
</div>
<div class="paragraph">
<p>The following example sends that request using <code>curl</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">curl \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--user "admin@internal:mypassword" \
--cacert /etc/pki/ovirt-engine/ca.pem \
--data '
<nic>
<name>mynic</name>
<network>
<name>ovirtmgmt</name>
</network>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/123/nics</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
<div class="paragraph">
<p>The hotplugging feature only supports virtual machine operating systems with hotplugging operations.
Example operating systems include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Red Hat Enterprise Linux 6</p>
</li>
<li>
<p>Red Hat Enterprise Linux 5</p>
</li>
<li>
<p>Windows Server 2008 and</p>
</li>
<li>
<p>Windows Server 2003</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
authorvalueMartin Mucha <mmucha@redhat.com>Vinzenz Feenstra <vfeenstr@redhat.com>datevalue14 Sep 2016statusvalueaddedaddnictruetrueniclistnicsfalsefalsenic[]Sets the maximum number of NICs to return. If not specified all the NICs are returned.
<div class="paragraph">
<p>Sets the maximum number of NICs to return. If not specified all the NICs are returned.</p>
</div>
maxtruetrueintegernicvm_nicidfalsefalsestringareavalueVirtualizationvm_reported_deviceslistreported_devicefalsefalsereported_device[]Sets the maximum number of devices to return. If not specified all the devices are returned.
<div class="paragraph">
<p>Sets the maximum number of devices to return. If not specified all the devices are returned.</p>
</div>
maxtruetrueintegerreported_devicevm_reported_deviceidfalsefalsestringareavalueSLAbalancegetbalancefalsefalsebalanceIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueInfrastructurepermitsAdds a permit to the set aggregated by parent role. The permit must be one retrieved from the capabilities
resource.
<div class="paragraph">
<p>Adds a permit to the set aggregated by parent role. The permit must be one retrieved from the capabilities
resource.</p>
</div>
addThe permit to add.
<div class="paragraph">
<p>The permit to add.</p>
</div>
permittruetruepermitlistpermitsfalsefalsepermit[]Sets the maximum number of permits to return. If not specified all the permits are returned.
<div class="paragraph">
<p>Sets the maximum number of permits to return. If not specified all the permits are returned.</p>
</div>
maxtruetrueintegerSub-resource locator method, returns individual permit resource on which the remainder of the URI is dispatched.
<div class="paragraph">
<p>Sub-resource locator method, returns individual permit resource on which the remainder of the URI is dispatched.</p>
</div>
permitpermitidfalsefalsestringareavalueStoragestorage_domain_templateslisttemplatesfalsefalsetemplate[]Sets the maximum number of templates to return. If not specified all the templates are returned.
<div class="paragraph">
<p>Sets the maximum number of templates to return. If not specified all the templates are returned.</p>
</div>
maxtruetrueintegertemplatestorage_domain_templateidfalsefalsestringareavalueInfrastructuresystemReturns basic information describing the API, like the product name, the version number and a summary of the
number of relevant objects.
[source]
----
GET /ovirt-engine/api
----
We get following response:
[source,xml]
----
<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`.
<div class="paragraph">
<p>Returns basic information describing the API, like the product name, the version number and a summary of the
number of relevant objects.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api</code></pre>
</div>
</div>
<div class="paragraph">
<p>We get following response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>The entry point provides a user with links to the collections in a
virtualization environment. The <code>rel</code> attribute of each collection link
provides a reference point for each link.</p>
</div>
<div class="paragraph">
<p>The entry point also contains other data such as <code>product_info</code>,
<code>special_objects</code> and <code>summary</code>.</p>
</div>
authorvaluePiotr Kliczewski <pkliczew@redhat.com>datevalue14 Sep 2016statusvalueaddedgetapifalsefalseapireload_configurationsIndicates if the reload should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the reload should be performed asynchronously.</p>
</div>
asynctruetruebooleanReference to the service that provides information about the cluster levels supported by the system.
<div class="paragraph">
<p>Reference to the service that provides information about the cluster levels supported by the system.</p>
</div>
cluster_levelscluster_levelsbookmarksbookmarksclustersclusterscpu_profilescpu_profilesdata_centersdata_centersdisk_profilesdisk_profilesdisksdisksdomainsdomainseventseventsexternal_host_providersexternal_host_providersReference to service facilitating import of external virtual machines.
<div class="paragraph">
<p>Reference to service facilitating import of external virtual machines.</p>
</div>
authorvalueMartin Betak <mbetak@redhat.com>datevalue27 Jul 2016statusvalueaddedsincevalue4.0.4external_vm_importsexternal_vm_importsgroupsgroupshostshostsiconsiconsinstance_typesinstance_typesjobsjobsList all known affinity labels.
<div class="paragraph">
<p>List all known affinity labels.</p>
</div>
affinity_labelsaffinity_labelsmac_poolsmac_poolsNetwork filters will enhance the admin ability to manage the network packets traffic from/to the participated
VMs.
<div class="paragraph">
<p>Network filters will enhance the admin ability to manage the network packets traffic from/to the participated
VMs.</p>
</div>
network_filtersnetwork_filtersnetworksnetworksopenstack_image_providersopenstack_image_providersopenstack_network_providersopenstack_network_providersopenstack_volume_providersopenstack_volume_providersoperating_systemsoperating_systemsrolesrolesscheduling_policiesscheduling_policiesscheduling_policy_unitsscheduling_policy_unitsstorage_domainsstorage_domainsstorage_connectionsstorage_server_connectionskatello_errataengine_katello_erratapermissionssystem_permissionstagstagstemplatestemplatesusersusersvm_poolsvm_poolsvmsvmsvnic_profilesvnic_profilesList of all image transfers being performed for image I/O in oVirt.
<div class="paragraph">
<p>List of all image transfers being performed for image I/O in oVirt.</p>
</div>
authorvalueAmit Aviram <aaviram@redhat.com>datevalue30 Aug 2016statusvalueaddedsincevalue4.0.4image_transfersimage_transfersareavalueInfrastructureexternal_hostgethostfalsefalseexternal_hostareavalueInfrastructureexternal_host_groupgetgroupfalsefalseexternal_host_groupareavalueInfrastructurekatello_erratumgeterratumfalsefalsekatello_erratumareavalueInfrastructureexternal_discovered_hostgethostfalsefalseexternal_discovered_hostThis 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 Katello errata assigned to the engine.
<div class="paragraph">
<p>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 Katello errata assigned to the engine.</p>
</div>
areavalueInfrastructureengine_katello_erratalisterratafalsefalsekatello_erratum[]Sets the maximum number of errata to return. If not specified all the errata are returned.
<div class="paragraph">
<p>Sets the maximum number of errata to return. If not specified all the errata are returned.</p>
</div>
maxtruetrueintegerkatello_erratumkatello_erratumidfalsefalsestringareavalueInfrastructureexternal_compute_resourcegetresourcefalsefalseexternal_compute_resourceareavalueInfrastructureexternal_host_groupslistgroupsfalsefalseexternal_host_group[]Sets the maximum number of groups to return. If not specified all the groups are returned.
<div class="paragraph">
<p>Sets the maximum number of groups to return. If not specified all the groups are returned.</p>
</div>
maxtruetrueintegergroupexternal_host_groupidfalsefalsestringareavalueInfrastructureexternal_host_providerimport_certificatescertificatestruetruecertificate[]test_connectivityIndicates if the test should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the test should be performed asynchronously.</p>
</div>
asynctruetruebooleangetproviderfalsefalseexternal_host_providerupdateprovidertruetrueexternal_host_providerIndicates if the update should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the update should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleancertificatesexternal_provider_certificatescompute_resourcesexternal_compute_resourcesdiscovered_hostsexternal_discovered_hostshost_groupsexternal_host_groupshostsexternal_hostsareavalueInfrastructurekatello_erratalisterratafalsefalsekatello_erratum[]Sets the maximum number of errata to return. If not specified all the errata are returned.
<div class="paragraph">
<p>Sets the maximum number of errata to return. If not specified all the errata are returned.</p>
</div>
maxtruetrueintegerkatello_erratumkatello_erratumidfalsefalsestringareavalueInfrastructureexternal_discovered_hostslisthostsfalsefalseexternal_discovered_host[]Sets the maximum number of hosts to return. If not specified all the hosts are returned.
<div class="paragraph">
<p>Sets the maximum number of hosts to return. If not specified all the hosts are returned.</p>
</div>
maxtruetrueintegerhostexternal_discovered_hostidfalsefalsestringareavalueInfrastructureexternal_hostslisthostsfalsefalseexternal_host[]Sets the maximum number of hosts to return. If not specified all the hosts are returned.
<div class="paragraph">
<p>Sets the maximum number of hosts to return. If not specified all the hosts are returned.</p>
</div>
maxtruetrueintegerhostexternal_hostidfalsefalsestringareavalueInfrastructureexternal_compute_resourceslistresourcesfalsefalseexternal_compute_resource[]Sets the maximum number of resources to return. If not specified all the resources are returned.
<div class="paragraph">
<p>Sets the maximum number of resources to return. If not specified all the resources are returned.</p>
</div>
maxtruetrueintegerresourceexternal_compute_resourceidfalsefalsestringareavalueInfrastructureexternal_host_providersaddprovidertruetrueexternal_host_providerlistprovidersfalsefalseexternal_host_provider[]Sets the maximum number of providers to return. If not specified all the providers are returned.
<div class="paragraph">
<p>Sets the maximum number of providers to return. If not specified all the providers are returned.</p>
</div>
maxtruetrueintegerproviderexternal_host_provideridfalsefalsestringareavalueGlustergluster_brickgetbrickfalsefalsegluster_brickRemoves this brick from the volume and deletes it from the database.
<div class="paragraph">
<p>Removes this brick from the volume and deletes it from the database.</p>
</div>
removeIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanReplaces this brick with a new one. The property `brick` is required.
<div class="paragraph">
<p>Replaces this brick with a new one. The property <code>brick</code> is required.</p>
</div>
deprecatedreplaceforcetruetruebooleanIndicates if the replacement should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the replacement should be performed asynchronously.</p>
</div>
asynctruetruebooleanstatisticsstatisticsareavalueGlustergluster_volumesCreates a new Gluster volume and adds it to the database. The volume is created based on properties of the
`volume` parameter. The properties `name`, `volumeType` and `bricks` are required.
<div class="paragraph">
<p>Creates a new Gluster volume and adds it to the database. The volume is created based on properties of the
<code>volume</code> parameter. The properties <code>name</code>, <code>volumeType</code> and <code>bricks</code> are required.</p>
</div>
addThe Gluster volume definition from which to create the volume is passed as input and the newly created
volume is returned.
<div class="paragraph">
<p>The Gluster volume definition from which to create the volume is passed as input and the newly created
volume is returned.</p>
</div>
volumetruetruegluster_volumelistvolumesfalsefalsegluster_volume[]Sets the maximum number of volumes to return. If not specified all the volumes are returned.
<div class="paragraph">
<p>Sets the maximum number of volumes to return. If not specified all the volumes are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned volumes.
<div class="paragraph">
<p>A query string used to restrict the returned volumes.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanvolumegluster_volumeidfalsefalsestringareavalueGlustergluster_volumegetvolumefalsefalsegluster_volumeget_profile_statisticsdetailsfalsefalsegluster_volume_profile_detailsrebalancefix_layouttruetruebooleanforcetruetruebooleanIndicates if the rebalance should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the rebalance should be performed asynchronously.</p>
</div>
asynctruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanreset_all_optionsIndicates if the reset should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the reset should be performed asynchronously.</p>
</div>
asynctruetruebooleanreset_optionforcetruetruebooleanoptiontruetrueoptionIndicates if the reset should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the reset should be performed asynchronously.</p>
</div>
asynctruetruebooleanset_optionoptiontruetrueoptionIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanstartforcetruetruebooleanIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanstart_profileIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanstopforcetruetruebooleanIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanstop_profileIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanstop_rebalanceIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanstatisticsstatisticsgluster_bricksgluster_bricksareavalueGlustergluster_hookResolves 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.
<div class="paragraph">
<p>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 <code>DISABLED</code> in database.</p>
</div>
disableIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanResolves 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.
<div class="paragraph">
<p>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 <code>DISABLED</code> in database.</p>
</div>
enableIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleangethookfalsefalsegluster_hookRemoves the this Gluster hook from all servers in cluster and deletes it from the database.
<div class="paragraph">
<p>Removes the this Gluster hook from all servers in cluster and deletes it from the database.</p>
</div>
removeIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanResolves 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.
<div class="paragraph">
<p>Resolves missing hook conflict depending on the resolution type.</p>
</div>
<div class="paragraph">
<p>For <code>ADD</code> 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.</p>
</div>
<div class="paragraph">
<p>For <code>COPY</code> 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.</p>
</div>
resolvehosttruetruehostresolution_typetruetruestringIndicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanareavalueGlustergluster_bricksactivatebrickstruetruegluster_brick[]Indicates if the activation should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the activation should be performed asynchronously.</p>
</div>
asynctruetruebooleanAdds given list of bricks to the volume, and updates the database accordingly. The properties `serverId` and
`brickDir`are required.
<div class="paragraph">
<p>Adds given list of bricks to the volume, and updates the database accordingly. The properties <code>serverId</code> and
`brickDir`are required.</p>
</div>
addThe list of bricks to be added to the volume
<div class="paragraph">
<p>The list of bricks to be added to the volume</p>
</div>
brickstruetruegluster_brick[]listbricksfalsefalsegluster_brick[]Sets the maximum number of bricks to return. If not specified all the bricks are returned.
<div class="paragraph">
<p>Sets the maximum number of bricks to return. If not specified all the bricks are returned.</p>
</div>
maxtruetrueintegermigratebrickstruetruegluster_brick[]Indicates if the migration should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the migration should be performed asynchronously.</p>
</div>
asynctruetruebooleanRemoves the given list of bricks brick from the volume and deletes them from the database.
<div class="paragraph">
<p>Removes the given list of bricks brick from the volume and deletes them from the database.</p>
</div>
removeThe list of bricks to be removed
<div class="paragraph">
<p>The list of bricks to be removed</p>
</div>
brickstruetruegluster_brick[]Indicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanstop_migratebrickstruetruegluster_brick[]Indicates if the action should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the action should be performed asynchronously.</p>
</div>
asynctruetruebooleanbrickgluster_brickidfalsefalsestringareavalueGlustergluster_hookslisthooksfalsefalsegluster_hook[]Sets the maximum number of hooks to return. If not specified all the hooks are returned.
<div class="paragraph">
<p>Sets the maximum number of hooks to return. If not specified all the hooks are returned.</p>
</div>
maxtruetrueintegerhookgluster_hookidfalsefalsestringManages the collection of disks available in the system.
<div class="paragraph">
<p>Manages the collection of disks available in the system.</p>
</div>
areavalueStorageauthorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue4 Nov 2016statusvalueaddeddisksAdds a new floating disk.
When creating a new floating <<types/disk,Disk>>, the API requires the `storage_domain`, `provisioned_size` and
`format` attributes.
To create a new floating disk with specified `provisioned_size`, `format` and `name` on a storage domain with an
id `e9fedf39-5edc-4e0a-8628-253f1b9c5693`, send a request as follows:
[source]
----
POST /ovirt-engine/api/disks
----
With a request body as follows:
[source,xml]
----
<disk>
<storage_domains>
<storage_domain id="e9fedf39-5edc-4e0a-8628-253f1b9c5693"/>
</storage_domains>
<name>disk1</name>
<provisioned_size>1048576</provisioned_size>
<format>cow</format>
</disk>
----
<div class="paragraph">
<p>Adds a new floating disk.</p>
</div>
<div class="paragraph">
<p>When creating a new floating <a href="#types/disk">Disk</a>, the API requires the <code>storage_domain</code>, <code>provisioned_size</code> and
<code>format</code> attributes.</p>
</div>
<div class="paragraph">
<p>To create a new floating disk with specified <code>provisioned_size</code>, <code>format</code> and <code>name</code> on a storage domain with an
id <code>e9fedf39-5edc-4e0a-8628-253f1b9c5693</code>, send a request as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/disks</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><disk>
<storage_domains>
<storage_domain id="e9fedf39-5edc-4e0a-8628-253f1b9c5693"/>
</storage_domains>
<name>disk1</name>
<provisioned_size>1048576</provisioned_size>
<format>cow</format>
</disk></code></pre>
</div>
</div>
authorvalueIdan Shaby <ishaby@redhat.com>datevalue14 Sep 2016statusvalueaddedadddisktruetruedisklistdisksfalsefalsedisk[]Sets the maximum number of disks to return. If not specified all the disks are returned.
<div class="paragraph">
<p>Sets the maximum number of disks to return. If not specified all the disks are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned disks.
<div class="paragraph">
<p>A query string used to restrict the returned disks.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleandiskdiskidfalsefalsestringareavalueVirtualizationinstance_type_watchdogsaddwatchdogtruetruewatchdoglistwatchdogsfalsefalsewatchdog[]Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.
<div class="paragraph">
<p>Sets the maximum number of watchdogs to return. If not specified all the watchdogs are returned.</p>
</div>
maxtruetrueintegerwatchdoginstance_type_watchdogidfalsefalsestringareavalueInfrastructurejobsaddjobtruetruejoblistjobsfalsefalsejob[]Sets the maximum number of jobs to return. If not specified all the jobs are returned.
<div class="paragraph">
<p>Sets the maximum number of jobs to return. If not specified all the jobs are returned.</p>
</div>
maxtruetrueintegerjobjobidfalsefalsestringareavalueVirtualizationiconslisticonsfalsefalseicon[]Sets the maximum number of icons to return. If not specified all the icons are returned.
<div class="paragraph">
<p>Sets the maximum number of icons to return. If not specified all the icons are returned.</p>
</div>
maxtruetrueintegericoniconidfalsefalsestringareavalueVirtualizationtemplatesCreates a new template.
This requires the `name` and `vm` elements. Identify the virtual machine with the `id` `name` attributes.
[source]
----
POST /ovirt-engine/api/templates
----
With a request body like this:
[source,xml]
----
<template>
<name>mytemplate</name>
<vm id="123"/>
</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.
[source,xml]
----
<template>
<name>mytemplate</name>
<vm id="123"/>
<version>
<base_template id="456"/>
<version_name>mytemplate_001</version_name>
</version>
</template>
----
<div class="paragraph">
<p>Creates a new template.</p>
</div>
<div class="paragraph">
<p>This requires the <code>name</code> and <code>vm</code> elements. Identify the virtual machine with the <code>id</code> <code>name</code> attributes.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/templates</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><template>
<name>mytemplate</name>
<vm id="123"/>
</template></code></pre>
</div>
</div>
<div class="paragraph">
<p>The template can be created as a sub version of an existing template.This requires the <code>name</code> and <code>vm</code> attributes
for the new template, and the <code>base_template</code> and <code>version_name</code> attributes for the new template version. The
<code>base_template</code> and <code>version_name</code> attributes must be specified within a <code>version</code> section enclosed in the
<code>template</code> section. Identify the virtual machine with the <code>id</code> or <code>name</code> attributes.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><template>
<name>mytemplate</name>
<vm id="123"/>
<version>
<base_template id="456"/>
<version_name>mytemplate_001</version_name>
</version>
</template></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedaddtemplatetruetruetemplateSpecifies if the permissions of the virtual machine should be copied to the template.
If this optional parameter is provided, and its values is `true` then the permissions of the virtual machine
(only the direct ones, not the inherited ones) will be copied to the created template. For example, to create
a template from the `myvm` virtual machine copying its permissions, send a request like this:
[source]
----
POST /ovirt-engine/api/templates?clone_permissions=true
----
With a request body like this:
[source,xml]
----
<template>
<name>mytemplate<name>
<vm>
<name>myvm<name>
</vm>
</template>
----
<div class="paragraph">
<p>Specifies if the permissions of the virtual machine should be copied to the template.</p>
</div>
<div class="paragraph">
<p>If this optional parameter is provided, and its values is <code>true</code> 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 <code>myvm</code> virtual machine copying its permissions, send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/templates?clone_permissions=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><template>
<name>mytemplate<name>
<vm>
<name>myvm<name>
</vm>
</template></code></pre>
</div>
</div>
authorvalueJuan Hernandez <juan.hernandez@redhat.com>datevalue16 Aug 2016statusvalueaddedsincevalue4.0.0clone_permissionstruetruebooleanlisttemplatesfalsefalsetemplate[]Sets the maximum number of templates to return. If not specified all the templates are returned.
<div class="paragraph">
<p>Sets the maximum number of templates to return. If not specified all the templates are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned templates.
<div class="paragraph">
<p>A query string used to restrict the returned templates.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleantemplatetemplateidfalsefalsestringareavalueSLAfiltergetresultfalsefalsefilterIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanremoveIndicates if the remove should be performed asynchronously.
<div class="paragraph">
<p>Indicates if the remove should be performed asynchronously.</p>
</div>
asynctruetruebooleanThis service is used to list and manipulate affinity labels that are
assigned to supported entities when accessed using entities/affinitylabels.
<div class="paragraph">
<p>This service is used to list and manipulate affinity labels that are
assigned to supported entities when accessed using entities/affinitylabels.</p>
</div>
assigned_affinity_labelsAttaches a label to an entity.
<div class="paragraph">
<p>Attaches a label to an entity.</p>
</div>
addlabeltruetrueaffinity_labelLists all labels that are attached to an entity.
<div class="paragraph">
<p>Lists all labels that are attached to an entity.</p>
</div>
listlabelfalsefalseaffinity_label[]Link to the specific entity-label assignment to allow
removal.
<div class="paragraph">
<p>Link to the specific entity-label assignment to allow
removal.</p>
</div>
labelassigned_affinity_labelidfalsefalsestringareavalueStoragesnapshot_cdromgetcdromfalsefalsecdromareavalueSLAhost_numa_nodegetnodefalsefalsenuma_nodestatisticsstatisticsThis service represents list of hosts that have a specific
label when accessed through the affinitylabels/hosts
subcollection.
<div class="paragraph">
<p>This service represents list of hosts that have a specific
label when accessed through the affinitylabels/hosts
subcollection.</p>
</div>
affinity_label_hostsAdd a label to a host.
<div class="paragraph">
<p>Add a label to a host.</p>
</div>
addhosttruetruehostList all hosts with the label.
<div class="paragraph">
<p>List all hosts with the label.</p>
</div>
listhostsfalsefalsehost[]A link to the specific label-host assignment to
allow label removal.
<div class="paragraph">
<p>A link to the specific label-host assignment to
allow label removal.</p>
</div>
hostaffinity_label_hostidfalsefalsestringareavalueStoragedisk_snapshotslistsnapshotsfalsefalsedisk_snapshot[]Sets the maximum number of snapshots to return. If not specified all the snapshots are returned.
<div class="paragraph">
<p>Sets the maximum number of snapshots to return. If not specified all the snapshots are returned.</p>
</div>
maxtruetrueintegersnapshotdisk_snapshotidfalsefalsestringLists 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:
[source]
----
GET /ovirt-engine/api/storagedomains/123/vms
----
This will return the following response body:
[source,xml]
----
<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 <<types/vm, Vm>> and <<types/template, Template>> collections, except they also contain a
<<types/storage_domain, StorageDomain>> reference and an <<services/storage_domain_vm/methods/import, import>>
action.
<div class="paragraph">
<p>Lists the virtual machines of an export storage domain.</p>
</div>
<div class="paragraph">
<p>For example, to retrieve the virtual machines that are available in the storage domain with identifier <code>123</code> send the
following request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/storagedomains/123/vms</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will return the following response body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><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></code></pre>
</div>
</div>
<div class="paragraph">
<p>Virtual machines and templates in these collections have a similar representation to their counterparts in the
top-level <a href="#types/vm">Vm</a> and <a href="#types/template">Template</a> collections, except they also contain a
<a href="#types/storage_domain">StorageDomain</a> reference and an <a href="#services/storage_domain_vm/methods/import">import</a>
action.</p>
</div>
areavalueStorageauthorvalueAmit Aviram <aaviram@redhat.com>datevalue14 Sep 2016statusvalueaddedstorage_domain_vmslistvmfalsefalsevm[]Sets the maximum number of virtual machines to return. If not specified all the virtual machines are
returned.
<div class="paragraph">
<p>Sets the maximum number of virtual machines to return. If not specified all the virtual machines are
returned.</p>
</div>
maxtruetrueintegervmstorage_domain_vmidfalsefalsestringareavalueInfrastructurehostsCreates 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:
[source]
----
POST /ovirt-engine/api/hosts
----
With the following request body:
[source,xml]
----
<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.
To add a hosted engine host, use the optional `deploy_hosted_engine` parameter:
[source]
----
POST /ovirt-engine/api/hosts?deploy_hosted_engine=true
----
<div class="paragraph">
<p>Creates a new host.</p>
</div>
<div class="paragraph">
<p>The host is created based on the attributes of the <code>host</code> parameter. The <code>name</code>, <code>address</code> and <code>root_password</code>
properties are required.</p>
</div>
<div class="paragraph">
<p>For example, to add a host send the following request:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/hosts</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the following request body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><host>
<name>myhost</name>
<address>myhost.example.com</address>
<root_password>myrootpassword</root_password>
</host></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The <code>root_password</code> element is only included in the client-provided initial representation and is not
exposed in the representations returned from subsequent requests.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To add a hosted engine host, use the optional <code>deploy_hosted_engine</code> parameter:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/hosts?deploy_hosted_engine=true</code></pre>
</div>
</div>
authorvalueJakub Niedermertl <jniederm@redhat.com>Roy Golan <rgolan@redhat.com>datevalue14 Sep 2016statusvalueaddedaddThe host definition from which to create the new host is passed as parameter, and the newly created host
is returned.
<div class="paragraph">
<p>The host definition from which to create the new host is passed as parameter, and the newly created host
is returned.</p>
</div>
hosttruetruehostWhen 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.
<div class="paragraph">
<p>When set to <code>true</code> it means this host should deploy also hosted engine components. Missing value is treated
as <code>true</code> i.e deploy. Omitting this parameter means <code>false</code> and will perform no operation in hosted engine
area.</p>
</div>
deploy_hosted_enginetruetruebooleanWhen 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.
<div class="paragraph">
<p>When set to <code>true</code> 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 <code>true</code> i.e un-deploy.
Omitting this parameter means <code>false</code> and will perform no operation in hosted engine area.</p>
</div>
undeploy_hosted_enginetruetruebooleanlisthostsfalsefalsehost[]Sets the maximum number of hosts to return. If not specified all the hosts are returned.
<div class="paragraph">
<p>Sets the maximum number of hosts to return. If not specified all the hosts are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned hosts.
<div class="paragraph">
<p>A query string used to restrict the returned hosts.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanhosthostidfalsefalsestringareavalueSLAfiltersaddfiltertruetruefilterlistfiltersfalsefalsefilter[]Sets the maximum number of filters to return. If not specified all the filters are returned.
<div class="paragraph">
<p>Sets the maximum number of filters to return. If not specified all the filters are returned.</p>
</div>
maxtruetrueintegerIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanfilterfilteridfalsefalsestringareavalueStoragestorage_server_connectionsCreates 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:
[source]
----
POST /ovirt-engine/api/storageconnections
----
With a request body like this:
[source,xml]
----
<storage_connection>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/export/mydata</path>
<host>
<name>myhost</name>
</host>
</storage_connection>
----
<div class="paragraph">
<p>Creates a new storage connection.</p>
</div>
<div class="paragraph">
<p>For example, to create a new storage connection for the NFS server <code>mynfs.example.com</code> and NFS share
<code>/export/mydata</code> send a request like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/storageconnections</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_connection>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/export/mydata</path>
<host>
<name>myhost</name>
</host>
</storage_connection></code></pre>
</div>
</div>
authorvalueDaniel Erez <derez@redhat.com>datevalue14 Sep 2016statusvalueaddedaddconnectiontruetruestorage_connectionlistconnectionsfalsefalsestorage_connection[]Sets the maximum number of connections to return. If not specified all the connections are returned.
<div class="paragraph">
<p>Sets the maximum number of connections to return. If not specified all the connections are returned.</p>
</div>
maxtruetrueintegerstorage_connectionstorage_server_connectionidfalsefalsestringareavalueInfrastructurefence_agentsaddagenttruetrueagentlistagentsfalsefalseagent[]Sets the maximum number of agents to return. If not specified all the agents are returned.
<div class="paragraph">
<p>Sets the maximum number of agents to return. If not specified all the agents are returned.</p>
</div>
maxtruetrueintegeragentfence_agentidfalsefalsestringareavalueVirtualizationclustersCreates a new cluster.
This requires the `name`, `cpu.type` and `data_center` attributes. Identify the data center with either the `id`
or `name` attributes.
[source]
----
POST /ovirt-engine/api/clusters
----
With a request body like this:
[source,xml]
----
<cluster>
<name>mycluster</name>
<cpu>
<type>Intel Penryn Family</type>
</cpu>
<data_center id="123"/>
</cluster>
----
<div class="paragraph">
<p>Creates a new cluster.</p>
</div>
<div class="paragraph">
<p>This requires the <code>name</code>, <code>cpu.type</code> and <code>data_center</code> attributes. Identify the data center with either the <code>id</code>
or <code>name</code> attributes.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>POST /ovirt-engine/api/clusters</code></pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cluster>
<name>mycluster</name>
<cpu>
<type>Intel Penryn Family</type>
</cpu>
<data_center id="123"/>
</cluster></code></pre>
</div>
</div>
authorvalueArik Hadas <ahadas@redhat.com>datevalue14 Sep 2016statusvalueaddedaddclustertruetrueclusterlistclustersfalsefalsecluster[]Sets the maximum number of clusters to return. If not specified all the clusters are returned.
<div class="paragraph">
<p>Sets the maximum number of clusters to return. If not specified all the clusters are returned.</p>
</div>
maxtruetrueintegerA query string used to restrict the returned clusters.
<div class="paragraph">
<p>A query string used to restrict the returned clusters.</p>
</div>
searchtruetruestringIndicates 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`.
<div class="paragraph">
<p>Indicates if the search performed using the <code>search</code> parameter should be performed taking case into
account. The default value is <code>true</code>, which means that case is taken into account. If you want to search
ignoring case set it to <code>false</code>.</p>
</div>
case_sensitivetruetruebooleanIndicates if the results should be filtered according to the permissions of the user.
<div class="paragraph">
<p>Indicates if the results should be filtered according to the permissions of the user.</p>
</div>
filtertruetruebooleanclusterclusteridfalsefalsestringRepresents a permission sub-collection, scoped by User or some entity type.
<div class="paragraph">
<p>Represents a permission sub-collection, scoped by User or some entity type.</p>
</div>
areavalueInfrastructureassigned_permissionsaddpermissiontruetruepermissionlistpermissionsfalsefalsepermission[]Sub-resource locator method, returns individual permission resource on which the remainder of the URI is
dispatched.
<div class="paragraph">
<p>Sub-resource locator method, returns individual permission resource on which the remainder of the URI is
dispatched.</p>
</div>
permissionpermissionidfalsefalsestring003_quick_start_example
<div class="sect1">
<h2 id="_quick_start_example">Quick start example</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This chapter provides an example to demonstrate the REST API’s ability
to setup a basic oVirt environment and create a virtual machine.
In addition to the standard prerequisites, this example requires the
following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A networked and configured oVirt installation;</p>
</li>
<li>
<p>An ISO file containing a desired virtual machine operating system to
install. This chapter uses <a href="https://www.centos.org">CentOS</a> 7 for our
installation ISO example; and</p>
</li>
<li>
<p>oVirt’s <code>engine-iso-uploader</code> tool to upload your chosen
operating system ISO file.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This example uses <a href="https://curl.haxx.se"><code>curl</code></a> to demonstrate API
requests with a client application. Note that any application capable of
HTTP requests can substitute for <code>curl</code>.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
For simplicity, the HTTP request headers in this example omit
the <code>Host</code> and <code>Authorization</code> headers. However, these fields are mandatory
and require data specific to your installation of oVirt.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
All the <code>curl</code> examples use <code>admin@internal</code> as the user
name, <code>mypassword</code> as the password, <code>/etc/pki/ovirt-engine/ca.pem</code> as the
certificate location and <code>myengine.example.com</code> as the host name. These
are just examples, Make sure to replace them with valid values for your
environment.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
oVirt generates an unique identifier for the <code>id</code>
attribute for each resource. Identifier codes in this example might
appear different to the identifier codes in your oVirt
environment.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
In many examples of this section some of the attributes of results
returned by the API have been omitted, to make them shorter. You can
always use the reference to find the complete list of attributes. For
example, if you want to see the complete list of attributes of the
<code>Cluster</code> type, just go <a href="#types/cluster">here</a>.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="_example_access_api_entry_point">Example: Access API entry point</h3>
<div class="paragraph">
<p>The following request retrieves a representation of the main entry point
for version 4 of of the API:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api HTTP/1.1
Version: 4
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>Same request, but using the <code>/v4</code> URL prefix instead of the <code>Version</code>
header:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/v4 HTTP/1.1
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api</pre>
</div>
</div>
<div class="paragraph">
<p>The result will be an object of type <a href="#types/api">Api</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><api>
<link href="/ovirt-engine/api/clusters" rel="clusters"/>
<link href="/ovirt-engine/api/datacenters" rel="datacenters"/>
...
<product_info>
<name>oVirt Engine</name>
<vendor>ovirt.org</vendor>
<version>
<build>0</build>
<full_version>4.0.0-0.0.el7</full_version>
<major>4</major>
<minor>0</minor>
<revision>0</revision>
</version>
</product_info>
<special_objects>
<blank_template href="..." id="..."/>
<root_tag href="..." id="..."/>
</special_objects>
<summary>
<hosts>
<active>23</active>
<total>30</total>
</hosts>
<storage_domains>
<active>5</active>
<total>6</total>
</storage_domains>
<users>
<active>12</active>
<total>102</total>
</users>
<vms>
<active>253</active>
<total>545</total>
</vms>
</summary>
<time>2016-10-06T15:38:18.548+02:00</time>
</api></code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
<div class="paragraph">
<p>When neither the header nor the URL prefix are used, the server will
automatically select a version. The default is version <code>4</code>. You can change
the default version using the <code>ENGINE_API_DEFAULT_VERSION</code> configuration
parameter:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># echo "ENGINE_API_DEFAULT_VERSION=3" > \
/etc/ovirt-engine/engine.conf.d/99-set-default-version.conf
# systemctl restart ovirt-engine</pre>
</div>
</div>
<div class="paragraph">
<p>Changing this parameter affects all users of the API that don’t
specify the version explicitly.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The entry point provides a user with links to the collections in a
virtualization environment. The <code>rel</code> attribute of each collection link
provides a reference point for each link. The next step in this example
examines the data center collection, which is available through the
<code>datacenters</code> link.</p>
</div>
<div class="paragraph">
<p>The entry point also contains other data such as <a href="#types/product_info">product_info</a>, <a href="#types/special_objects">special_objects</a> and
<a href="#types/api_summary">summary</a>. This data is covered in chapters
outside this example.</p>
</div>
</div>
<div class="sect2">
<h3 id="_example_list_data_centers">Example: List data centers</h3>
<div class="paragraph">
<p>oVirt creates a <code>Default</code> data center on installation. This
example uses the <code>Default</code> data center as the basis for our virtual
environment.</p>
</div>
<div class="paragraph">
<p>The following request retrieves a representation of the data centers:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/datacenters HTTP/1.1
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/datacenters</pre>
</div>
</div>
<div class="paragraph">
<p>The result will be a list of objects of type <a href="#types/data_center">DataCenter</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><data_centers>
<data_center href="/ovirt-engine/api/datacenters/001" id="001">
<name>Default</name>
<description>The default Data Center</description>
<link href="/ovirt-engine/api/datacenters/001/clusters" rel="clusters"/>
<link href="/ovirt-engine/api/datacenters/001/storagedomains" rel="storagedomains"/>
...
<local>false</local>
<quota_mode>disabled</quota_mode>
<status>up</status>
<supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</supported_versions>
<version>
<major>4</major>
<minor>0</minor>
</version>
</data_center>
...
</data_centers></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note the <code>id</code> of your <code>Default</code> data center. It identifies this data
center in relation to other resources of your virtual environment.</p>
</div>
<div class="paragraph">
<p>The data center also contains a link to the
<a href="#services/attached_storage_domains">service</a> that manages the storage
domains attached to the data center:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><link href="/ovirt-engine/api/datacenters/001/storagedomains" rel="storagedomains"/></pre>
</div>
</div>
<div class="paragraph">
<p>That service is used to attach storage domains from the main
<code>storagedomains</code> collection, which this example covers later.</p>
</div>
</div>
<div class="sect2">
<h3 id="_example_list_host_clusters">Example: List host clusters</h3>
<div class="paragraph">
<p>oVirt creates a <code>Default</code> hosts cluster on installation. This
example uses the <code>Default</code> cluster to group resources in your
oVirt environment.</p>
</div>
<div class="paragraph">
<p>The following request retrieves a representation of the cluster
collection:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/clusters HTTP/1.1
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/clusters</pre>
</div>
</div>
<div class="paragraph">
<p>The result will be a list of objects of type <a href="#types/cluster">Cluster</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><clusters>
<cluster href="/ovirt-engine/api/clusters/002" id="002">
<name>Default</name>
<description>The default server cluster</description>
<link href="/ovirt-engine/api/clusters/002/networks" rel="networks"/>
<link href="/ovirt-engine/api/clusters/002" rel="permissions"/>
...
<cpu>
<architecture>x86_64</architecture>
<type>Intel Conroe Family</type>
</cpu>
<version>
<major>4</major>
<minor>0</minor>
</version>
<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
</cluster>
...
</clusters></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note the <code>id</code> of your <code>Default</code> host cluster. It identifies this host
cluster in relation to other resources of your virtual environment.</p>
</div>
<div class="paragraph">
<p>The <code>Default</code> cluster is associated with the <code>Default</code> data center
through a relationship using the <code>id</code> and <code>href</code> attributes of the
<code>data_center</code> link:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><data_center href="/ovirt-engine/api/datacenters/001" id="001"/></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>networks</code> link is a reference to the <a href="#services/assigned_networks">service</a> that manages the networks associated to this cluster. The next
section examines the networks collection in more detail.</p>
</div>
</div>
<div class="sect2">
<h3 id="_example_list_logical_networks">Example: List logical networks</h3>
<div class="paragraph">
<p>oVirt creates a default <code>ovirtmgmt</code> network on installation.
This network acts as the management network for oVirt Engine to access
hosts.</p>
</div>
<div class="paragraph">
<p>This network is associated with our <code>Default</code> cluster and is a member of
the <code>Default</code> data center. This example uses the <code>ovirtmgmt</code> network to
connect our virtual machines.</p>
</div>
<div class="paragraph">
<p>The following request retrieves the list of logical networks:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/networks HTTP/1.1
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/networks</pre>
</div>
</div>
<div class="paragraph">
<p>The result will be a list of objects of type <a href="#types/network">Network</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><networks>
<network href="/ovirt-engine/api/networks/003" id="003">
<name>ovirtmgmt</name>
<description>Management Network</description>
<link href="/ovirt-engine/api/networks/003/permissions" rel="permissions"/>
<link href="/ovirt-engine/api/networks/003/vnicprofiles" rel="vnicprofiles"/>
<link href="/ovirt-engine/api/networks/003/networklabels" rel="networklabels"/>
<mtu>0</mtu>
<stp>false</stp>
<usages>
<usage>vm</usage>
</usages>
<data_center href="/ovirt-engine/api/datacenters/001" id="001"/>
</network>
...
</networks></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>ovirtmgmt</code> network is attached to the <code>Default</code> data center through a
relationship using the data center’s <code>id</code>.</p>
</div>
<div class="paragraph">
<p>The <code>ovirtmgmt</code> network is also attached to the <code>Default</code> cluster through a
relationship in the cluster’s network sub-collection.</p>
</div>
</div>
<div class="sect2">
<h3 id="_example_list_hosts">Example: List hosts</h3>
<div class="paragraph">
<p>This example retrieves the list of hosts and shows a host named <code>myhost</code>
registered with the virtualization environment:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/hosts HTTP/1.1
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/hosts</pre>
</div>
</div>
<div class="paragraph">
<p>The result will be a list of objects of type <a href="#types/host">Host</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><hosts>
<host href="/ovirt-engine/api/hosts/004" id="004">
<name>myhost</name>
<link href="/ovirt-engine/api/hosts/004/nics" rel="nics"/>
...
<address>node40.example.com</address>
<cpu>
<name>Intel Core Processor (Haswell, no TSX)</name>
<speed>3600</speed>
<topology>
<cores>1</cores>
<sockets>2</sockets>
<threads>1</threads>
</topology>
</cpu>
<memory>8371830784</memory>
<os>
<type>RHEL</type>
<version>
<full_version>7 - 2.1511.el7.centos.2.10</full_version>
<major>7</major>
</version>
</os>
<port>54321</port>
<status>up</status>
<cluster href="/ovirt-engine/api/clusters/002" id="002"/>
</host>
...
</hosts></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note the <code>id</code> of your host. It identifies this host in relation to other
resources of your virtual environment.</p>
</div>
<div class="paragraph">
<p>This host is a member of the <code>Default</code> cluster and accessing the <code>nics</code>
sub-collection shows this host has a connection to the <code>ovirtmgmt</code>
network.</p>
</div>
</div>
<div class="sect2">
<h3 id="_example_create_nfs_data_storage">Example: Create NFS data storage</h3>
<div class="paragraph">
<p>An NFS data storage domain is an exported NFS share attached to a data
center and provides storage for virtualized guest images. Creation of a
new storage domain requires a <code>POST</code> request, with the storage domain
representation included, sent to the URL of the storage domain
collection.</p>
</div>
<div class="paragraph">
<p>You can enable the wipe after delete option by default on the storage
domain. To configure this specify <code>wipe_after_delete</code> 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.</p>
</div>
<div class="paragraph">
<p>The request should be like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>And the request body should be like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_domain>
<name>mydata</name>
<type>data</type>
<description>My data</description>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/mydata</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain></code></pre>
</div>
</div>
<div class="paragraph">
<p>The same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
<name>mydata</name>
<description>My data</description>
<type>data</type>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/mydata</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains</pre>
</div>
</div>
<div class="paragraph">
<p>The server uses host <code>myhost</code> to create a NFS data storage domain called
<code>mydata</code> with an export path of <code>mynfs.example.com:/exports/mydata</code>. The
API also returns the following representation of the newly created
storage domain resource (of type <a href="#types/storage_domain">StorageDomain</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_domain href="/ovirt-engine/api/storagedomains/005" id="005">
<name>mydata</name>
<description>My data</description>
<available>42949672960</available>
<committed>0</committed>
<master>false</master>
<status>unattached</status>
<storage>
<address>mynfs.example.com</address>
<path>/exports/mydata</path>
<type>nfs</type>
</storage>
<storage_format>v3</storage_format>
<type>data</type>
<used>9663676416</used>
</storage_domain></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_example_create_nfs_iso_storage">Example: Create NFS ISO storage</h3>
<div class="paragraph">
<p>An NFS ISO storage domain is a mounted NFS share attached to a data
center and provides storage for DVD/CD-ROM ISO and virtual floppy disk
(VFD) image files. Creation of a new storage domain requires a <code>POST</code>
request, with the storage domain representation included, sent to the
URL of the storage domain collection:</p>
</div>
<div class="paragraph">
<p>The request should be like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>And the request body should be like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_domain>
<name>myisos</name>
<description>My ISOs</description>
<type>iso</type>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/myisos</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain></code></pre>
</div>
</div>
<div class="paragraph">
<p>The same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
<name>myisos</name>
<description>My ISOs</description>
<type>iso</type>
<storage>
<type>nfs</type>
<address>mynfs.example.com</address>
<path>/exports/myisos</path>
</storage>
<host>
<name>myhost</name>
</host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains</pre>
</div>
</div>
<div class="paragraph">
<p>The server uses host <code>myhost</code> to create a NFS ISO storage domain called
<code>myisos</code> with an export path of <code>mynfs.example.com:/exports/myisos</code>. The
API also returns the following representation of the newly created
storage domain resource (of type <a href="#types/storage_domain">StorageDomain</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_domain href="/ovirt-engine/api/storagedomains/006" id="006">
<name>myiso</name>
<description>My ISOs</description>
<available>42949672960</available>
<committed>0</committed>
<master>false</master>
<status>unattached</status>
<storage>
<address>mynfs.example.com</address>
<path>/exports/myisos</path>
<type>nfs</type>
</storage>
<storage_format>v1</storage_format>
<type>iso</type>
<used>9663676416</used>
</storage_domain></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_example_attach_storage_domains_to_data_center">Example: Attach storage domains to data center</h3>
<div class="paragraph">
<p>The following example attaches the <code>mydata</code> and <code>myisos</code> storage domains
to the <code>Default</code> data center.</p>
</div>
<div class="paragraph">
<p>To attach the <code>mydata</code> storage domain, send a request like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_domain>
<name>mydata</name>
</storage_domain></code></pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
<name>mydata</name>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains</pre>
</div>
</div>
<div class="paragraph">
<p>To attach the <code>myisos</code> storage domain, send a request like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>With a request body like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><storage_domain>
<name>myisos</name>
</storage_domain></code></pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
<name>myisos</name>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_example_create_virtual_machine">Example: Create virtual machine</h3>
<div class="paragraph">
<p>The following example creates a virtual machine called <code>myvm</code> on the
<code>Default</code> cluster using the virtualization environment’s <code>Blank</code>
template as a basis. The request also defines the virtual machine’s
memory as 512 MiB and sets the boot device to a virtual hard disk.</p>
</div>
<div class="paragraph">
<p>The request should be contain an object of type <a href="#types/vm">Vm</a>
describing the virtual machine to create:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml">POST /ovirt-engine/api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>And the request body should be like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm>
<name>myvm</name>
<description>My VM</description>
<cluster>
<name>Default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
</os>
</vm></code></pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<vm>
<name>myvm</name>
<description>My VM</description>
<cluster>
<name>Default</name>
</cluster>
<template>
<name>Blank</name>
</template>
<memory>536870912</memory>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
</os>
</vm>
' \
https://myengine.example.com/ovirt-engine/api/vms</pre>
</div>
</div>
<div class="paragraph">
<p>The response body will be an object of the <a href="#types/vm">Vm</a> type:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm href="/ovirt-engine/api/vms/007" id="007">
<name>myvm</name>
<link href="/ovirt-engine/api/vms/007/diskattachments" rel="diskattachments"/>
<link href="/ovirt-engine/api/vms/007/nics" rel="nics"/>
...
<cpu>
<architecture>x86_64</architecture>
<topology>
<cores>1</cores>
<sockets>1</sockets>
<threads>1</threads>
</topology>
</cpu>
<memory>1073741824</memory>
<os>
<boot>
<devices>
<device>hd</device>
</devices>
</boot>
<type>other</type>
</os>
<type>desktop</type>
<cluster href="/ovirt-engine/api/clusters/002" id="002"/>
<status>down</status>
<original_template href="/ovirt-engine/api/templates/000" id="00"/>
<template href="/ovirt-engine/api/templates/000" id="000"/>
</vm></code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_example_create_a_virtual_machine_nic">Example: Create a virtual machine NIC</h3>
<div class="paragraph">
<p>The following example creates a virtual network interface to connect the
example virtual machine to the <code>ovirtmgmt</code> network.</p>
</div>
<div class="paragraph">
<p>The request should be like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>POST /ovirt-engine/api/vms/007/nics HTTP/1.1
Content-Type: application/xml
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>The request body should contain an object of type <a href="#types/nic">Nic</a>
describing the NIC to be created:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><nic>
<name>mynic</name>
<description>My network interface card</description>
</nic></code></pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<nic>
<name>mynic</name>
<description>My network interface card</description>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/nics</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_example_create_virtual_machine_disk">Example: Create virtual machine disk</h3>
<div class="paragraph">
<p>The following example creates an 8 GiB <em>copy-on-write</em> disk for the
example virtual machine.</p>
</div>
<div class="paragraph">
<p>The request should be like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>POST /ovirt-engine/api/vms/007/diskattachments HTTP/1.1
Content-Type: application/xml
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>The request body should be an object of type <a href="#types/disk_attachment">DiskAttachment</a> describing the disk and how it will be attached to the
virtual machine:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><disk_attachment>
<bootable>false</bootable>
<interface>virtio</interface>
<active>true</active>
<disk>
<description>My disk</description>
<format>cow</format>
<name>mydisk</name>
<provisioned_size>8589934592</provisioned_size>
<storage_domains>
<storage_domain>
<name>mydata</name>
</storage_domain>
</storage_domains>
</disk>
</disk_attachment></code></pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<disk_attachment>
<bootable>false</bootable>
<interface>virtio</interface>
<active>true</active>
<disk>
<description>My disk</description>
<format>cow</format>
<name>mydisk</name>
<provisioned_size>8589934592</provisioned_size>
<storage_domains>
<storage_domain>
<name>mydata</name>
</storage_domain>
</storage_domains>
</disk>
</disk_attachment>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/diskattachments</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>storage_domains</code> attribute tells the API to store the disk on the
<code>mydata</code> storage domain.</p>
</div>
</div>
<div class="sect2">
<h3 id="_example_attach_iso_image_to_virtual_machine">Example: Attach ISO image to virtual machine</h3>
<div class="paragraph">
<p>The boot media for our example virtual machine requires an CD-ROM or DVD
ISO image for an operating system installation. This example uses a
CentOS 7 image for installation.</p>
</div>
<div class="paragraph">
<p>ISO images must be available in the <code>myisos</code> ISO domain for the virtual
machines to use. oVirt provides an uploader tool that ensures
that the ISO images are uploaded into the correct directory path with
the correct user permissions.</p>
</div>
<div class="paragraph">
<p>Once the ISO is uploaded, an API can be used to request the list of
files from the ISO storage domain:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/storagedomains/006/files HTTP/1.1
Accept: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
https://myengine.example.com/ovirt-engine/api/storagedomains/006/files</pre>
</div>
</div>
<div class="paragraph">
<p>The server returns the following list of objects of type <a href="#types/file">File</a>, one for each available ISO (or floppy) image:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><files>
<file href="..." id="CentOS-7-x86_64-Minimal.iso">
<name>CentOS-7-x86_64-Minimal.iso</name>
</file>
...
</files></code></pre>
</div>
</div>
<div class="paragraph">
<p>An API user attaches the <code>CentOS-7-x86_64-Minimal.iso</code> to our example
virtual machine. Attaching an ISO image is equivalent to using the
<em>Change CD</em> button in the administration or user portal applications.</p>
</div>
<div class="paragraph">
<p>The request should be like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>PUT /ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>The request body should be an object of type <a href="#types/cdrom">Cdrom</a>
containing an inner <code>file</code> attribute to indicate the identifier of the
ISO (or floppy) image:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><cdrom>
<file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom></code></pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request PUT \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<cdrom>
<file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000</pre>
</div>
</div>
<div class="paragraph">
<p>For more details see the documentation of the <a href="#services/vm_cdrom">service</a> that manages virtual machine CD-ROMS.</p>
</div>
</div>
<div class="sect2">
<h3 id="_example_start_the_virtual_machine">Example: Start the virtual machine</h3>
<div class="paragraph">
<p>The virtual environment is complete and the virtual machine contains all
necessary components to function. This example starts the virtual
machine using the <a href="#services/vm/methods/start">start</a> method.</p>
</div>
<div class="paragraph">
<p>The request should be like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>POST /ovirt-engine/api/vms/007/start HTTP/1.1
Accept: application/xml
Content-type: application/xml</pre>
</div>
</div>
<div class="paragraph">
<p>The request body should be like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><action>
<vm>
<os>
<boot>
<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm>
</action></code></pre>
</div>
</div>
<div class="paragraph">
<p>Same request, using the <code>curl</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<action>
<vm>
<os>
<boot>
<devices>
<device>cdrom</device>
</devices>
</boot>
</os>
</vm>
</action>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/start</pre>
</div>
</div>
<div class="paragraph">
<p>The additional request body sets the virtual machine’s boot device to
CD-ROM for this boot only. This enables the virtual machine to install
the operating system from the attached ISO image. The boot device
reverts back to disk for all future boots.</p>
</div>
</div>
</div>
</div>
002_authentication_and_security
<div class="sect1">
<h2 id="_authentication_and_security">Authentication and security</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_tls_ssl_certification">TLS/SSL Certification</h3>
<div class="paragraph">
<p>The oVirt API requires Hypertext Transfer Protocol Secure
(HTTPS) <span class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnote_1" title="View footnote.">1</a>]</span> for secure
interaction with client software, such as the SDK and CLI components.
This involves a process of obtaining the certificate of the
<a href="https://en.wikipedia.org/wiki/Certificate_authority">CA</a> used by the
server, and importing it into the certificate store of your client.</p>
</div>
<div class="sect3">
<h4 id="_obtaining_the_ca_certificate">Obtaining the CA certificate</h4>
<div class="paragraph">
<p>You can obtain the CA certificate from the oVirt Engine and transfer it
to the client machine using one of these methods:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Method 1</dt>
<dd>
<p>The preferred method to obtain the CA certificate used by the
oVirt server is to use the <code>openssl s_client</code> command line tool
to perform a real TLS handshake with the server, and then extract the
certificates that it presents. Run a command like this:</p>
<div class="literalblock">
<div class="content">
<pre>$ openssl s_client \
-connect myengine.example.com:443 \
-showcerts \
< /dev/null</pre>
</div>
</div>
<div class="paragraph">
<p>That will connect to the server and will display an output similar to
this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>CONNECTED(00000003)
depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416
verify error:num=19:self signed certificate in certificate chain
---
Certificate chain
0 s:/C=US/O=Example Inc./CN=myengine.example.com
i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
-----END CERTIFICATE-----
1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416
i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----</pre>
</div>
</div>
<div class="paragraph">
<p>The text between the <code>-----BEGIN CERTIFICATE-----</code> and <code>-----END
CERTIFICATE-----</code> marks are the certificates presented by the server.
The first one is the certificate of the server itself, and the last one
is the certificate of the CA. Copy that CA certificate, including the
marks, to the <code>ca.crt</code> file. The result should look like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----</pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
This is most reliable method to obtain the CA certificate
actually used by the server. The rest of the methods described here will
work in most cases, but they won’t obtain the correct CA certificate if
it has been manually replaced by the administrator of the server.
</td>
</tr>
</table>
</div>
</dd>
<dt class="hdlist1">Method 2</dt>
<dd>
<p>If you can’t use the <code>openssl s_client</code> method described
above, you can instead use a command line tool to download the CA
certificate from the engine.</p>
<div class="paragraph">
<p>Examples of command line tools include <code>curl</code> and <code>wget</code>, both of which
are available on multiple platforms.</p>
</div>
<div class="paragraph">
<p>If using <code>curl</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ curl \
--output ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'</pre>
</div>
</div>
<div class="paragraph">
<p>If using <code>wget</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ wget \
--output-document ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'</pre>
</div>
</div>
</dd>
<dt class="hdlist1">Method 3</dt>
<dd>
<p>Use a web browser to navigate to the certificate located
at:</p>
<div class="literalblock">
<div class="content">
<pre>https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA</pre>
</div>
</div>
<div class="paragraph">
<p>Depending on the chosen browser, the certificate either downloads or
imports into the browser’s keystore.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><strong>If the browser downloads the certificate</strong>: save the file as
<code>ca.crt</code>.</p>
</li>
<li>
<p><strong>If the browser imports the certificate</strong>: export it from the
browser’s certification options and save it as <code>ca.crt</code>.</p>
</li>
</ol>
</div>
</dd>
<dt class="hdlist1">Method 4</dt>
<dd>
<p>Log in to the engine, export the certificate from the
truststore and copy it to your client machine.</p>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Log in to the engine machine as the <code>root</code> user.</p>
</li>
<li>
<p>Export the certificate from the truststore using the Java
<code>keytool</code> management utility:</p>
<div class="literalblock">
<div class="content">
<pre># keytool \
-keystore /etc/pki/ovirt-engine/.truststore \
-storepass mypass \
-exportcert \
-alias cacert \
-rfc \
-file ca.crt</pre>
</div>
</div>
<div class="paragraph">
<p>This creates a certificate file called <code>ca.crt</code>.</p>
</div>
</li>
<li>
<p>Copy the certificate to the client machine using the <code>scp</code>
command:</p>
<div class="literalblock">
<div class="content">
<pre>$ scp ca.crt myuser@myclient.example.com:/home/myuser/.</pre>
</div>
</div>
</li>
</ol>
</div>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Each of these methods results in a certificate file named <code>ca.crt</code> on
your client machine. An API user imports this file into the certificate
store of the client.</p>
</div>
</div>
<div class="sect3">
<h4 id="_importing_a_certificate_to_a_client">Importing a certificate to a client</h4>
<div class="paragraph">
<p>Importing a certificate to a client relies on how the client itself
stores and interprets certificates. This guide contains some examples on
importing certificates. For clients not using Network Security Services
(NSS) or Java KeyStore (JKS), see your client documentation for more
information on importing a certificate.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_authentication">Authentication</h3>
<div class="paragraph">
<p>Any user with an oVirt Engine account has access to the API. All
requests need to be authenticated using either <em>OAuth</em> or basic
authentication, as described below.</p>
</div>
<div class="sect3">
<h4 id="_oauth_authentication">OAuth authentication</h4>
<div class="paragraph">
<p>Since version 4.0 of oVirt the preferred authentication
mechanism is <a href="https://oauth.net/2"><em>OAuth 2.0</em></a>, as described in
<a href="https://tools.ietf.org/html/rfc6749">RFC 6749</a>.</p>
</div>
<div class="paragraph">
<p><em>OAuth</em> is a sophisticated protocol, with several mechanism to obtain
authorization and access tokens. But for usage with the oVirt
API the only supported one is the <em>resource owner password credentials
grant</em>, as described in <a href="https://tools.ietf.org/html/rfc6749#section-4.3">section 4.3</a>
of that RFC.</p>
</div>
<div class="paragraph">
<p>The first step in the <em>OAuth</em> authentication process is to obtain a
<em>token</em>, sending the user name and password to the single sign-on
service of the engine:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>POST /ovirt-engine/sso/oauth/token HTTP/1.1
Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json</pre>
</div>
</div>
<div class="paragraph">
<p>The request body must contain the <code>grant_type</code>, <code>scope</code>, <code>username</code>
and <code>password</code> parameters:</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">Table 1. OAuth token request parameters</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>grant_type</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>password</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>scope</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ovirt-app-api</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>username</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>admin@internal</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>password</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mypassword</code></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>These parameters must be
<a href="https://en.wikipedia.org/wiki/Percent-encoding">URL-encoded</a>. For example
the <code>@</code> character in the user name needs to be encoded as <code>%40</code>. So the
resulting request body will be something like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword</pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
The <code>scope</code> parameter is described as optional in the <em>OAuth</em>
RFC, but when using it with the oVirt API it is mandatory, and
its value must be <code>ovirt-app-api</code>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If the user name and password are valid the single sign-on service of
the engine will respond with a JSON document similar to this one:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
"access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
"token_type": "bearer",
"scope": "...",
...
}</pre>
</div>
</div>
<div class="paragraph">
<p>For API authentication purposes the only relevant name/value pair is the
<code>access_token</code>. Don’t manipulate this in any way, use it exactly as
provided by the SSO service.</p>
</div>
<div class="paragraph">
<p>Once the token has been obtained, it can be used to perform requests to
the API, including it in the HTTP <code>Authorization</code> header, and using the
<code>Bearer</code> scheme. For example, to get the list of virtual machines using
this token, send a request like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Accept: application/xml
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=</pre>
</div>
</div>
<div class="paragraph">
<p>The token can be used multiple times, for multiple requests, but it will
eventually expire. When it expires the server will reject the request,
and will use the 401 HTTP response code to indicate so:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>HTTP/1.1 401 Unauthorized</pre>
</div>
</div>
<div class="paragraph">
<p>When this happens a new token is needed, and can be requested using the
same procedure described above, as the single sign-on service of the
engine doesn’t currently support refresh tokens.</p>
</div>
</div>
<div class="sect3">
<h4 id="_basic_authentication">Basic authentication</h4>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Basic authentication is still supported only for backwards
compatibility, but it is deprecated since version 4.0 of oVirt,
and will be removed in the future.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Each request uses HTTP Basic Authentication <span class="footnote">[<a id="_footnoteref_2" class="footnote" href="#_footnote_2" title="View footnote.">2</a>]</span> to
encode the credentials. If a request does not include an appropriate
<code>Authorization</code> header, the server sends a <code>401 Authorization Required</code> as
a result:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
HTTP/1.1 401 Authorization Required</pre>
</div>
</div>
<div class="paragraph">
<p>Request are issued with an <code>Authorization</code> header for the specified
realm. An API user encodes an appropriate oVirt Engine domain and user
in the supplied credentials with the <code>username@domain:password</code>
convention.</p>
</div>
<div class="paragraph">
<p>The following table shows the process for encoding credentials in
<a href="https://tools.ietf.org/html/rfc4648">Base64</a>.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">Table 2. Encoding credentials for API access</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Item</th>
<th class="tableblock halign-left valign-top">Value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">User name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>admin</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Domain</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>internal</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Password</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mypassword</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Unencoded credentials</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>admin@internal:mypassword</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Base64 encoded credentials</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==</code></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>An API user provides the Base64 encoded credentials as shown:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
HTTP/1.1 200 OK</pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Basic authentication involves potentially sensitive
information, such as passwords, sent as plain text. API requires
Hypertext Transfer Protocol Secure (HTTPS) for transport-level
encryption of plain-text requests.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<div class="title">Important</div>
</td>
<td class="content">
Some Base64 libraries break the result into multiple lines
and terminate each line with a newline character. This breaks the header
and causes a faulty request. The <code>Authorization</code> header requires the
encoded credentials on a single line within the header.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_authentication_sessions">Authentication sessions</h4>
<div class="paragraph">
<p>The API also provides the ability for authentication session support. An
API user sends an initial request with authentication details, then
sends all subsequent requests using a session cookie to authenticate.
The following procedure demonstrates how to use an authenticated
session.</p>
</div>
<div class="sect4">
<h5 id="_requesting_an_authenticated_session">Requesting an authenticated session</h5>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Send a request with the <code>Authorization</code> and <code>Prefer: persistent-auth</code>
headers:</p>
<div class="literalblock">
<div class="content">
<pre>HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
Prefer: persistent-auth
HTTP/1.1 200 OK
...</pre>
</div>
</div>
<div class="paragraph">
<p>This returns a response with the following header:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure</pre>
</div>
</div>
<div class="paragraph">
<p>Note the <code>JSESSIONID=</code> value. In this example the value is
<code>5dQja5ubr4yvI2MM2z+LZxrK</code>.</p>
</div>
</li>
<li>
<p>Send all subsequent requests with the <code>Prefer: persistent-auth</code> and
<code>Cookie</code> headers with the <code>JSESSIONID=</code> value. The `Authorization header
is no longer needed when using an authenticated session.</p>
<div class="literalblock">
<div class="content">
<pre>HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Prefer: persistent-auth
Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK
HTTP/1.1 200 OK
...</pre>
</div>
</div>
</li>
<li>
<p>When the session is no longer required, perform a request to the
sever without the <code>Prefer: persistent-auth</code> header.</p>
<div class="literalblock">
<div class="content">
<pre>HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
HTTP/1.1 200 OK
...</pre>
</div>
</div>
</li>
</ol>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footnotes">
<hr>
<div class="footnote" id="_footnote_1">
<a href="#_footnoteref_1">1</a> HTTPS is described in <a href="http://tools.ietf.org/html/rfc2818">RFC 2818 HTTP Over TLS.</a>
</div>
<div class="footnote" id="_footnote_2">
<a href="#_footnoteref_2">2</a> Basic Authentication is described in <a href="http://tools.ietf.org/html/rfc2617">RFC 2617 HTTP Authentication: Basic and Digest Access Authentication</a>.
</div>
</div>
a01_primitive_types
<div class="sect1">
<h2 id="_primitive_types">Appendix A: Primitive types</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This section describes the primitive data types supported by the API.</p>
</div>
<div class="sect2">
<h3 id="types/string">String <span class="small">primitive</span></h3>
<div class="paragraph">
<p>A finite sequence of <a href="http://unicode.org">Unicode</a> characters.</p>
</div>
</div>
<div class="sect2">
<h3 id="types/boolean">Boolean <span class="small">primitive</span></h3>
<div class="paragraph">
<p>Represents the <em>false</em> and <em>true</em> concepts used in mathematical logic.</p>
</div>
<div class="paragraph">
<p>The valid values are the strings <code>false</code> and <code>true</code>.</p>
</div>
<div class="paragraph">
<p>Case is ignored by the engine, so for example <code>False</code> and <code>FALSE</code> also
valid values. However the server will always return lower case values.</p>
</div>
<div class="paragraph">
<p>For backwards compatibility with older versions of the engine, the
values <code>0</code> and <code>1</code> are also accepted. The value <code>0</code> has the same meaning
than <code>false</code>, and <code>1</code> has the same meaning than <code>true</code>. Try to avoid
using these values, as support for them may be removed in the future.</p>
</div>
</div>
<div class="sect2">
<h3 id="types/integer">Integer <span class="small">primitive</span></h3>
<div class="paragraph">
<p>Represents the mathematical concept of integer number.</p>
</div>
<div class="paragraph">
<p>The valid values are finite sequences of decimal digits.</p>
</div>
<div class="paragraph">
<p>Currently the engine implements this type using a signed 32 bit
integer, so the minimum value is -2<sup>31</sup> (-2147483648) and the maximum
value is 2<sup>31</sup>-1 (2147483647).</p>
</div>
<div class="paragraph">
<p>However, there are some attributes in the system where the range of
values possible with 32 bit isn’t enough. In those exceptional cases
the engine uses 64 bit integers, in particular for the following
attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>Disk.actual_size</code></p>
</li>
<li>
<p><code>Disk.provisioned_size</code></p>
</li>
<li>
<p><code>GlusterClient.bytes_read</code></p>
</li>
<li>
<p><code>GlusterClient.bytes_written</code></p>
</li>
<li>
<p><code>Host.max_scheduling_memory</code></p>
</li>
<li>
<p><code>Host.memory</code></p>
</li>
<li>
<p><code>HostNic.speed</code></p>
</li>
<li>
<p><code>LogicalUnit.size</code></p>
</li>
<li>
<p><code>MemoryPolicy.guaranteed</code></p>
</li>
<li>
<p><code>NumaNode.memory</code></p>
</li>
<li>
<p><code>QuotaStorageLimit.limit</code></p>
</li>
<li>
<p><code>StorageDomain.available</code></p>
</li>
<li>
<p><code>StorageDomain.used</code></p>
</li>
<li>
<p><code>StorageDomain.committed</code></p>
</li>
<li>
<p><code>VmBase.memory</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For these exception cases the minimum value is -2<sup>63</sup>
(-9223372036854775808) and the maximum value is 2<sup>63</sup>-1
(9223372036854775807).</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
In the future the integer type will be implemented using
unlimited precission integers, so the above limitations and exceptions
will eventually disappear.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="types/decimal">Decimal <span class="small">primitive</span></h3>
<div class="paragraph">
<p>Represents the mathematical concept of real number.</p>
</div>
<div class="paragraph">
<p>Currently the engine implements this type using 32 bit
<a href="https://en.wikipedia.org/wiki/IEEE_floating_point">IEEE 754</a> single
precission floating point numbers.</p>
</div>
<div class="paragraph">
<p>For some attributes this isn’t enough precission. In those exceptional
cases the engine uses 64 bit double precission floating point numbers,
in particular for the following attributes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>QuotaStorageLimit.usage</code></p>
</li>
<li>
<p><code>QuotaStorageLimit.memory_limit</code></p>
</li>
<li>
<p><code>QuotaStorageLimit.memory_usage</code></p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
In the future the decimal type will be implemented using unlimited
precission decimal numbers, so the above limitations and exceptions will
eventually disappear.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="types/date">Date <span class="small">primitive</span></h3>
<div class="paragraph">
<p>Represents a date and time.</p>
</div>
<div class="paragraph">
<p>The format returned by the engine is the one described in the
<a href="https://www.w3.org/TR/xmlschema11-2/#dateTime">XML Schema specification</a>
when requesting XML. For example, if you send a request like this to
retrieve the XML representation of a virtual machine:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/vms/123
Accept: application/xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>The response body will contain the following XML document:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml"><vm id="123" href="/ovirt-engine/api/vms/123">
...
<creation_time>2016-09-08T09:53:35.138+02:00</creation_time>
...
</vm></code></pre>
</div>
</div>
<div class="paragraph">
<p>When requesting the JSON representation the engine uses a different,
format: an integer containg the number of seconds since Jan 1<sup>st</sup> 1970,
also know as <a href="https://en.wikipedia.org/wiki/Unix_time"><em>epoch time</em></a>. For
example, if you send a request like this to retrieve the JSON
representation of a virtual machine:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>GET /ovirt-engine/api/vms/123
Accept: application/json</code></pre>
</div>
</div>
<div class="paragraph">
<p>The response body will contain the following JSON document:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-json" data-lang="json">{
"id": "123",
"href="/ovirt-engine/api/vms/123",
...
"creation_time": 1472564909990,
...
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
In both cases, the dates returned by the engine use the time zone
configured in the server where it is running, in the above examples it
is UTC+2.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
001_introduction
<div class="sect1">
<h2 id="_introduction">Introduction</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The oVirt Engine provides a <strong>Representational State Transfer (REST)
API</strong>. The API provides software developers and system administrators
with control over their oVirt environment outside of the
standard web interface. The API is useful for developers and
administrators who aim to integrate the functionality of an
oVirt environment with custom scripts or external applications
that access the API via the standard Hypertext Transfer Protocol (HTTP).</p>
</div>
<div class="paragraph">
<p>The benefits of the API are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Broad client support - Any programming language, framework, or
system with support for HTTP protocol can use the API.</p>
</li>
<li>
<p>Self descriptive - Client applications require minimal knowledge of
the virtualization infrastructure as many details are discovered at
runtime;</p>
</li>
<li>
<p>Resource-based model - The resource-based REST model provides a
natural way to manage a virtualization platform.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This provides developers and administrators with the ability to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Integrate with enterprise IT systems.</p>
</li>
<li>
<p>Integrate with third-party virtualization software.</p>
</li>
<li>
<p>Perform automated maintenance or error checking tasks.</p>
</li>
<li>
<p>Automate repetitive tasks in an oVirt environment with
scripts.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This documentation acts as a reference to the oVirt API. It
aims to provide developers and administrators with instructions and
examples to help harness the functionality of their oVirt
environment through the API either directly or using the provided SDKs.</p>
</div>
<div class="sect2">
<h3 id="_representational_state_transfer">Representational State Transfer</h3>
<div class="paragraph">
<p><strong>Representational State Transfer (REST)</strong> is a design architecture that
focuses on resources for a specific service and their representations. A
resource representation is a key abstraction of information that
corresponds to one specific managed element on a server. A client sends
a request to a server element located at a Uniform Resource Identifier
(URI) and performs operations with standard HTTP methods, such as GET,
POST, PUT, and DELETE. This provides a stateless communication
between the client and server where each request acts independent of any
other request and contains all necessary information to complete the
request.</p>
</div>
</div>
<div class="sect2">
<h3 id="_api_prerequisites">API Prerequisites</h3>
<div class="paragraph">
<p>Prerequisites for using the oVirt API:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A networked installation of oVirt Engine, which includes the API.</p>
</li>
<li>
<p>A client or programming library that initiates and receives HTTP requests
from the API server. For example:</p>
<div class="ulist">
<ul>
<li>
<p>The <a href="https://github.com/oVirt/ovirt-engine-sdk/tree/master/sdk">oVirt Python SDK</a>.</p>
</li>
<li>
<p>The <a href="https://github.com/oVirt/ovirt-engine-sdk-ruby/tree/master/sdk">oVirt Ruby SDK</a>.</p>
</li>
<li>
<p>The <a href="https://github.com/oVirt/ovirt-engine-sdk-java/tree/master/sdk">oVirt Java SDK</a>.</p>
</li>
<li>
<p>The <a href="https://curl.haxx.se">curl</a> command line tool.</p>
</li>
<li>
<p><a href="https://addons.mozilla.org/en-US/firefox/addon/restclient">RESTClient</a>, a
debugger for RESTful web services.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Knowledge of Hypertext Transfer Protocol (HTTP), which is the protocol
used for REST API interactions. The Internet Engineering Task Force provides
a Request for Comments (RFC) explaining the Hypertext Transfer Protocol
at <a href="http://www.ietf.org/rfc/rfc2616.txt" class="bare">http://www.ietf.org/rfc/rfc2616.txt</a>.</p>
</li>
<li>
<p>Knowledge of Extensible Markup Language (XML) or JavaScript Object
Notation (JSON), which the API uses to construct resource representations.
The W3C provides a full specification on XML at <a href="http://www.w3.org/TR/xml" class="bare">http://www.w3.org/TR/xml</a>.
ECMA International provide a free publication on JSON at
<a href="http://www.ecma-international.org" class="bare">http://www.ecma-international.org</a>.</p>
</li>
</ul>
</div>
</div>
</div>
</div>