Chapter 7. Types Red Hat Virtualization 4.2

7.1. AccessProtocol enum

Represents the access protocols supported by Gluster volumes. gluster and nfs are enabled by default.

Table 7.1. Values summary

Name	Summary
`cifs`	CIFS access protocol.
`gluster`	Gluster access protocol.
`nfs`	NFS access protocol.

7.2. Action struct

Table 7.2. Attributes summary

Name	Type	Summary
`allow_partial_import`	Boolean
`async`	Boolean
`attachment`	DiskAttachment
`authorized_key`	AuthorizedKey
`bricks`	GlusterBrick[]
`certificates`	Certificate[]
`check_connectivity`	Boolean
`clone`	Boolean
`clone_permissions`	Boolean
`cluster`	Cluster
`collapse_snapshots`	Boolean
`comment`	String	Free text containing comments about this object.
`connection`	StorageConnection
`connectivity_timeout`	Integer
`data_center`	DataCenter
`deploy_hosted_engine`	Boolean
`description`	String	A human-readable description in plain text.
`details`	GlusterVolumeProfileDetails
`directory`	String
`discard_snapshots`	Boolean
`discovered_targets`	IscsiDetails[]
`disk`	Disk
`disk_profile`	DiskProfile
`disks`	Disk[]
`exclusive`	Boolean
`fault`	Fault
`fence_type`	String
`filename`	String
`filter`	Boolean
`fix_layout`	Boolean
`force`	Boolean
`grace_period`	GracePeriod
`host`	Host
`id`	String	A unique identifier.
`image`	String
`image_transfer`	ImageTransfer
`import_as_template`	Boolean
`is_attached`	Boolean
`iscsi`	IscsiDetails
`iscsi_targets`	String[]
`job`	Job
`lease`	StorageDomainLease
`logical_units`	LogicalUnit[]
`maintenance_enabled`	Boolean
`modified_bonds`	HostNic[]
`modified_labels`	NetworkLabel[]
`modified_network_attachments`	NetworkAttachment[]
`name`	String	A human-readable name in plain text.
`option`	Option
`pause`	Boolean
`permission`	Permission
`power_management`	PowerManagement
`proxy_ticket`	ProxyTicket
`quota`	Quota
`reason`	String
`reassign_bad_macs`	Boolean
`reboot`	Boolean
`registration_configuration`	RegistrationConfiguration
`remote_viewer_connection_file`	String
`removed_bonds`	HostNic[]
`removed_labels`	NetworkLabel[]
`removed_network_attachments`	NetworkAttachment[]
`resolution_type`	String
`restore_memory`	Boolean
`root_password`	String
`seal`	Boolean
`snapshot`	Snapshot
`ssh`	Ssh
`status`	String
`stop_gluster_service`	Boolean
`storage_domain`	StorageDomain
`storage_domains`	StorageDomain[]
`succeeded`	Boolean
`synchronized_network_attachments`	NetworkAttachment[]
`template`	Template
`ticket`	Ticket
`undeploy_hosted_engine`	Boolean
`use_cloud_init`	Boolean
`use_sysprep`	Boolean
`virtual_functions_configuration`	HostNicVirtualFunctionsConfiguration
`vm`	Vm
`vnic_profile_mappings`	VnicProfileMapping[]
`volatile`	Boolean

7.3. AffinityGroup struct

An affinity group represents a group of virtual machines with a defined relationship.

Table 7.3. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`enforcing`	Boolean	Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines that are members of that affinity group.
`hosts_rule`	AffinityRule	Specifies the affinity rule applied between virtual machines and hosts that are members of this affinity group.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`positive`	Boolean	Specifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are members of that affinity group.
`vms_rule`	AffinityRule	Specifies the affinity rule applied to virtual machines that are members of this affinity group.

7.3.1. enforcing

Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to virtual machines that are members of that affinity group.

Warning

Please note that this attribute has been deprecated since version 4.1 of the engine, and will be removed in the future. Use the vms_rule attribute from now on.

7.3.2. positive

Specifies whether the affinity group applies positive affinity or negative affinity to virtual machines that are members of that affinity group.

Warning

Please note that this attribute has been deprecated since version 4.1 of the engine, and will be removed in the future. Use the vms_rule attribute from now on.

Table 7.4. Links summary

Name	Type	Summary
`cluster`	Cluster	A reference to the cluster to which the affinity group applies.
`hosts`	Host[]	A list of all hosts assigned to this affinity group.
`vms`	Vm[]	A list of all virtual machines assigned to this affinity group.

7.4. AffinityLabel struct

The affinity label can influence virtual machine scheduling. It is most frequently used to create a sub-cluster from the available hosts.

Table 7.5. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`read_only`	Boolean	The `read_only` property marks a label that can not be modified.

7.4.1. read_only

The read_only property marks a label that can not be modified. This is usually the case when listing internally-generated labels.

Table 7.6. Links summary

Name	Type	Summary
`hosts`	Host[]	A list of hosts that were labeled using this scheduling label.
`vms`	Vm[]	A list of virtual machines that were labeled using this scheduling label.

7.5. AffinityRule struct

Generic rule definition for affinity group. Each supported resource type (virtual machine, host) is controlled by a separate rule. This allows expressing of rules like: no affinity between defined virtual machines, but hard affinity between defined virtual machines and virtual hosts.

Table 7.7. Attributes summary

Name	Type	Summary
`enabled`	Boolean	Specifies whether the affinity group uses this rule or not.
`enforcing`	Boolean	Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to the resources that are controlled by this rule.
`positive`	Boolean	Specifies whether the affinity group applies positive affinity or negative affinity to the resources that are controlled by this rule.

7.5.1. enabled

Specifies whether the affinity group uses this rule or not. This attribute is optional during creation and is considered to be true when it is not provided. In case this attribute is not provided to the update operation, it is considered to be true if AffinityGroup positive attribute is set as well. The backend enabled value will be preserved when both enabled and positive attributes are missing.

7.5.2. enforcing

Specifies whether the affinity group uses hard or soft enforcement of the affinity applied to the resources that are controlled by this rule. This argument is mandatory if the rule is enabled and is ignored when the rule is disabled.

7.5.3. positive

Specifies whether the affinity group applies positive affinity or negative affinity to the resources that are controlled by this rule. This argument is mandatory if the rule is enabled and is ignored when the rule is disabled.

7.6. Agent struct

Type representing a fence agent.

Table 7.8. Attributes summary

Name	Type	Summary
`address`	String	Fence agent address.
`comment`	String	Free text containing comments about this object.
`concurrent`	Boolean	Specifies whether the agent should be used concurrently or sequentially.
`description`	String	A human-readable description in plain text.
`encrypt_options`	Boolean	Specifies whether the options should be encrypted.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`options`	Option[]	Fence agent options (comma-delimited list of key-value pairs).
`order`	Integer	The order of this agent if used with other agents.
`password`	String	Fence agent password.
`port`	Integer	Fence agent port.
`type`	String	Fence agent type.
`username`	String	Fence agent user name.

Table 7.9. Links summary

Name	Type	Summary
`host`	Host	Reference to the host service.

7.6.1. host

Reference to the host service. Each fence agent belongs to a single host.

7.7. AgentConfiguration struct

Table 7.10. Attributes summary

Name	Type	Summary
`address`	String
`broker_type`	MessageBrokerType
`network_mappings`	String
`password`	String
`port`	Integer
`username`	String

7.8. Api struct

This type contains the information returned by the root service of the API.

To get that information send a request like this:

GET /ovirt-engine/api

The result will be like this:

<api>
  <link rel="hosts" href="/ovirt-engine/api/hosts"/>
  <link rel="vms" href="/ovirt-engine/api/vms"/>
  ...
  <product_info>
    <name>oVirt Engine</name>
    <vendor>ovirt.org</vendor>
    <version>
      <build>0</build>
      <full_version>4.1.0_master</full_version>
      <major>4</major>
      <minor>1</minor>
      <revision>0</revision>
    </version>
  </product_info>
  <special_objects>
    <link rel="templates/blank" href="..."/>
    <link rel="tags/root" href="..."/>
  </special_objects>
  <summary>
    <vms>
      <total>10</total>
      <active>3</active>
    </vms>
    <hosts>
      <total>2</total>
      <active>2</active>
    </hosts>
    <users>
      <total>8</total>
      <active>2</active>
    </users>
    <storage_domains>
      <total>2</total>
      <active>2</active>
    </storage_domains>
  </summary>
  <time>2016-12-12T12:22:25.866+01:00</time>
</api>

Table 7.11. Attributes summary

Name	Type	Summary
`product_info`	ProductInfo	Information about the product, such as its name, the name of the vendor, and the version.
`special_objects`	SpecialObjects	References to special objects, such as the blank template and the root of the hierarchy of tags.
`summary`	ApiSummary	A summary containing the total number of relevant objects, such as virtual machines, hosts, and storage domains.
`time`	Date	The date and time when this information was generated.

Table 7.12. Links summary

Name	Type	Summary
`authenticated_user`	User	Reference to the authenticated user.
`effective_user`	User	Reference to the effective user.

7.8.1. authenticated_user

Reference to the authenticated user.

The authenticated user is the user whose credentials were verified in order to accept the current request. In the current version of the system the authenticated user and the effective user are always the same. In the future, when support for user impersonation is introduced, they will be potentially different.

7.8.2. effective_user

Reference to the effective user.

The effective user is the user whose permissions apply during the current request. In the current version of the system the authenticated user and the effective user are always the same. In the future, when support for user impersonation is introduced, they will be potentially different.

7.9. ApiSummary struct

A summary containing the total number of relevant objects, such as virtual machines, hosts, and storage domains.

Table 7.13. Attributes summary

Name	Type	Summary
`hosts`	ApiSummaryItem	The summary of hosts.
`storage_domains`	ApiSummaryItem	The summary of storage domains.
`users`	ApiSummaryItem	The summary of users.
`vms`	ApiSummaryItem	The summary of virtual machines.

7.10. ApiSummaryItem struct

This type contains an item of the API summary. Each item contains the total and active number of some kind of object.

Table 7.14. Attributes summary

Name	Type	Summary
`active`	Integer	The total number of active objects.
`total`	Integer	The total number of objects.

7.11. Application struct

Represents an application installed on a virtual machine. Applications are reported by the guest agent, if you deploy one on the virtual machine operating system.

To get that information send a request like this:

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

The result will be like this:

<application href="/ovirt-engine/api/vms/123/applications/456" id="456">
  <name>application-test-1.0.0-0.el7</name>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
</application>

Table 7.15. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.16. Links summary

Name	Type	Summary
`vm`	Vm	A reference to the virtual machine the application is installed on.

7.12. Architecture enum

Table 7.17. Values summary

Name	Summary
`ppc64`
`s390x`	IBM S390X CPU architecture.
`undefined`
`x86_64`

7.12.1. s390x

IBM S390X CPU architecture.

Needs to be specified for virtual machines and clusters running on the S390X architecture.

Note that S390 is often used in an ambiguous way to describe either the general machine architecture as such or its 31-bit variant. S390X is used specifically for the 64-bit architecture, which is in line with the other architectures, like X86_64 or PPC64.

7.13. AuthorizedKey struct

Table 7.18. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`key`	String
`name`	String	A human-readable name in plain text.

Table 7.19. Links summary

Name	Type	Summary
`user`	User

7.14. AutoNumaStatus enum

Table 7.20. Values summary

Name	Summary
`disable`
`enable`
`unknown`

7.15. Balance struct

Table 7.21. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.22. Links summary

Name	Type	Summary
`scheduling_policy`	SchedulingPolicy
`scheduling_policy_unit`	SchedulingPolicyUnit

7.16. Bios struct

Table 7.23. Attributes summary

Name	Type	Summary
`boot_menu`	BootMenu

7.17. BlockStatistic struct

Table 7.24. Attributes summary

Name	Type	Summary
`statistics`	Statistic[]

7.18. Bonding struct

Represents a network interfaces bond.

Table 7.25. Attributes summary

Name	Type	Summary
`ad_partner_mac`	Mac	The `ad_partner_mac` property of the partner bond in mode 4.
`options`	Option[]	A list of option elements for a bonded interface.
`slaves`	HostNic[]	A list of slave NICs for a bonded interface.

7.18.1. ad_partner_mac

The ad_partner_mac property of the partner bond in mode 4. Bond mode 4 is the 802.3ad standard, which is also called dynamic link aggregation. See Wikipedia and Presentation for more information. 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.

7.18.2. options

A list of option elements for a bonded interface. Each option contains property name and value attributes. Only required when adding bonded interfaces.

7.18.3. slaves

A list of slave NICs for a bonded interface. Only required when adding bonded interfaces.

Table 7.26. Links summary

Name	Type	Summary
`active_slave`	HostNic	The `active_slave` property of the bond in modes that support it (active-backup, balance-alb and balance-tlb).

7.18.4. active_slave

The active_slave property of the bond in modes that support it (active-backup, balance-alb and balance-tlb). See Linux documentation for further details. This parameter is read-only. Setting it will have no effect on the bond. It is retrieved from /sys/class/net/bondX/bonding/active_slave file on the system where the bond is located.

For example:

GET /ovirt-engine/api/hosts/123/nics/321

Will respond:

<host_nic href="/ovirt-engine/api/hosts/123/nics/321" id="321">
  ...
  <bonding>
    <slaves>
      <host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456" />
      ...
    </slaves>
    <active_slave href="/ovirt-engine/api/hosts/123/nics/456" id="456" />
  </bonding>
  ...
</host_nic>

7.19. Bookmark struct

Represents a bookmark in the system.

Table 7.27. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`value`	String	The bookmark value, representing a search in the engine.

7.20. Boot struct

Configuration of the boot sequence of a virtual machine.

Table 7.28. Attributes summary

Name	Type	Summary
`devices`	BootDevice[]	Ordered list of boot devices.

7.20.1. devices

Ordered list of boot devices. The virtual machine will try to boot from the given boot devices, in the given order.

7.21. BootDevice enum

Represents the kinds of devices that a virtual machine can boot from.

Table 7.29. Values summary

Name	Summary
`cdrom`	Boot from CD-ROM.
`hd`	Boot from the hard drive.
`network`	Boot from the network, using PXE.

7.21.1. cdrom

Boot from CD-ROM. The CD-ROM can be chosen from the list of ISO files available in an ISO domain attached to the ata center that the virtual machine belongs to.

7.21.2. network

Boot from the network, using PXE. It is necessary to have PXE configured on the network that the virtual machine is connected to.

7.22. BootMenu struct

Represents boot menu configuration for virtual machines and templates.

Table 7.30. Attributes summary

Name	Type	Summary
`enabled`	Boolean	Whether the boot menu is enabled for this virtual machine (or template), or not.

7.23. BootProtocol enum

Defines the options of the IP address assignment method to a NIC.

Table 7.31. Values summary

Name	Summary
`autoconf`	Stateless address auto-configuration.
`dhcp`	Dynamic host configuration protocol.
`none`	No address configuration.
`poly_dhcp_autoconf`	DHCP alongside Stateless address auto-configuration (SLAAC) The SLAAC mechanism is defined by http://tools.
`static`	Statically-defined address, mask and gateway.

7.23.1. autoconf

Stateless address auto-configuration.

The mechanism is defined by RFC 4862. Please refer to this wikipedia article for more information.

Note

The value is valid for IPv6 addresses only.

7.23.2. dhcp

Dynamic host configuration protocol.

Please refer to this wikipedia article for more information.

7.23.3. poly_dhcp_autoconf

DHCP alongside Stateless address auto-configuration (SLAAC)

The SLAAC mechanism is defined by RFC 4862. Please refer to the Stateless address auto-configuration article and the DHCP article for more information.

Note

The value is valid for IPv6 addresses only.

7.24. BrickProfileDetail struct

Table 7.32. Attributes summary

Name	Type	Summary
`profile_details`	ProfileDetail[]

Table 7.33. Links summary

Name	Type	Summary
`brick`	GlusterBrick

7.25. Cdrom struct

Table 7.34. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`file`	File
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.35. Links summary

Name	Type	Summary
`instance_type`	InstanceType	Optionally references to an instance type the device is used by.
`template`	Template	Optionally references to a template the device is used by.
`vm`	Vm	Don’t use this element, use `vms` instead.
`vms`	Vm[]	References to the virtual machines that are using this device.

7.25.1. vms

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.

7.26. Certificate struct

Table 7.36. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`content`	String
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`organization`	String
`subject`	String

7.27. CloudInit struct

Deprecated type to specify cloud-init configuration.

This type has been deprecated and replaced by alternative attributes inside the Initialization type. See the cloud_init attribute documentation for details.

Table 7.37. Attributes summary

Name	Type	Summary
`authorized_keys`	AuthorizedKey[]
`files`	File[]
`host`	Host
`network_configuration`	NetworkConfiguration
`regenerate_ssh_keys`	Boolean
`timezone`	String
`users`	User[]

7.28. Cluster struct

Type representation of a cluster.

A JSON representation of a cluster:

{
  "cluster" : [ {
    "ballooning_enabled" : "false",
    "cpu" : {
      "architecture" : "x86_64",
      "type" : "Intel SandyBridge Family"
    },
    "custom_scheduling_policy_properties" : {
      "property" : [ {
        "name" : "HighUtilization",
        "value" : "80"
      }, {
        "name" : "CpuOverCommitDurationMinutes",
        "value" : "2"
      } ]
    },
    "error_handling" : {
      "on_error" : "migrate"
    },
    "fencing_policy" : {
      "enabled" : "true",
      "skip_if_connectivity_broken" : {
        "enabled" : "false",
        "threshold" : "50"
      },
      "skip_if_gluster_bricks_up" : "false",
      "skip_if_gluster_quorum_not_met" : "false",
      "skip_if_sd_active" : {
        "enabled" : "false"
      }
    },
    "gluster_service" : "false",
    "firewall_type" : "iptables",
    "ha_reservation" : "false",
    "ksm" : {
      "enabled" : "true",
      "merge_across_nodes" : "true"
    },
    "maintenance_reason_required" : "false",
    "memory_policy" : {
      "over_commit" : {
        "percent" : "100"
      },
      "transparent_hugepages" : {
        "enabled" : "true"
      }
    },
    "migration" : {
      "auto_converge" : "inherit",
      "bandwidth" : {
        "assignment_method" : "auto"
      },
      "compressed" : "inherit",
      "policy" : {
        "id" : "00000000-0000-0000-0000-000000000000"
      }
    },
    "optional_reason" : "false",
    "required_rng_sources" : {
      "required_rng_source" : [ "random" ]
    },
    "switch_type" : "legacy",
    "threads_as_cores" : "false",
    "trusted_service" : "false",
    "tunnel_migration" : "false",
    "version" : {
      "major" : "4",
      "minor" : "1"
    },
    "virt_service" : "true",
    "data_center" : {
      "href" : "/ovirt-engine/api/datacenters/123",
      "id" : "123"
    },
    "mac_pool" : {
      "href" : "/ovirt-engine/api/macpools/456",
      "id" : "456"
    },
    "scheduling_policy" : {
      "href" : "/ovirt-engine/api/schedulingpolicies/789",
      "id" : "789"
    },
    "actions" : {
      "link" : [ {
        "href" : "/ovirt-engine/api/clusters/234/resetemulatedmachine",
        "rel" : "resetemulatedmachine"
      } ]
    },
    "name" : "Default",
    "description" : "The default server cluster",
    "href" : "/ovirt-engine/api/clusters/234",
    "id" : "234",
    "link" : [ {
      "href" : "/ovirt-engine/api/clusters/234/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/cpuprofiles",
      "rel" : "cpuprofiles"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/networkfilters",
      "rel" : "networkfilters"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/networks",
      "rel" : "networks"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/affinitygroups",
      "rel" : "affinitygroups"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/glusterhooks",
      "rel" : "glusterhooks"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/glustervolumes",
      "rel" : "glustervolumes"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/enabledfeatures",
      "rel" : "enabledfeatures"
    }, {
      "href" : "/ovirt-engine/api/clusters/234/externalnetworkproviders",
      "rel" : "externalnetworkproviders"
    } ]
  } ]
}

Table 7.38. Attributes summary

Name	Type	Summary
`ballooning_enabled`	Boolean
`comment`	String	Free text containing comments about this object.
`cpu`	Cpu
`custom_scheduling_policy_properties`	Property[]	Custom scheduling policy properties of the cluster.
`description`	String	A human-readable description in plain text.
`display`	Display
`error_handling`	ErrorHandling
`fencing_policy`	FencingPolicy	A custom fencing policy can be defined for a cluster.
`firewall_type`	FirewallType	The type of firewall to be used on hosts in this cluster.
`gluster_service`	Boolean
`gluster_tuned_profile`	String	The name of the https://fedorahosted.
`ha_reservation`	Boolean
`id`	String	A unique identifier.
`ksm`	Ksm
`maintenance_reason_required`	Boolean
`memory_policy`	MemoryPolicy
`migration`	MigrationOptions
`name`	String	A human-readable name in plain text.
`optional_reason`	Boolean
`required_rng_sources`	RngSource[]	Set of random number generator (RNG) sources required from each host in the cluster.
`serial_number`	SerialNumber
`supported_versions`	Version[]
`switch_type`	SwitchType	The type of switch to be used by all networks in given cluster.
`threads_as_cores`	Boolean
`trusted_service`	Boolean
`tunnel_migration`	Boolean
`version`	Version	The compatibility version of the cluster.
`virt_service`	Boolean

7.28.1. custom_scheduling_policy_properties

Custom 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:

PUT /ovirt-engine/api/clusters/123

With a request body:

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

7.28.2. fencing_policy

A custom fencing policy can be defined for a cluster.

For example:

PUT /ovirt-engine/api/cluster/123

With request body like this:

<cluster>
  <fencing_policy>
    <enabled>true</enabled>
    <skip_if_sd_active>
      <enabled>false</enabled>
    </skip_if_sd_active>
    <skip_if_connectivity_broken>
      <enabled>false</enabled>
      <threshold>50</threshold>
    </skip_if_connectivity_broken>
  </fencing_policy>
</cluster>

7.28.3. firewall_type

The type of firewall to be used on hosts in this cluster.

Up to version 4.1, it was always iptables. Since version 4.2, you can choose between iptables and firewalld. For clusters with a compatibility version of 4.2 and higher, the default firewall type is firewalld.

7.28.4. gluster_tuned_profile

The name of the tuned profile to set on all the hosts in the cluster. This is not mandatory and relevant only for clusters with Gluster service.

7.28.5. required_rng_sources

Set of random number generator (RNG) sources required from each host in the cluster.

When read, it returns the implicit urandom (for cluster version 4.1 and higher) or random (for cluster version 4.0 and lower) plus additional selected RNG sources. When written, the implicit urandom and random RNG sources cannot be removed.

Important

Before version 4.1 of the engine, the set of required random number generators was completely controllable by the administrator; any source could be added or removed, including the random source. But starting with version 4.1, the urandom and random sources will always be part of the set, and can’t be removed.

Important

Engine version 4.1 introduces a new RNG source urandom that replaces random RNG source in clusters with compatibility version 4.1 or higher.

7.28.6. version

The compatibility version of the cluster.

All hosts in this cluster must support at least this compatibility version.

For example:

GET /ovirt-engine/api/clusters/123

Will respond with:

<cluster>
  ...
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  ...
</cluster>

To update the compatibility version, use:

PUT /ovirt-engine/api/clusters/123

With a request body like this:

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

Table 7.39. Links summary

Name	Type	Summary
`affinity_groups`	AffinityGroup[]
`cpu_profiles`	CpuProfile[]
`data_center`	DataCenter
`enabled_features`	ClusterFeature[]	Custom features that are enabled for the cluster.
`external_network_providers`	ExternalProvider[]	A reference to the external network provider available in the cluster.
`gluster_hooks`	GlusterHook[]
`gluster_volumes`	GlusterVolume[]
`mac_pool`	MacPool	A reference to the MAC pool used by this cluster.
`management_network`	Network
`network_filters`	NetworkFilter[]
`networks`	Network[]
`permissions`	Permission[]
`scheduling_policy`	SchedulingPolicy	Reference to the default scheduling policy used by this cluster.

7.28.7. external_network_providers

A reference to the external network provider available in the cluster.

If the automatic deployment of the external network provider is supported, the networks of the referenced network provider are available on every host in the cluster. External network providers of a cluster can only be set during adding the cluster. This value may be overwritten for individual hosts during adding the host.

7.28.8. scheduling_policy

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

7.29. ClusterFeature struct

Type represents an additional feature that is available at a cluster level.

Table 7.40. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.41. Links summary

Name	Type	Summary
`cluster_level`	ClusterLevel	Reference to the cluster level.

7.30. ClusterLevel struct

Describes the capabilities supported by a specific cluster level.

Table 7.42. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`cpu_types`	CpuType[]	The CPU types supported by this cluster level.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`permits`	Permit[]	The permits supported by this cluster level.

Table 7.43. Links summary

Name	Type	Summary
`cluster_features`	ClusterFeature[]	The additional features supported by this cluster level.

7.31. Configuration struct

Table 7.44. Attributes summary

Name	Type	Summary
`data`	String	The document describing the virtual machine.
`type`	ConfigurationType

7.31.1. data

The document describing the virtual machine.

Example of the OVF document:

<?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 Memory</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>

7.32. ConfigurationType enum

Configuration format types.

Table 7.45. Values summary

Name	Summary
`ova`	ConfigurationType of type standard OVF.
`ovf`	ConfigurationType of type oVirt-compatible OVF.

7.32.1. ova

ConfigurationType of type standard OVF.

The provided virtual machine configuration conforms with the Open Virtualization Format (OVF) standard. This value should be used for an OVF configuration that is extracted from an Open Virtual Appliance (OVA) that was generated by oVirt or by other vendors. See here for the OVF specification.

7.32.2. ovf

ConfigurationType of type oVirt-compatible OVF.

The provided virtual machine configuration conforms with the oVirt-compatible form of the Open Virtualization Format (OVF). Note that the oVirt-compatible form of the OVF may differ from the OVF standard that is used by other vendors. This value should be used for an OVF configuration that is taken from a storage domain.

7.33. Console struct

Representation for serial console device.

Table 7.46. Attributes summary

Name	Type	Summary
`enabled`	Boolean	Enable/disable the serial console device.

7.34. Core struct

Table 7.47. Attributes summary

Name	Type	Summary
`index`	Integer
`socket`	Integer

7.35. Cpu struct

Table 7.48. Attributes summary

Name	Type	Summary
`architecture`	Architecture
`cores`	Core[]
`cpu_tune`	CpuTune
`level`	Integer
`mode`	CpuMode
`name`	String
`speed`	Decimal
`topology`	CpuTopology
`type`	String

7.36. CpuMode enum

Table 7.49. Values summary

Name	Summary
`custom`
`host_model`
`host_passthrough`

7.37. CpuProfile struct

Table 7.50. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.51. Links summary

Name	Type	Summary
`cluster`	Cluster
`permissions`	Permission[]
`qos`	Qos

7.38. CpuTopology struct

Table 7.52. Attributes summary

Name	Type	Summary
`cores`	Integer
`sockets`	Integer
`threads`	Integer

7.39. CpuTune struct

Table 7.53. Attributes summary

Name	Type	Summary
`vcpu_pins`	VcpuPin[]

7.40. CpuType struct

Describes a supported CPU type.

Table 7.54. Attributes summary

Name	Type	Summary
`architecture`	Architecture	The architecture of the CPU.
`level`	Integer	The level of the CPU type.
`name`	String	The name of the CPU type, for example `Intel Conroe Family`.

7.41. CreationStatus enum

Table 7.55. Values summary

Name	Summary
`complete`
`failed`
`in_progress`
`pending`

7.42. CustomProperty struct

Custom property representation.

Table 7.56. Attributes summary

Name	Type	Summary
`name`	String	Property name.
`regexp`	String	A regular expression defining the available values a custom property can get.
`value`	String	Property value.

7.43. DataCenter struct

Table 7.57. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`local`	Boolean
`name`	String	A human-readable name in plain text.
`quota_mode`	QuotaModeType
`status`	DataCenterStatus
`storage_format`	StorageFormat
`supported_versions`	Version[]
`version`	Version	The compatibility version of the data center.

7.43.1. version

The compatibility version of the data center.

All clusters in this data center must already be set to at least this compatibility version.

For example:

GET /ovirt-engine/api/datacenters/123

Will respond:

<data_center>
  ...
  <version>
    <major>4</major>
    <minor>0</minor>
  </version>
  ...
</data_center>

To update the compatibility version, use:

PUT /ovirt-engine/api/datacenters/123

With a request body:

<data_center>
  <version>
    <major>4</major>
    <minor>1</minor>
  </version>
</data_center>

Table 7.58. Links summary

Name	Type	Summary
`clusters`	Cluster[]	Reference to clusters inside this data center.
`iscsi_bonds`	IscsiBond[]	Reference to ISCSI bonds used by this data center.
`mac_pool`	MacPool	Reference to the MAC pool used by this data center.
`networks`	Network[]	Reference to networks attached to this data center.
`permissions`	Permission[]	Reference to permissions assigned to this data center.
`qoss`	Qos[]	Reference to quality of service used by this data center.
`quotas`	Quota[]	Reference to quotas assigned to this data center.
`storage_domains`	StorageDomain[]	Reference to storage domains attached to this data center.

7.44. DataCenterStatus enum

Table 7.59. Values summary

Name	Summary
`contend`
`maintenance`
`not_operational`
`problematic`
`uninitialized`
`up`

7.45. Device struct

A device wraps links to potential parents of a device.

Table 7.60. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.61. Links summary

Name	Type	Summary
`instance_type`	InstanceType	Optionally references to an instance type the device is used by.
`template`	Template	Optionally references to a template the device is used by.
`vm`	Vm	Don’t use this element, use `vms` instead.
`vms`	Vm[]	References to the virtual machines that are using this device.

7.45.1. vms

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.

7.46. Disk struct

Represents a virtual disk device.

Table 7.62. Attributes summary

Name	Type	Summary
`active`	Boolean	Indicates if the disk is visible to the virtual machine.
`actual_size`	Integer	The actual size of the disk, in bytes.
`alias`	String
`bootable`	Boolean	Indicates if the disk is marked as bootable.
`comment`	String	Free text containing comments about this object.
`content_type`	DiskContentType	Indicates the actual content residing on the disk.
`description`	String	A human-readable description in plain text.
`format`	DiskFormat	The underlying storage format.
`id`	String	A unique identifier.
`image_id`	String
`initial_size`	Integer	The initial size of a sparse image disk created on block storage, in bytes.
`interface`	DiskInterface	The type of interface driver used to connect the disk device to the virtual machine.
`logical_name`	String
`lun_storage`	HostStorage
`name`	String	A human-readable name in plain text.
`propagate_errors`	Boolean	Indicates if disk errors should cause virtual machine to be paused or if disk errors should be propagated to the the guest operating system instead.
`provisioned_size`	Integer	The virtual size of the disk, in bytes.
`qcow_version`	QcowVersion	The underlying QCOW version of a QCOW volume.
`read_only`	Boolean	Indicates if the disk is in read-only mode.
`sgio`	ScsiGenericIO
`shareable`	Boolean	Indicates if the disk can be attached to multiple virtual machines.
`sparse`	Boolean	Indicates if the physical storage for the disk should not be preallocated.
`status`	DiskStatus	The status of the disk device.
`storage_type`	DiskStorageType
`total_size`	Integer	The total size of the disk including all of its snapshots, in bytes.
`uses_scsi_reservation`	Boolean
`wipe_after_delete`	Boolean	Indicates 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.

7.46.1. active

Indicates if the disk is visible to the virtual machine.

Important

When adding a disk attachment to a virtual machine, if the server accepts requests that do not contain this attribute the result is undefined. In some cases the disk will be automatically activated and in other cases it will not. To avoid issues it is strongly recommended to always include the this attribute with the desired value.

7.46.2. actual_size

The actual size of the disk, in bytes.

The actual size is the number of bytes actually used by the disk. It will be smaller than the provisioned size for disks that use the cow format.

7.46.3. bootable

Indicates 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 DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

7.46.4. initial_size

The initial size of a sparse image disk created on block storage, in bytes.

The initial size is the number of bytes a sparse disk is initially allocated with when created on block storage. The initial size will be smaller than the provisioned size. If not specified the default initial size used by the system will be allocated.

7.46.5. interface

The 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 DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

7.46.6. provisioned_size

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

7.46.7. qcow_version

The underlying QCOW version of a QCOW volume. The QCOW version specifies to the qemu which qemu version the volume supports. This field can be updated using the update API and will be reported only for QCOW volumes. It is determined by the version of the storage domain that the disk is created on. Storage domains with a version lower than V4 support QCOW2 volumes. V4 storage domains also support QCOW2v3. For more information about features of the different QCOW versions, see here.

7.46.8. read_only

Indicates if the disk is in read-only mode.

Since version 4.0 this attribute is not shown in the API and was moved to DiskAttachment.

Since version 4.1.2 of Red Hat Virtualization Manager this attribute is deprecated, and it will be removed in the future. In order to attach a disk in read only mode use the read_only attribute of the DiskAttachment type. For example:

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

<disk_attachment>
  <read_only>true</read_only>
  ...
</disk_attachment>

7.46.9. shareable

Indicates 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 GlusterFS or GFS.

7.46.10. total_size

The total size of the disk including all of its snapshots, in bytes.

The total size is the number of bytes actually used by the disk plus the size of its snapshots. It won’t be populated for direct LUN and Cinder disks. For disks without snapshots the total size is equal to the actual size.

7.46.11. wipe_after_delete

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

Table 7.63. Links summary

Name	Type	Summary
`disk_profile`	DiskProfile
`instance_type`	InstanceType	Optionally references to an instance type the device is used by.
`openstack_volume_type`	OpenStackVolumeType
`permissions`	Permission[]
`quota`	Quota
`snapshot`	Snapshot
`statistics`	Statistic[]	Statistics exposed by the disk.
`storage_domain`	StorageDomain
`storage_domains`	StorageDomain[]	The storage domains associated with this disk.
`template`	Template	Optionally references to a template the device is used by.
`vm`	Vm	Don’t use this element, use `vms` instead.
`vms`	Vm[]	References to the virtual machines that are using this device.

7.46.12. statistics

Statistics exposed by the disk. For example:

<statistics>
  <statistic href="/ovirt-engine/api/disks/123/statistics/456" id="456">
    <name>data.current.read</name>
    <description>Read data rate</description>
    <kind>gauge</kind>
    <type>decimal</type>
    <unit>bytes_per_second</unit>
    <values>
      <value>
        <datum>1052</datum>
      </value>
    </values>
    <disk href="/ovirt-engine/api/disks/123" id="123"/>
  </statistic>
  ...
</statistics>

These statistics are not directly included when the disk is retrieved, only a link. To obtain the statistics follow the included link:

GET /ovirt-engine/api/disks/123/statistics

7.46.13. storage_domains

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

7.46.14. vms

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.

7.47. DiskAttachment struct

Describes how a disk is attached to a virtual machine.

Table 7.64. Attributes summary

Name	Type	Summary
`active`	Boolean	Defines whether the disk is active in the virtual machine it’s attached to.
`bootable`	Boolean	Defines whether the disk is bootable.
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`interface`	DiskInterface	The type of interface driver used to connect the disk device to the virtual machine.
`logical_name`	String	The logical name of the virtual machine’s disk, as seen from inside the virtual machine.
`name`	String	A human-readable name in plain text.
`pass_discard`	Boolean	Defines whether the virtual machine passes discard commands to the storage.
`read_only`	Boolean	Indicates whether the disk is connected to the virtual machine as read only.
`uses_scsi_reservation`	Boolean	Defines whether SCSI reservation is enabled for this disk.

7.47.1. active

Defines whether 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.

7.47.2. logical_name

The 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:

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

7.47.3. read_only

Indicates whether the disk is connected to the virtual machine as read only.

When adding a new disk attachment the default value is false.

<disk_attachment>
  ...
  <read_only>true</read_only>
</disk_attachment>

7.47.4. uses_scsi_reservation

Defines whether SCSI reservation is enabled for this disk.

Virtual machines with VIRTIO-SCSI passthrough enabled can set persistent SCSI reservations on disks. If they set persistent SCSI reservations, those virtual machines cannot be migrated to a different host because they would lose access to the disk, because SCSI reservations are specific to SCSI initiators, and therefore hosts. This scenario cannot be automatically detected. To avoid migrating these virtual machines, the user can set this attribute to true, to indicate the virtual machine is using SCSI reservations.

Table 7.65. Links summary

Name	Type	Summary
`disk`	Disk	The reference to the disk.
`template`	Template	The reference to the template.
`vm`	Vm	The reference to the virtual machine.

7.48. DiskContentType enum

The actual content residing on the disk.

Table 7.66. Values summary

Name	Summary
`data`	The disk contains data.
`iso`	The disk contains an ISO image to be used a CDROM device.
`memory_dump_volume`	The disk contains a memory dump from a live snapshot.
`memory_metadata_volume`	The disk contains memory metadata from a live snapshot.
`ovf_store`	The disk is an OVF store.

7.49. DiskFormat enum

The underlying storage format of disks.

Table 7.67. Values summary

Name	Summary
`cow`	The Copy On Write format allows snapshots, with a small performance overhead.
`raw`	The raw format does not allow snapshots, but offers improved performance.

7.50. DiskInterface enum

The underlying storage interface of disks communication with controller.

Table 7.68. Values summary

Name	Summary
`ide`	Legacy controller device.
`spapr_vscsi`	Para-virtualized device supported by the IBM pSeries family of machines, using the SCSI protocol.
`virtio`	Virtualization interface where just the guest’s device driver knows it is running in a virtual environment.
`virtio_scsi`	Para-virtualized SCSI controller device.

7.50.1. ide

Legacy controller device. Works with almost all guest operating systems, so it is good for compatibility. Performance is lower than with the other alternatives.

7.50.2. virtio

Virtualization interface where just the guest’s device driver knows it is running in a virtual environment. Enables guests to get high performance disk operations.

7.50.3. virtio_scsi

Para-virtualized SCSI controller device. Fast interface with the guest via direct physical storage device address, using the SCSI protocol.

7.51. DiskProfile struct

Table 7.69. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.70. Links summary

Name	Type	Summary
`permissions`	Permission[]
`qos`	Qos
`storage_domain`	StorageDomain

7.52. DiskSnapshot struct

Table 7.71. Attributes summary

Name	Type	Summary
`active`	Boolean	Indicates if the disk is visible to the virtual machine.
`actual_size`	Integer	The actual size of the disk, in bytes.
`alias`	String
`bootable`	Boolean	Indicates if the disk is marked as bootable.
`comment`	String	Free text containing comments about this object.
`content_type`	DiskContentType	Indicates the actual content residing on the disk.
`description`	String	A human-readable description in plain text.
`format`	DiskFormat	The underlying storage format.
`id`	String	A unique identifier.
`image_id`	String
`initial_size`	Integer	The initial size of a sparse image disk created on block storage, in bytes.
`interface`	DiskInterface	The type of interface driver used to connect the disk device to the virtual machine.
`logical_name`	String
`lun_storage`	HostStorage
`name`	String	A human-readable name in plain text.
`propagate_errors`	Boolean	Indicates if disk errors should cause virtual machine to be paused or if disk errors should be propagated to the the guest operating system instead.
`provisioned_size`	Integer	The virtual size of the disk, in bytes.
`qcow_version`	QcowVersion	The underlying QCOW version of a QCOW volume.
`read_only`	Boolean	Indicates if the disk is in read-only mode.
`sgio`	ScsiGenericIO
`shareable`	Boolean	Indicates if the disk can be attached to multiple virtual machines.
`sparse`	Boolean	Indicates if the physical storage for the disk should not be preallocated.
`status`	DiskStatus	The status of the disk device.
`storage_type`	DiskStorageType
`total_size`	Integer	The total size of the disk including all of its snapshots, in bytes.
`uses_scsi_reservation`	Boolean
`wipe_after_delete`	Boolean	Indicates 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.

7.52.1. active

Indicates if the disk is visible to the virtual machine.

Important

When adding a disk attachment to a virtual machine, if the server accepts requests that do not contain this attribute the result is undefined. In some cases the disk will be automatically activated and in other cases it will not. To avoid issues it is strongly recommended to always include the this attribute with the desired value.

7.52.2. actual_size

The actual size of the disk, in bytes.

The actual size is the number of bytes actually used by the disk. It will be smaller than the provisioned size for disks that use the cow format.

7.52.3. bootable

Indicates 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 DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

7.52.4. initial_size

The initial size of a sparse image disk created on block storage, in bytes.

The initial size is the number of bytes a sparse disk is initially allocated with when created on block storage. The initial size will be smaller than the provisioned size. If not specified the default initial size used by the system will be allocated.

7.52.5. interface

The 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 DiskAttachment type. It is preserved here only for backwards compatibility, and it will be removed in the future.

7.52.6. provisioned_size

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

7.52.7. qcow_version

The underlying QCOW version of a QCOW volume. The QCOW version specifies to the qemu which qemu version the volume supports. This field can be updated using the update API and will be reported only for QCOW volumes. It is determined by the version of the storage domain that the disk is created on. Storage domains with a version lower than V4 support QCOW2 volumes. V4 storage domains also support QCOW2v3. For more information about features of the different QCOW versions, see here.

7.52.8. read_only

Indicates if the disk is in read-only mode.

Since version 4.0 this attribute is not shown in the API and was moved to DiskAttachment.

Since version 4.1.2 of Red Hat Virtualization Manager this attribute is deprecated, and it will be removed in the future. In order to attach a disk in read only mode use the read_only attribute of the DiskAttachment type. For example:

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

<disk_attachment>
  <read_only>true</read_only>
  ...
</disk_attachment>

7.52.9. shareable

Indicates 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 GlusterFS or GFS.

7.52.10. total_size

The total size of the disk including all of its snapshots, in bytes.

The total size is the number of bytes actually used by the disk plus the size of its snapshots. It won’t be populated for direct LUN and Cinder disks. For disks without snapshots the total size is equal to the actual size.

7.52.11. wipe_after_delete

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

Table 7.72. Links summary

Name	Type	Summary
`disk`	Disk
`disk_profile`	DiskProfile
`instance_type`	InstanceType	Optionally references to an instance type the device is used by.
`openstack_volume_type`	OpenStackVolumeType
`permissions`	Permission[]
`quota`	Quota
`snapshot`	Snapshot
`statistics`	Statistic[]	Statistics exposed by the disk.
`storage_domain`	StorageDomain
`storage_domains`	StorageDomain[]	The storage domains associated with this disk.
`template`	Template	Optionally references to a template the device is used by.
`vm`	Vm	Don’t use this element, use `vms` instead.
`vms`	Vm[]	References to the virtual machines that are using this device.

7.52.12. statistics

Statistics exposed by the disk. For example:

<statistics>
  <statistic href="/ovirt-engine/api/disks/123/statistics/456" id="456">
    <name>data.current.read</name>
    <description>Read data rate</description>
    <kind>gauge</kind>
    <type>decimal</type>
    <unit>bytes_per_second</unit>
    <values>
      <value>
        <datum>1052</datum>
      </value>
    </values>
    <disk href="/ovirt-engine/api/disks/123" id="123"/>
  </statistic>
  ...
</statistics>

These statistics are not directly included when the disk is retrieved, only a link. To obtain the statistics follow the included link:

GET /ovirt-engine/api/disks/123/statistics

7.52.13. storage_domains

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

7.52.14. vms

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.

7.53. DiskStatus enum

Current status representation for disk.

Table 7.73. Values summary

Name	Summary
`illegal`	Disk cannot be accessed by the virtual machine, and the user needs to take action to resolve the issue.
`locked`	The disk is being used by the system, therefore it cannot be accessed by virtual machines at this point.
`ok`	The disk status is normal and can be accessed by the virtual machine.

7.53.1. locked

The disk is being used by the system, therefore it cannot be accessed by virtual machines at this point. This is usually a temporary status, until the disk is freed.

7.54. DiskStorageType enum

Table 7.74. Values summary

Name	Summary
`cinder`
`image`
`lun`

7.55. DiskType enum

Table 7.75. Values summary

Name	Summary
`data`
`system`

7.56. Display struct

Represents a graphic console configuration.

Table 7.76. Attributes summary

Name	Type	Summary
`address`	String	The IP address of the guest to connect the graphic console client to.
`allow_override`	Boolean	Indicates if to override the display address per host.
`certificate`	Certificate	The TLS certificate in case of a TLS connection.
`copy_paste_enabled`	Boolean	Indicates whether a user is able to copy and paste content from an external host into the graphic console.
`disconnect_action`	String	Returns the action that will take place when the graphic console is disconnected.
`file_transfer_enabled`	Boolean	Indicates if a user is able to drag and drop files from an external host into the graphic console.
`keyboard_layout`	String	The keyboard layout to use with this graphic console.
`monitors`	Integer	The number of monitors opened for this graphic console.
`port`	Integer	The port address on the guest to connect the graphic console client to.
`proxy`	String	The proxy IP which will be used by the graphic console client to connect to the guest.
`secure_port`	Integer	The secured port address on the guest, in case of using TLS, to connect the graphic console client to.
`single_qxl_pci`	Boolean	Indicates if to use one PCI slot for each monitor or to use a single PCI channel for all multiple monitors.
`smartcard_enabled`	Boolean	Indicates if to use smart card authentication.
`type`	DisplayType	The graphic console protocol type.

7.56.1. allow_override

Indicates if to override the display address per host. Relevant only for the Host.display attribute. If set, the graphical console address of a virtual machine will be overridden by the host specified display address. if not set, the graphical console address of a virtual machine will not be overridden.

7.56.2. certificate

The TLS certificate in case of a TLS connection. If TLS isn’t enabled then it won’t be reported.

7.56.3. copy_paste_enabled

Indicates whether a user is able to copy and paste content from an external host into the graphic console. This option is only available for the SPICE console type.

7.56.4. disconnect_action

Returns the action that will take place when the graphic console is disconnected. The options are:

none: No action is taken.
lock_screen: Locks the currently active user session.
logout: Logs out the currently active user session.
reboot: Initiates a graceful virtual machine reboot.
shutdown: Initiates a graceful virtual machine shutdown.

This option is only available for the SPICE console type.

7.56.5. file_transfer_enabled

Indicates if a user is able to drag and drop files from an external host into the graphic console. This option is only available for the SPICE console type.

7.56.6. keyboard_layout

The keyboard layout to use with this graphic console. This option is only available for the VNC console type. If no keyboard is enabled then it won’t be reported.

7.56.7. monitors

The number of monitors opened for this graphic console. This option is only available for the SPICE console type. Possible values are 1, 2 or 4.

7.56.8. proxy

The proxy IP which will be used by the graphic console client to connect to the guest. It is useful when the client is outside the guest’s network. This option is only available for the SPICE console type. This proxy can be set in global configuration, cluster level, virtual machine pool level or disabled per virtual machine. If the proxy is set in any of this mentioned places and not disabled for the virtual machine, it will be returned by this method. If the proxy is not set, nothing will be reported.

7.56.9. secure_port

The secured port address on the guest, in case of using TLS, to connect the graphic console client to. If TLS isn’t enabled then it won’t be reported.

7.56.10. single_qxl_pci

Indicates if to use one PCI slot for each monitor or to use a single PCI channel for all multiple monitors. This option is only available for the SPICE console type and only for connecting a guest Linux based OS.

7.56.11. smartcard_enabled

Indicates if to use smart card authentication. This option is only available for the SPICE console type.

7.57. DisplayType enum

Represents an enumeration of the protocol used to connect to the graphic console of the virtual machine.

Table 7.77. Values summary

Name	Summary
`spice`	Display of type SPICE.
`vnc`	Display of type VNC.

7.57.1. spice

Display of type SPICE. See https://www.spice-space.org for more details.

7.57.2. vnc

Display of type VNC. VNC stands for Virtual Network Computing, and it is a graphical desktop sharing system that uses RFB (Remote Frame Buffer) protocol to remotely control another machine.

7.58. Dns struct

Represents the DNS resolver configuration.

Table 7.78. Attributes summary

Name	Type	Summary
`search_domains`	Host[]	Array of hosts serving as search domains.
`servers`	Host[]	Array of hosts serving as DNS servers.

7.59. DnsResolverConfiguration struct

Represents the DNS resolver configuration.

Table 7.79. Attributes summary

Name	Type	Summary
`name_servers`	String[]	Array of addresses of name servers.

7.59.1. name_servers

Array of addresses of name servers. Either IPv4 or IPv6 addresses may be specified.

7.60. Domain struct

This type represents a directory service domain.

Table 7.80. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`user`	User

Table 7.81. Links summary

Name	Type	Summary
`groups`	Group[]	A reference to all groups in the directory service.
`users`	User[]	A reference to a list of all users in the directory service.

7.60.1. users

A reference to a list of all users in the directory service. This information is used to add new users to the Red Hat Virtualization environment.

7.61. EntityExternalStatus enum

Type representing an external entity status.

Table 7.82. Values summary

Name	Summary
`error`	The external entity status is erroneous.
`failure`	The external entity has an issue that causes failures.
`info`	There external entity status is okay but with some information that might be relevant.
`ok`	The external entity status is okay.
`warning`	The external entity status is okay but with an issue that might require attention.

7.61.1. error

The external entity status is erroneous. This might require a moderate attention.

7.61.2. failure

The external entity has an issue that causes failures. This might require immediate attention.

7.62. EntityProfileDetail struct

Table 7.83. Attributes summary

Name	Type	Summary
`profile_details`	ProfileDetail[]

7.63. ErrorHandling struct

Table 7.84. Attributes summary

Name	Type	Summary
`on_error`	MigrateOnError

7.64. Event struct

Type representing an event.

Table 7.85. Attributes summary

Name	Type	Summary
`code`	Integer	The event code.
`comment`	String	Free text containing comments about this object.
`correlation_id`	String	The event correlation identifier.
`custom_data`	String	Free text representing custom event data.
`custom_id`	Integer	A custom event identifier.
`description`	String	A human-readable description in plain text.
`flood_rate`	Integer	Defines the flood rate.
`id`	String	A unique identifier.
`index`	Integer	The numeric index of this event.
`name`	String	A human-readable name in plain text.
`origin`	String	Free text identifying the origin of the event.
`severity`	LogSeverity	The event severity.
`time`	Date	The event time.

7.64.1. correlation_id

The event correlation identifier. Used in order to correlate several events together.

7.64.2. flood_rate

Defines the flood rate. This prevents flooding in case an event appeared more than once in the defined rate. Defaults is 30 seconds.

7.64.3. index

The numeric index of this event. The indexes of events are always increasing, so events with higher indexes are guaranteed to be older than events with lower indexes.

Important

In the current implementation of the engine, the id attribute has the same value as this index attribute. That is an implementation detail that the user of the API should not rely on. In the future the id attribute may be changed to an arbitrary string, containing non numeric characters and no implicit order. On the other hand this index attribute is guaranteed to stay as integer and ordered.

Table 7.86. Links summary

Name	Type	Summary
`cluster`	Cluster	Reference to the cluster service.
`data_center`	DataCenter	Reference to the data center service.
`host`	Host	Reference to the host service.
`storage_domain`	StorageDomain	Reference to the storage domain service.
`template`	Template	Reference to the template service.
`user`	User	Reference to the user service.
`vm`	Vm	Reference to the virtual machine service.

7.64.4. cluster

Reference to the cluster service. Event can be associated with a cluster.

7.64.5. data_center

Reference to the data center service. Event can be associated with a data center.

7.64.6. host

Reference to the host service. Event can be associated with a host.

7.64.7. storage_domain

Reference to the storage domain service. Event can be associated with a storage domain.

7.64.8. template

Reference to the template service. Event can be associated with a template.

7.64.9. user

Reference to the user service. Event can be associated with a user.

7.64.10. vm

Reference to the virtual machine service. Event can be associated with a virtual machine.

7.65. ExternalComputeResource struct

Table 7.87. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`provider`	String
`url`	String
`user`	String

Table 7.88. Links summary

Name	Type	Summary
`external_host_provider`	ExternalHostProvider

7.66. ExternalDiscoveredHost struct

Table 7.89. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`ip`	String
`last_report`	String
`mac`	String
`name`	String	A human-readable name in plain text.
`subnet_name`	String

Table 7.90. Links summary

Name	Type	Summary
`external_host_provider`	ExternalHostProvider

7.67. ExternalHost struct

Represents a host provisioned by a host provider (such as Foreman/Satellite).

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

Table 7.91. Attributes summary

Name	Type	Summary
`address`	String	The address of the host, either IP address of FQDN (Fully Qualified Domain Name).
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.92. Links summary

Name	Type	Summary
`external_host_provider`	ExternalHostProvider	A reference to the external host provider that the host is managed by.

7.68. ExternalHostGroup struct

Table 7.93. Attributes summary

Name	Type	Summary
`architecture_name`	String
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`domain_name`	String
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`operating_system_name`	String
`subnet_name`	String

Table 7.94. Links summary

Name	Type	Summary
`external_host_provider`	ExternalHostProvider

7.69. ExternalHostProvider struct

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

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

Table 7.95. Attributes summary

Name	Type	Summary
`authentication_url`	String	Defines the external provider authentication URL address.
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`password`	String	Defines password for the user during the authentication process.
`properties`	Property[]	Array of provider name/value properties.
`requires_authentication`	Boolean	Defines whether provider authentication is required or not.
`url`	String	Defines URL address of the external provider.
`username`	String	Defines user name to be used during authentication process.

7.69.1. requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

Table 7.96. Links summary

Name	Type	Summary
`certificates`	Certificate[]	A reference to the certificates the engine supports for this provider.
`compute_resources`	ExternalComputeResource[]	A reference to the compute resource as represented in the host provider.
`discovered_hosts`	ExternalDiscoveredHost[]	A reference to the discovered hosts in the host provider.
`host_groups`	ExternalHostGroup[]	A reference to the host groups in the host provider.
`hosts`	Host[]	A reference to the hosts provisioned by the host provider.

7.69.2. compute_resources

A reference to the compute resource as represented in the host provider. Each host provider optionally has the engine defined as a compute resource, which allows to create virtual machines in the engine. This compute resource details are used in the Bare-Metal provisioning use-case, in order to deploy the hypervisor.

7.69.3. discovered_hosts

A reference to the discovered hosts in the host provider. Discovered hosts are hosts that were not provisioned yet.

7.69.4. host_groups

A reference to the host groups in the host provider. Host group contains different properties that the host provider applies on all hosts that are member of this group. Such as installed software, system definitions, passwords and more.

7.70. ExternalNetworkProviderConfiguration struct

Describes how an external network provider is provisioned on a host.

Table 7.97. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.98. Links summary

Name	Type	Summary
`external_network_provider`	ExternalProvider	Link to the external network provider.
`host`	Host	Link to the host.

7.71. ExternalProvider struct

Represents an external provider.

Table 7.99. Attributes summary

Name	Type	Summary
`authentication_url`	String	Defines the external provider authentication URL address.
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`password`	String	Defines password for the user during the authentication process.
`properties`	Property[]	Array of provider name/value properties.
`requires_authentication`	Boolean	Defines whether provider authentication is required or not.
`url`	String	Defines URL address of the external provider.
`username`	String	Defines user name to be used during authentication process.

7.71.1. requires_authentication

Defines whether provider authentication is required or not.

If authentication is required, both username and password attributes will be used during authentication.

7.72. ExternalStatus enum

Represents an external status. This status is currently used for hosts and storage domains, and allows an external system to update status of objects it is aware of.

Table 7.100. Values summary

Name	Summary
`error`	Error status.
`failure`	Failure status.
`info`	Info status.
`ok`	OK status.
`warning`	Warning status.

7.72.1. error

Error status. There is some kind of error in the relevant object.

7.72.2. failure

Failure status. The relevant object is failing.

7.72.3. info

Info status. The relevant object is in OK status, but there is an information available that might be relevant for the administrator.

7.72.4. ok

OK status. The relevant object is working well.

7.72.5. warning

Warning status. The relevant object is working well, but there is some warning that might be relevant for the administrator.

7.73. ExternalSystemType enum

Represents the type of the external system that is associated with the step.

Table 7.101. Values summary

Name	Summary
`gluster`	Represents `Gluster` as the external system which is associated with the `step`.
`vdsm`	Represents `VDSM` as the external system which is associated with the `step`.

7.74. ExternalVmImport struct

Describes the parameters for the virtual machine import operation from an external system.

Table 7.102. Attributes summary

Name	Type	Summary
`name`	String	The name of the virtual machine to be imported, as is defined within the external system.
`password`	String	The password to authenticate against the external hypervisor system.
`provider`	ExternalVmProviderType	The type of external virtual machine provider.
`sparse`	Boolean	Specifies the disk allocation policy of the resulting virtual machine: `true` for sparse, `false` for preallocated.
`url`	String	The URL to be passed to the `virt-v2v` tool for conversion.
`username`	String	The username to authenticate against the external hypervisor system.

7.74.1. url

The URL to be passed to the virt-v2v tool for conversion.

Example:

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.

Table 7.103. Links summary

Name	Type	Summary
`cluster`	Cluster	Specifies the target cluster for the resulting virtual machine.
`cpu_profile`	CpuProfile	Optional.
`drivers_iso`	File	Optional.
`host`	Host	Optional.
`quota`	Quota	Optional.
`storage_domain`	StorageDomain	Specifies the target storage domain for converted disks.
`vm`	Vm	The virtual machine entity used to specify a name for the newly created virtual machine.

7.74.2. cpu_profile

Optional. Specifies the CPU profile of the resulting virtual machine.

7.74.3. drivers_iso

Optional. The name of the ISO containing drivers that can be used during the virt-v2v conversion process.

7.74.4. host

Optional. Specifies the host (using host’s ID) to be used for the conversion process. If not specified, one is selected automatically.

7.74.5. quota

Optional. Specifies the quota that will be applied to the resulting virtual machine.

7.74.6. vm

The virtual machine entity used to specify a name for the newly created virtual machine.

If a name is not specified, the source virtual machine name will be used.

7.75. ExternalVmProviderType enum

Describes the type of external hypervisor system.

Table 7.104. Values summary

Name	Summary
`kvm`
`vmware`
`xen`

7.76. Fault struct

Table 7.105. Attributes summary

Name	Type	Summary
`detail`	String
`reason`	String

7.77. FenceType enum

Type representing the type of the fence operation.

Table 7.106. Values summary

Name	Summary
`manual`	Manual host fencing via power management.
`restart`	Restart the host via power management.
`start`	Start the host via power management.
`status`	Check the host power status via power management.
`stop`	Stop the host via power management.

7.78. FencingPolicy struct

Type representing a cluster fencing policy.

Table 7.107. Attributes summary

Name	Type	Summary
`enabled`	Boolean	Enable or disable fencing on this cluster.
`skip_if_connectivity_broken`	SkipIfConnectivityBroken	If enabled, we will not fence a host in case more than a configurable percentage of hosts in the cluster lost connectivity as well.
`skip_if_gluster_bricks_up`	Boolean	A flag indicating if fencing should be skipped if Gluster bricks are up and running in the host being fenced.
`skip_if_gluster_quorum_not_met`	Boolean	A flag indicating if fencing should be skipped if Gluster bricks are up and running and Gluster quorum will not be met without those bricks.
`skip_if_sd_active`	SkipIfSdActive	If enabled, we will skip fencing in case the host maintains its lease in the storage.

7.78.1. skip_if_connectivity_broken

If enabled, we will not fence a host in case more than a configurable percentage of hosts in the cluster lost connectivity as well. This comes to prevent fencing storm in cases where there is a global networking issue in the cluster.

7.78.2. skip_if_gluster_bricks_up

A flag indicating if fencing should be skipped if Gluster bricks are up and running in the host being fenced. This flag is optional, and the default value is false.

7.78.3. skip_if_gluster_quorum_not_met

A flag indicating if fencing should be skipped if Gluster bricks are up and running and Gluster quorum will not be met without those bricks. This flag is optional, and the default value is false.

7.78.4. skip_if_sd_active

If enabled, we will skip fencing in case the host maintains its lease in the storage. It means that if the host still has storage access then it won’t get fenced.

7.79. File struct

Table 7.108. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`content`	String
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`type`	String

Table 7.109. Links summary

Name	Type	Summary
`storage_domain`	StorageDomain

7.80. Filter struct

Table 7.110. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`position`	Integer

Table 7.111. Links summary

Name	Type	Summary
`scheduling_policy_unit`	SchedulingPolicyUnit

7.81. FirewallType enum

Describes all firewall types supported by the system.

Table 7.112. Values summary

Name	Summary
`firewalld`	FirewallD firewall type.
`iptables`	IPTables firewall type.

7.81.1. firewalld

FirewallD firewall type.

When a cluster has the firewall type set to firewalld, the firewalls of all hosts in the cluster will be configured using firewalld. FirewallD replaced IPTables in version 4.2. It simplifies configuration using a command line program and dynamic configuration.

7.81.2. iptables

IPTables firewall type.

When a cluster has the firewall type set to iptables, the firewalls of all hosts in the cluster will be configured using iptables. iptables adds firewall rules to /etc/sysconfig/iptables using a special iptables syntax. For more information, see the iptables manual page.

iptables is deprecated in cluster version 4.2 and will be removed in cluster version 4.3.

7.82. Floppy struct

The underlying representation of a floppy file.

Table 7.113. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`file`	File	File object that represent the Floppy device’s content and its type.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.

Table 7.114. Links summary

Name	Type	Summary
`instance_type`	InstanceType	Optionally references to an instance type the device is used by.
`template`	Template	Optionally references to a template the device is used by.
`vm`	Vm	Don’t use this element, use `vms` instead.
`vms`	Vm[]	References to the virtual machines that are using this device.

7.82.1. vms

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.

7.83. FopStatistic struct

Table 7.115. Attributes summary

Name	Type	Summary
`name`	String
`statistics`	Statistic[]

7.84. GlusterBrick struct

Table 7.116. Attributes summary

Name	Type	Summary
`brick_dir`	String
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`device`	String
`fs_name`	String
`gluster_clients`	GlusterClient[]
`id`	String	A unique identifier.
`memory_pools`	GlusterMemoryPool[]
`mnt_options`	String
`name`	String	A human-readable name in plain text.
`pid`	Integer
`port`	Integer
`server_id`	String
`status`	GlusterBrickStatus

Table 7.117. Links summary

Name	Type	Summary
`gluster_volume`	GlusterVolume
`instance_type`	InstanceType	Optionally references to an instance type the device is used by.
`statistics`	Statistic[]
`template`	Template	Optionally references to a template the device is used by.
`vm`	Vm	Don’t use this element, use `vms` instead.
`vms`	Vm[]	References to the virtual machines that are using this device.

7.84.1. vms

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.

7.85. GlusterBrickAdvancedDetails struct

Table 7.118. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`device`	String
`fs_name`	String
`gluster_clients`	GlusterClient[]
`id`	String	A unique identifier.
`memory_pools`	GlusterMemoryPool[]
`mnt_options`	String
`name`	String	A human-readable name in plain text.
`pid`	Integer
`port`	Integer

Table 7.119. Links summary

Name	Type	Summary
`instance_type`	InstanceType	Optionally references to an instance type the device is used by.
`template`	Template	Optionally references to a template the device is used by.
`vm`	Vm	Don’t use this element, use `vms` instead.
`vms`	Vm[]	References to the virtual machines that are using this device.

7.85.1. vms

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.

7.86. GlusterBrickMemoryInfo struct

Table 7.120. Attributes summary

Name	Type	Summary
`memory_pools`	GlusterMemoryPool[]

7.87. GlusterBrickStatus enum

Table 7.121. Values summary

Name	Summary
`down`	Brick is in `down` state, the data cannot be stored or retrieved from it.
`unknown`	When the status cannot be determined due to host being non-responsive.
`up`	Brick is in `up` state, the data can be stored or retrieved from it.

7.88. GlusterClient struct

Table 7.122. Attributes summary

Name	Type	Summary
`bytes_read`	Integer
`bytes_written`	Integer
`client_port`	Integer
`host_name`	String

7.89. GlusterHook struct

Table 7.123. Attributes summary

Name	Type	Summary
`checksum`	String
`comment`	String	Free text containing comments about this object.
`conflict_status`	Integer
`conflicts`	String
`content`	String
`content_type`	HookContentType
`description`	String	A human-readable description in plain text.
`gluster_command`	String
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`stage`	HookStage
`status`	GlusterHookStatus

Table 7.124. Links summary

Name	Type	Summary
`cluster`	Cluster
`server_hooks`	GlusterServerHook[]

7.90. GlusterHookStatus enum

Table 7.125. Values summary

Name	Summary
`disabled`	Hook is disabled in the cluster.
`enabled`	Hook is enabled in the cluster.
`missing`	Unknown/missing hook status.

7.91. GlusterMemoryPool struct

Table 7.126. Attributes summary

Name	Type	Summary
`alloc_count`	Integer
`cold_count`	Integer
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`hot_count`	Integer
`id`	String	A unique identifier.
`max_alloc`	Integer
`max_stdalloc`	Integer
`name`	String	A human-readable name in plain text.
`padded_size`	Integer
`pool_misses`	Integer
`type`	String

7.92. GlusterServerHook struct

Table 7.127. Attributes summary

Name	Type	Summary
`checksum`	String
`comment`	String	Free text containing comments about this object.
`content_type`	HookContentType
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`status`	GlusterHookStatus

Table 7.128. Links summary

Name	Type	Summary
`host`	Host

7.93. GlusterState enum

Table 7.129. Values summary

Name	Summary
`down`
`unknown`
`up`

7.94. GlusterVolume struct

Table 7.130. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`disperse_count`	Integer
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`options`	Option[]
`redundancy_count`	Integer
`replica_count`	Integer
`status`	GlusterVolumeStatus
`stripe_count`	Integer
`transport_types`	TransportType[]
`volume_type`	GlusterVolumeType

Table 7.131. Links summary

Name	Type	Summary
`bricks`	GlusterBrick[]
`cluster`	Cluster
`statistics`	Statistic[]

7.95. GlusterVolumeProfileDetails struct

Table 7.132. Attributes summary

Name	Type	Summary
`brick_profile_details`	BrickProfileDetail[]
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`nfs_profile_details`	NfsProfileDetail[]

7.96. GlusterVolumeStatus enum

Table 7.133. Values summary

Name	Summary
`down`	Volume needs to be started, for clients to be able to mount and use it.
`unknown`	When the status cannot be determined due to host being non-responsive.
`up`	Volume is started, and can be mounted and used by clients.

7.97. GlusterVolumeType enum

Type representing the type of Gluster Volume.

Table 7.134. Values summary

Name	Summary
`disperse`	Dispersed volumes are based on erasure codes, providing space-efficient protection against disk or server failures.
`distribute`	Distributed volumes distributes files throughout the bricks in the volume.
`distributed_disperse`	Distributed dispersed volumes distribute files across dispersed subvolumes.
`distributed_replicate`	Distributed replicated volumes distributes files across replicated bricks in the volume.
`distributed_stripe`	Distributed striped volumes stripe data across two or more nodes in the cluster.
`distributed_striped_replicate`	Distributed striped replicated volumes distributes striped data across replicated bricks in the cluster.
`replicate`	Replicated volumes replicates files across bricks in the volume.
`stripe`	Striped volumes stripes data across bricks in the volume.
`striped_replicate`	Striped replicated volumes stripes data across replicated bricks in the cluster.

7.97.1. disperse

Dispersed volumes are based on erasure codes, providing space-efficient protection against disk or server failures.

Dispersed volumes an encoded fragment of the original file to each brick in a way that only a subset of the fragments is needed to recover the original file. The number of bricks that can be missing without losing access to data is configured by the administrator on volume creation time.

7.97.2. distribute

Distributed volumes distributes files throughout the bricks in the volume.

Distributed volumes can be used where the requirement is to scale storage and the redundancy is either not important or is provided by other hardware/software layers.

7.97.3. distributed_disperse

Distributed dispersed volumes distribute files across dispersed subvolumes.

This has the same advantages of distribute replicate volumes, but using disperse to store the data into the bricks.

7.97.4. distributed_replicate

Distributed replicated volumes distributes files across replicated bricks in the volume.

Distributed replicated volumes can be used in environments where the requirement is to scale storage and high-reliability is critical. Distributed replicated volumes also offer improved read performance in most environments.

7.97.5. distributed_stripe

Distributed striped volumes stripe data across two or more nodes in the cluster.

Distributed striped volumes should be used where the requirement is to scale storage and in high concurrency environments accessing very large files is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not recommended and it will be removed in future release.

7.97.6. distributed_striped_replicate

Distributed striped replicated volumes distributes striped data across replicated bricks in the cluster.

For best results, distributed striped replicated volumes should be used in highly concurrent environments where parallel access of very large files and performance is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not recommended and it will be removed in future release.

7.97.7. replicate

Replicated volumes replicates files across bricks in the volume.

Replicated volumes can be used in environments where high-availability and high-reliability are critical.

7.97.8. stripe

Striped volumes stripes data across bricks in the volume.

For best results, striped volumes should only in high concurrency environments accessing very large files.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not recommended and it will be removed in future release.

7.97.9. striped_replicate

Striped replicated volumes stripes data across replicated bricks in the cluster.

For best results, striped replicated volumes should be used in highly concurrent environments where there is parallel access of very large files and performance is critical.

Note: With the introduction of Sharding in Glusterfs 3.7 releases, striped volumes are not recommended and it will be removed in future release.

7.98. GracePeriod struct

Table 7.135. Attributes summary

Name	Type	Summary
`expiry`	Integer

7.99. GraphicsConsole struct

Table 7.136. Attributes summary

Name	Type	Summary
`address`	String
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`port`	Integer
`protocol`	GraphicsType
`tls_port`	Integer

Table 7.137. Links summary

Name	Type	Summary
`instance_type`	InstanceType
`template`	Template
`vm`	Vm

7.100. GraphicsType enum

The graphics protocol used to connect to the graphic console.

Table 7.138. Values summary

Name	Summary
`spice`	Graphics protocol of type SPICE.
`vnc`	Graphics protocol of type VNC.

7.100.1. spice

Graphics protocol of type SPICE. See https://www.spice-space.org for more details.

7.100.2. vnc

Graphics protocol of type VNC. VNC stands for Virtual Network Computing, and it is a graphical desktop sharing system that uses RFB (Remote Frame Buffer) protocol to remotely control another machine.

7.101. Group struct

This type represents all groups in the directory service.

Table 7.139. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`domain_entry_id`	String	The containing directory service domain id.
`id`	String	A unique identifier.
`name`	String	A human-readable name in plain text.
`namespace`	String	Namespace where group resides.

Table 7.140. Links summary

Name	Type	Summary
`domain`	Domain	A link to the domain containing this group.
`permissions`	Permission[]	A link to the permissions sub-collection for permissions attached to this group.
`roles`	Role[]	A link to the roles sub-collection for roles attached to this group.
`tags`	Tag[]	A link to the tags sub-collection for tags attached to this group.

7.101.1. roles

A link to the roles sub-collection for roles attached to this group.

Used only to represent the initial role assignments for a new group; thereafter, modification of role assignments is only supported via the roles sub-collection.

7.102. GuestOperatingSystem struct

Represents an operating system installed on the virtual machine.

To get that information send a request like this:

GET /ovirt-engine/api/vms/123

The result will be like this:

<vm href="/ovirt-engine/api/vms/123" id="123">
...
  <guest_operating_system>
    <architecture>x86_64</architecture>
    <codename>Maipo</codename>
    <distribution>Red Hat Enterprise Linux Server</distribution>
    <family>Linux</family>
    <kernel>
      <version>
        <build>0</build>
        <full_version>3.10.0-514.10.2.el7.x86_64</full_version>
        <major>3</major>
        <minor>10</minor>
        <revision>514</revision>
      </version>
    </kernel>
    <version>
      <full_version>7.3</full_version>
      <major>7</major>
      <minor>3</minor>
    </version>
  </guest_operating_system>
</vm>

Table 7.141. Attributes summary

Name	Type	Summary
`architecture`	String	The architecture of the operating system, such as x86_64.
`codename`	String	Code name of the operating system, such as `Maipo`.
`distribution`	String	Full name of operating system distribution.
`family`	String	Family of operating system, such as `Linux`.
`kernel`	Kernel	Kernel version of the operating system.
`version`	Version	Version of the installed operating system.

7.103. HardwareInformation struct

Represents hardware information of host.

To get that information send a request like this:

GET /ovirt-engine/api/hosts/123

The result will be like this:

<host href="/ovirt-engine/api/hosts/123" id="123">
  ...
  <hardware_information>
    <family>Red Hat Enterprise Linux</family>
    <manufacturer>Red Hat</manufacturer>
    <product_name>RHEV Hypervisor</product_name>
    <serial_number>01234567-89AB-CDEF-0123-456789ABCDEF</serial_number>
    <supported_rng_sources>
      <supported_rng_source>random</supported_rng_source>
    </supported_rng_sources>
    <uuid>12345678-9ABC-DEF0-1234-56789ABCDEF0</uuid>
    <version>1.2-34.5.el7ev</version>
  </hardware_information>
  ...
</application>

Table 7.142. Attributes summary

Name	Type	Summary
`family`	String	Type of host’s CPU.
`manufacturer`	String	Manufacturer of the host’s machine and hardware vendor.
`product_name`	String	Host’s product name (for example `RHEV Hypervisor`).
`serial_number`	String	Unique ID for host’s chassis.
`supported_rng_sources`	RngSource[]	Supported sources of random number generator.
`uuid`	String	Unique ID for each host.
`version`	String	Unique name for each of the manufacturer.

7.104. HighAvailability struct

Type representing high availability of a virtual machine.

Table 7.143. Attributes summary

Name	Type	Summary
`enabled`	Boolean	Define if the virtual machine should be consider highly available.
`priority`	Integer	Indicates the priority of the virtual machine inside the run and migration queues.

7.104.1. priority

Indicates the priority of the virtual machine inside the run and migration queues.

Virtual machines with higher priorities will be started and migrated before virtual machines with lower priorities.

The value is an integer between 0 and 100. The higher the value, the higher the priority.

The graphical user interface (GUI) does not allow specifying all the possible values, instead it only allows you to select Low, Medium or High. When the value is set using the API, the GUI will set the label as follows:

API Value	GUI Label
0 - 25	Low
26 - 74	Medium
75 - 100	High

When the label is selected using the GUI, the value in the API will be set as follows:

GUI Label	API Value
Low	1
Medium	50
High	100

7.105. Hook struct

Represents a hook.

Table 7.144. Attributes summary

Name	Type	Summary
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`event_name`	String	Name of the event to execute the hook on.
`id`	String	A unique identifier.
`md5`	String	Checksum of the hook.
`name`	String	A human-readable name in plain text.

Table 7.145. Links summary

Name	Type	Summary
`host`	Host	Reference to the host the hook belongs to.

7.106. HookContentType enum

Represents content type of hook script.

Table 7.146. Values summary

Name	Summary
`binary`	Binary content type of the hook.
`text`	Text content type of the hook.

7.107. HookStage enum

Type represents a stage of volume event at which hook executes.

Table 7.147. Values summary

Name	Summary
`post`	Stage after start of volume.
`pre`	Stage before start of volume.

7.108. HookStatus enum

Type represents the status of a hook.

Table 7.148. Values summary

Name	Summary
`disabled`	Hook is disabled.
`enabled`	Hook is enabled.
`missing`	Hook is missing.

7.109. Host struct

Type representing a host.

Table 7.149. Attributes summary

Name	Type	Summary
`address`	String	The host address (FQDN/IP).
`auto_numa_status`	AutoNumaStatus	The host auto non uniform memory access (NUMA) status.
`certificate`	Certificate	The host certificate.
`comment`	String	Free text containing comments about this object.
`cpu`	Cpu	The CPU type of this host.
`description`	String	A human-readable description in plain text.
`device_passthrough`	HostDevicePassthrough	Specifies whether host device passthrough is enabled on this host.
`display`	Display	Optionally specify the display address of this host explicitly.
`external_status`	ExternalStatus	The host external status.
`hardware_information`	HardwareInformation	The host hardware information.
`hosted_engine`	HostedEngine	The self-hosted engine status of this host.
`id`	String	A unique identifier.
`iscsi`	IscsiDetails	The host iSCSI details.
`kdump_status`	KdumpStatus	The host KDUMP status.
`ksm`	Ksm	Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pages to a single page reference.
`libvirt_version`	Version	The host libvirt version.
`max_scheduling_memory`	Integer	The max scheduling memory on this host in bytes.
`memory`	Integer	The amount of physical memory on this host in bytes.
`name`	String	A human-readable name in plain text.
`network_operation_in_progress`	Boolean	Specifies whether a network-related operation, such as 'setup networks' or 'sync networks', is currently being executed on this host.
`numa_supported`	Boolean	Specifies whether non uniform memory access (NUMA) is supported on this host.
`os`	OperatingSystem	The operating system on this host.
`override_iptables`	Boolean	Specifies whether we should override firewall definitions.
`port`	Integer	The host port.
`power_management`	PowerManagement	The host power management definitions.
`protocol`	HostProtocol	The protocol that the engine uses to communicate with the host.
`root_password`	String	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.
`se_linux`	SeLinux	The host SElinux status.
`spm`	Spm	The host storage pool manager (SPM) status and definition.
`ssh`	Ssh	The SSH definitions.
`status`	HostStatus	The host status.
`status_detail`	String	The host status details.
`summary`	VmSummary	The virtual machine summary - how many are active, migrating and total.
`transparent_huge_pages`	TransparentHugePages	Transparent huge page support expands the size of memory pages beyond the standard 4 KiB limit.
`type`	HostType	Indicates if the host contains a full installation of the operating system or a scaled-down version intended only to host virtual machines.
`update_available`	Boolean	Specifies whether there is an oVirt-related update on this host.
`version`	Version	The version of VDSM.

7.109.1. external_status

The host external status. This can be used by third-party software to change the host external status in case of an issue. This has no effect on the host lifecycle, unless a third-party software checks for this status and acts accordingly.

7.109.2. hosted_engine

The self-hosted engine status of this host.

Important

When a host or collection of hosts is retrieved, this attribute is not included unless the all_content parameter of the operation is explicitly set to true. See the documentation of the operations that retrieve one or multiple hosts for details.

7.109.3. kdump_status

The host KDUMP status. KDUMP happens when the host kernel has crashed and it is now going through memory dumping.

7.109.4. ksm

Kernel SamePage Merging (KSM) reduces references to memory pages from multiple identical pages to a single page reference. This helps with optimization for memory density.

For example, to enable KSM for host 123, send a request like this:

PUT /ovirt-engine/api/hosts/123

With a request body like this:

<host>
  <ksm>
    <enabled>true</enabled>
  </ksm>
</host>

7.109.5. libvirt_version

The host libvirt version. For more information on libvirt please go to libvirt.

7.109.6. override_iptables

Specifies whether we should override firewall definitions. This applies only when the host is installed or re-installed.

7.109.7. protocol

The protocol that the engine uses to communicate with the host.

Warning

Since version 4.1 of the engine the protocol is always set to stomp since xml was removed.

7.109.8. se_linux

The host SElinux status. Security-Enhanced Linux (SELinux) is a component in the Linux kernel that provides a mechanism for supporting access control security policies.

7.109.9. spm

The host storage pool manager (SPM) status and definition. Use it to set the SPM priority of this host, and to see whether this is the current SPM or not.

7.109.10. status_detail

The host status details. Relevant for Gluster hosts.

7.109.11. transparent_huge_pages

Transparent huge page support expands the size of memory pages beyond the standard 4 KiB limit. This reduces memory consumption and increases host performance.

For example, to enable transparent huge page support for host 123, send a request like this:

PUT /ovirt-engine/api/hosts/123

With a request body like this:

<host>
  <transparent_hugepages>
    <enabled>true</enabled>
  </transparent_hugepages>
</host>

7.109.12. version

The version of VDSM.

For example:

GET /ovirt-engine/api/hosts/123

This GET request will return the following output:

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

Table 7.150. Links summary

Name	Type	Summary
`affinity_labels`	AffinityLabel[]
`agents`	Agent[]
`cluster`	Cluster
`devices`	Device[]
`external_host_provider`	ExternalHostProvider
`external_network_provider_configurations`	ExternalNetworkProviderConfiguration[]	External network providers provisioned on the host.
`hooks`	Hook[]
`katello_errata`	KatelloErratum[]	Lists all the Katello errata assigned to the host.
`network_attachments`	NetworkAttachment[]
`nics`	HostNic[]
`numa_nodes`	NumaNode[]
`permissions`	Permission[]
`statistics`	Statistic[]	Each host resource exposes a statistics sub-collection for host-specific statistics.
`storage_connection_extensions`	StorageConnectionExtension[]
`storages`	HostStorage[]
`tags`	Tag[]
`unmanaged_networks`	UnmanagedNetwork[]

7.109.13. external_network_provider_configurations

External network providers provisioned on the host.

External network providers on the host can be controlled when adding the host.

7.109.14. katello_errata

Lists all the Katello errata assigned to the host.

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

You will receive response in XML like this one:

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

7.109.15. statistics

Each host resource exposes a statistics sub-collection for host-specific statistics.

An example of an XML representation:

<statistics>
  <statistic href="/ovirt-engine/api/hosts/123/statistics/456" id="456">
    <name>memory.total</name>
    <description>Total memory</description>
    <kind>gauge</kind>
    <type>integer</type>
    <unit>bytes</unit>
    <values>
      <value>
        <datum>25165824000</datum>
      </value>
    </values>
    <host href="/ovirt-engine/api/hosts/123" id="123"/>
  </statistic>
    ...
</statistics>

Note

This statistics sub-collection is read-only.

The following list shows the statistic types for hosts:

Name	Description
`memory.total`	Total memory in bytes on the host.
`memory.used`	Memory in bytes used on the host.
`memory.free`	Memory in bytes free on the host.
`memory.shared`	Memory in bytes shared on the host.
`memory.buffers`	I/O buffers in bytes.
`memory.cached`	OS caches in bytes.
`swap.total`	Total swap memory in bytes on the host.
`swap.free`	Swap memory in bytes free on the host.
`swap.used`	Swap memory in bytes used on the host.
`swap.cached`	Swap memory in bytes also cached in host’s memory.
`ksm.cpu.current`	Percentage of CPU usage for Kernel SamePage Merging.
`cpu.current.user`	Percentage of CPU usage for user slice.
`cpu.current.system`	Percentage of CPU usage for system.
`cpu.current.idle`	Percentage of idle CPU usage.
`cpu.load.avg.5m`	CPU load average per five minutes.
`boot.time`	Boot time of the machine.

7.110. HostDevice struct

Table 7.151. Attributes summary

Name	Type	Summary
`capability`	String
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`driver`	String	The name of the driver this device is bound to.
`id`	String	A unique identifier.
`iommu_group`	Integer
`name`	String	A human-readable name in plain text.
`physical_function`	HostDevice
`placeholder`	Boolean
`product`	Product
`vendor`	Vendor
`virtual_functions`	Integer

7.110.1. driver

The name of the driver this device is bound to.

For example: pcieport or uhci_hcd.

Table 7.152. Links summary

Name	Type	Summary
`host`	Host
`parent_device`	HostDevice
`vm`	Vm

7.111. HostDevicePassthrough struct

Table 7.153. Attributes summary

Name	Type	Summary
`enabled`	Boolean

7.112. HostNic struct

Represents a host NIC.

For example, the XML representation of a host NIC looks like this:

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

A bonded interface is represented as a HostNic object containing the bonding and slaves attributes.

For example, the XML representation of a bonded host NIC looks like this:

<host_nic href="/ovirt-engine/api/hosts/123/nics/456" id="456">
  <name>bond0</name>
  <mac address="00:00:00:00:00:00"/>
  <ip>
    <address>192.168.122.39</address>
    <gateway>192.168.122.1</gateway>
    <netmask>255.255.255.0</netmask>
    <version>v4</version>
  </ip>
  <boot_protocol>dhcp</boot_protocol>
  <bonding>
    <options>
      <option>
        <name>mode</name>
        <value>4</value>
        <type>Dynamic link aggregation (802.3ad)</type>
      </option>
      <option>
        <name>miimon</name>
        <value>100</value>
      </option>
    </options>
    <slaves>
      <host_nic id="123"/>
      <host_nic id="456"/>
    </slaves>
  </bonding>
  <mtu>1500</mtu>
  <bridged>true</bridged>
  <custom_configuration>false</custom_configuration>
</host_nic>

Table 7.154. Attributes summary

Name	Type	Summary
`ad_aggregator_id`	Integer	The `ad_aggregator_id` property of a bond or bond slave, for bonds in mode 4.
`base_interface`	String	The base interface of the NIC.
`bonding`	Bonding	The bonding parameters of the NIC.
`boot_protocol`	BootProtocol	The IPv4 boot protocol configuration of the NIC.
`bridged`	Boolean	Defines the bridged network status.
`check_connectivity`	Boolean
`comment`	String	Free text containing comments about this object.
`custom_configuration`	Boolean
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.
`ip`	Ip	The IPv4 address of the NIC.
`ipv6`	Ip	The IPv6 address of the NIC.
`ipv6_boot_protocol`	BootProtocol	The IPv6 boot protocol configuration of the NIC.
`mac`	Mac	The MAC address of the NIC.
`mtu`	Integer	The maximum transmission unit for the interface.
`name`	String	A human-readable name in plain text.
`network_labels`	NetworkLabel[]	The labels that are applied to this NIC.
`override_configuration`	Boolean
`properties`	Property[]
`speed`	Integer
`statistics`	Statistic[]	A link to the statistics of the NIC.
`status`	NicStatus
`virtual_functions_configuration`	HostNicVirtualFunctionsConfiguration	Describes the virtual functions configuration of a physical function NIC.
`vlan`	Vlan

7.112.1. ad_aggregator_id

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. (See Wikipedia and Presentation for more information). This is only valid for bonds in mode 4, or NICs which are part of a bond. It is not present for bonds in other modes, or NICs which are not part of 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 as 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 the /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.

7.112.2. bridged

Defines the bridged network status. Set to true for a bridged network and false for a bridgeless network.

7.112.3. statistics

A link to the statistics of the NIC.

The data types for HostNic statistical values:

data.current.rx - The rate in bytes per second of data received.
data.current.tx - The rate in bytes per second of data transmitted.
data.current.rx.bps - The rate in bits per second of data received (since version 4.2).
data.current.tx.bps - The rate in bits per second of data transmitted (since version 4.2).
data.total.rx - Total received data.
data.total.tx - Total transmitted data.
errors.total.rx - Total errors from receiving data.
errors.total.tx - Total errors from transmitting data.

Table 7.155. Links summary

Name	Type	Summary
`host`	Host
`network`	Network	A reference to the network to which the interface should be connected.
`physical_function`	HostNic	A reference to the physical function NIC of a SR-IOV virtual function NIC.
`qos`	Qos	A link to the quality-of-service configuration of the interface.

7.112.4. network

A reference to the network to which the interface should be connected. A blank network ID is allowed.

7.113. HostNicVirtualFunctionsConfiguration struct

Describes the virtual functions configuration of an SR-IOV-enabled physical function NIC.

Table 7.156. Attributes summary

Name	Type	Summary
`all_networks_allowed`	Boolean	Defines whether all networks are allowed to be defined on the related virtual functions, or specified ones only.
`max_number_of_virtual_functions`	Integer	The maximum number of virtual functions the NIC supports.
`number_of_virtual_functions`	Integer	The number of virtual functions currently defined.

7.113.1. max_number_of_virtual_functions

The maximum number of virtual functions the NIC supports. This property is read-only.

7.113.2. number_of_virtual_functions

The number of virtual functions currently defined. A user-defined value between 0 and max_number_of_virtual_functions.

7.114. HostProtocol enum

The protocol used by the engine to communicate with a host.

Warning

Since version 4.1 of the engine the protocol is always set to stomp since xml was removed.

Table 7.157. Values summary

Name	Summary
`stomp`	JSON-RPC protocol on top of STOMP.
`xml`	XML-RPC protocol.

7.115. HostStatus enum

Type representing a host status.

Table 7.158. Values summary

Name	Summary
`connecting`	The engine cannot communicate with the host for a specific threshold so it is now trying to connect before going through fencing.
`down`	The host is down.
`error`	The host is in error status.
`initializing`	The host is initializing.
`install_failed`	The host installation failed.
`installing`	The host is being installed.
`installing_os`	The host operating system is now installing.
`kdumping`	The host kernel has crashed and it is now going through memory dumping.
`maintenance`	The host is in maintenance status.
`non_operational`	The host is non operational.
`non_responsive`	The host is not responsive.
`pending_approval`	The host is pending administrator approval.
`preparing_for_maintenance`	The host is preparing for maintenance.
`reboot`	The host is being rebooted.
`unassigned`	The host is in activation process.
`up`	The host is up.

7.115.1. error

The host is in error status. This will happen if we will try to run a virtual machine several times and it will fail.

7.115.2. initializing

The host is initializing. This is an intermediate step before moving the host to 'up' status.

7.115.3. install_failed

The host installation failed. In such cases look at the event log to understand what failed the installation, and issue a re-install.

7.115.4. installing_os

The host operating system is now installing. This status is relevant when using a Satellite/Foreman provider, and issuing a bare-metal provisioning (discovered host provisioning).

7.115.5. maintenance

The host is in maintenance status. When a host is in maintenance it cannot run virtual machines.

7.115.6. non_operational

The host is non operational. This can happen due to various reasons, such as not having a connection with the storage, not supporting a mandatory network, not supporting the cluster level, and more.

7.115.7. non_responsive

The host is not responsive. This means that the engine is not able to communicate with the host.

7.115.8. pending_approval

The host is pending administrator approval. This is relevant only for vintage ovirt-node / RHV-H.

7.115.9. preparing_for_maintenance

The host is preparing for maintenance. During this time the engine makes sure to live migrate all the virtual machines from this host to other hosts. Once all migrations have been completed the host will move to 'maintenance' status.

7.116. HostStorage struct

Table 7.159. Attributes summary

Name	Type	Summary
`address`	String
`comment`	String	Free text containing comments about this object.
`description`	String	A human-readable description in plain text.
`id`	String	A unique identifier.