Chapter 7. Types

This section enumerates all the data types that are available in the API.

7.1. AccessProtocol enum

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

Table 7.1. Values summary

NameSummary

cifs

CIFS access protocol.

gluster

Gluster access protocol.

nfs

NFS access protocol.

7.2. Action struct

Table 7.2. Attributes summary

NameTypeSummary

activate

Boolean

 

allow_partial_import

Boolean

 

async

Boolean

 

attachment

DiskAttachment

 

authorized_key

AuthorizedKey

 

auto_pinning_policy

AutoPinningPolicy

 

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.

commit_on_success

Boolean

 

connection

StorageConnection

 

connectivity_timeout

Integer

 

correlation_id

String

 

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

 

follow

String

 

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_after_restart

Boolean

 

maintenance_enabled

Boolean

 

migrate_vms_in_affinity_closure

Boolean

 

modified_bonds

HostNic[]

 

modified_labels

NetworkLabel[]

 

modified_network_attachments

NetworkAttachment[]

 

name

String

A human-readable name in plain text.

optimize_cpu_settings

Boolean

 

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

 

source_host

Host

 

ssh

Ssh

 

status

String

 

stop_gluster_service

Boolean

 

storage_domain

StorageDomain

 

storage_domains

StorageDomain[]

 

succeeded

Boolean

 

synchronized_network_attachments

NetworkAttachment[]

 

template

Template

 

ticket

Ticket

 

timeout

Integer

 

undeploy_hosted_engine

Boolean

 

upgrade_action

ClusterUpgradeAction

 

upgrade_percent_complete

Integer

 

use_cloud_init

Boolean

 

use_ignition

Boolean

 

use_initialization

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

NameTypeSummary

broken

Boolean

Specifies if the affinity group is broken.

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.

priority

Decimal

Priority of the affinity group.

vms_rule

AffinityRule

Specifies the affinity rule applied to virtual machines that are members of this affinity group.

7.3.1. broken

Specifies if the affinity group is broken. Affinity group is considered broken when any of its rules are not satisfied. Broken field is a computed field in the engine. Because of that, this field is only usable in GET requests.

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

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

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

has_implicit_affinity_group

Boolean

This property enables the legacy behavior for labels.

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

This property enables the legacy behavior for labels. If true, the label acts also as a positive enforcing VM-to-host affinity group.

This parameter is only used for clusters with compatibility version 4.3 or lower.

7.4.2. read_only

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

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

NameTypeSummary

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

NameTypeSummary

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.

7.7. AgentConfiguration struct

Deprecated Agent configuration settings.

Ignored, because the deployment of OpenStack Neutron agent is dropped since Red Hat Virtualization 4.4.0. The deployment of OpenStack hosts can be done by Red Hat OpenStack Platform Director or TripleO.

Table 7.10. Attributes summary

NameTypeSummary

address

String

 

broker_type

MessageBrokerType

 

network_mappings

String

Not recommended to use, because the Open vSwitch interface mappings are managed by VDSM since Red Hat Virtualization 4.

password

String

 

port

Integer

 

username

String

 

7.7.1. network_mappings

Not recommended to use, because the Open vSwitch interface mappings are managed by VDSM since Red Hat Virtualization 4.2.0.

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

NameTypeSummary

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.

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

NameTypeSummary

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

NameTypeSummary

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

NameTypeSummary

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.

7.12. Architecture enum

Table 7.17. Values summary

NameSummary

aarch64

AARCH64 CPU architecture.

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

NameTypeSummary

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.

7.14. AutoNumaStatus enum

Table 7.20. Values summary

NameSummary

disable

 

enable

 

unknown

 

7.15. AutoPinningPolicy enum

Type representing what the CPU and NUMA pinning policy is.

Important

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It will be removed in the future. Instead please use CpuPinningPolicy.

Table 7.21. Values summary

NameSummary

adjust

The CPU and NUMA pinning will be configured by the dedicated host.

disabled

The CPU and NUMA pinning won’t be calculated.

existing

The CPU and NUMA pinning will be configured by the virtual machine current state.

7.15.1. adjust

The CPU and NUMA pinning will be configured by the dedicated host.

Currently, its implication is that the CPU and NUMA pinning will use the dedicated host CPU topology. The virtual machine configuration will automatically be set to fit the host to get the highest possible performance.

7.15.2. disabled

The CPU and NUMA pinning won’t be calculated.

Currently, its implication is that the CPU and NUMA pinning won’t be calculated to the current virtual machine configuration. By default the VM topology set with 1 Socket, 1 Core and 1 Thread.

7.15.3. existing

The CPU and NUMA pinning will be configured by the virtual machine current state.

Currently, its implication is that the CPU and NUMA pinning will use the provided virtual machine CPU topology. Without given CPU topology it will use the engine defaults (the VM topology set with 1 Socket, 1 Core and 1 Thread).

7.16. Backup struct

Table 7.22. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

creation_date

Date

The backup creation date.

description

String

A human-readable description in plain text.

from_checkpoint_id

String

The checkpoint id at which to start the incremental backup.

id

String

A unique identifier.

modification_date

Date

The backup modification date.

name

String

A human-readable name in plain text.

phase

BackupPhase

The phase of the backup operation.

to_checkpoint_id

String

The checkpoint id created by this backup operation.

7.16.1. to_checkpoint_id

The checkpoint id created by this backup operation. This id can be used as the fromCheckpointId in the next incremental backup.

7.17. BackupPhase enum

Table 7.24. Values summary

NameSummary

failed

The final phase, indicates that the backup has failed.

finalizing

In this phase, the backup is invoking 'stop_backup' operation in order to complete the backup and unlock the relevant disk.

initializing

The initial phase of the backup.

ready

The phase means that the relevant disks' backup URLs are ready to be used and downloaded using image transfer.

starting

The phase is set before invoking 'start_backup' operation in vdsm/libvirt (which means that 'stop_backup' should be invoked to complete the flow).

succeeded

The final phase, indicates that the backup has finished successfully.

7.17.1. initializing

The initial phase of the backup. It is set on entity creation.

7.18. Balance struct

Table 7.25. Attributes summary

NameTypeSummary

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.

7.19. Bios struct

Table 7.27. Attributes summary

NameTypeSummary

boot_menu

BootMenu

 

type

BiosType

Chipset and BIOS type combination.

7.20. BiosType enum

Type representing a chipset and a BIOS type combination.

Table 7.28. Values summary

NameSummary

cluster_default

Use the cluster-wide default.

i440fx_sea_bios

i440fx chipset with SeaBIOS.

q35_ovmf

q35 chipset with OVMF (UEFI) BIOS.

q35_sea_bios

q35 chipset with SeaBIOS.

q35_secure_boot

q35 chipset with OVMF (UEFI) BIOS with SecureBoot enabled.

7.20.1. cluster_default

Use the cluster-wide default.

This value cannot be used for cluster.

7.20.2. i440fx_sea_bios

i440fx chipset with SeaBIOS.

For non-x86 architectures this is the only non-default value allowed.

7.21. BlockStatistic struct

Table 7.29. Attributes summary

NameTypeSummary

statistics

Statistic[]

 

7.22. Bonding struct

Represents a network interfaces bond.

Table 7.30. Attributes summary

NameTypeSummary

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.22.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.22.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.22.3. slaves

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

7.23. Bookmark struct

Represents a bookmark in the system.

Table 7.32. Attributes summary

NameTypeSummary

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.24. Boot struct

Configuration of the boot sequence of a virtual machine.

Table 7.33. Attributes summary

NameTypeSummary

devices

BootDevice[]

Ordered list of boot devices.

7.24.1. devices

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

7.25. BootDevice enum

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

Table 7.34. Values summary

NameSummary

cdrom

Boot from CD-ROM.

hd

Boot from the hard drive.

network

Boot from the network, using PXE.

7.25.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.25.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.26. BootMenu struct

Represents boot menu configuration for virtual machines and templates.

Table 7.35. Attributes summary

NameTypeSummary

enabled

Boolean

Whether the boot menu is enabled for this virtual machine (or template), or not.

7.27. BootProtocol enum

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

Table 7.36. Values summary

NameSummary

autoconf

Stateless address auto-configuration.

dhcp

Dynamic host configuration protocol.

none

No address configuration.

poly_dhcp_autoconf

DHCP alongside Stateless address auto-configuration (SLAAC).

static

Statically-defined address, mask and gateway.

7.27.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.27.2. dhcp

Dynamic host configuration protocol.

Please refer to this wikipedia article for more information.

7.27.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.28. BrickProfileDetail struct

Table 7.37. Attributes summary

NameTypeSummary

profile_details

ProfileDetail[]

 

7.29. Cdrom struct

Table 7.39. Attributes summary

NameTypeSummary

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.

7.30. Certificate struct

Table 7.41. Attributes summary

NameTypeSummary

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.31. Checkpoint struct

Table 7.42. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

creation_date

Date

The checkpoint creation date.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

parent_id

String

The parent checkpoint id.

state

CheckpointState

The state of the checkpoint.

7.32. CheckpointState enum

Table 7.44. Values summary

NameSummary

created

The initial state of the checkpoint.

invalid

The INVALID state set when a checkpoint cannot be used anymore for incremental backup and should be removed (For example, after committing to an older VM snapshot).

7.32.1. created

The initial state of the checkpoint. It is set on entity creation.

7.33. 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.45. Attributes summary

NameTypeSummary

authorized_keys

AuthorizedKey[]

 

files

File[]

 

host

Host

 

network_configuration

NetworkConfiguration

 

regenerate_ssh_keys

Boolean

 

timezone

String

 

users

User[]

 

7.34. CloudInitNetworkProtocol enum

Defines the values for the cloud-init protocol. This protocol decides how the cloud-init network parameters are formatted before being passed to the virtual machine in order to be processed by cloud-init.

Protocols supported are cloud-init version dependent. For more information, see Network Configuration Sources

Table 7.46. Values summary

NameSummary

eni

Legacy protocol.

openstack_metadata

Successor of the ENI protocol, with support for IPv6 and more.

7.34.1. eni

Legacy protocol. Does not support IPv6. For more information, see Network Configuration ENI (Legacy)

7.34.2. openstack_metadata

Successor of the ENI protocol, with support for IPv6 and more. This is the default value. For more information, see API: Proxy neutron configuration to guest instance

7.35. 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"
    },
    "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"
      }
    },
    "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.47. Attributes summary

NameTypeSummary

ballooning_enabled

Boolean

 

bios_type

BiosType

Chipset and BIOS type combination.

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.

fips_mode

FipsMode

FIPS mode of the 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 tuned profile.

ha_reservation

Boolean

 

id

String

A unique identifier.

ksm

Ksm

 

log_max_memory_used_threshold

Integer

The memory consumption threshold for logging audit log events.

log_max_memory_used_threshold_type

LogMaxMemoryUsedThresholdType

The memory consumption threshold type for logging audit log events.

maintenance_reason_required

Boolean

This property has no longer any relevance and has been deprecated.

memory_policy

MemoryPolicy

 

migration

MigrationOptions

Reference to cluster-wide configuration of migration of a running virtual machine to another host.

name

String

A human-readable name in plain text.

optional_reason

Boolean

This property has no longer any relevance and has been deprecated.

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

 

upgrade_correlation_id

String

The upgrade correlation identifier.

upgrade_in_progress

Boolean

Indicates if an upgrade has been started for the cluster.

upgrade_percent_complete

Integer

If an upgrade is in progress, the upgrade’s reported percent complete.

version

Version

The compatibility version of the cluster.

virt_service

Boolean

 

vnc_encryption

Boolean

Enable VNC encryption.

7.35.1. bios_type

Chipset and BIOS type combination.

This value is used as default for all virtual machines in the cluster having biosType set to CLUSTER_DEFAULT.

7.35.2. 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.35.3. 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.35.4. fips_mode

FIPS mode of the cluster.

FIPS mode represents the cluster’s policy towards hosts. Hosts added to the cluster will be checked to fulfill the cluster’s FIPS mode, making them non-operational if they do not. Unless a value is explicity provided, new clusters are initialized by default to UNDEFINED. This value changes automatically to the FIPS mode of the first host added to the cluster.

7.35.5. gluster_tuned_profile

The name of the tuned profile.

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

7.35.6. log_max_memory_used_threshold

The memory consumption threshold for logging audit log events.

For percentage, an audit log event is logged if the used memory is more that the value specified. For absolute value, an audit log event is logged when the the free memory falls below the value specified in MB.

7.35.7. log_max_memory_used_threshold_type

The memory consumption threshold type for logging audit log events.

You can choose between 'percentage' and 'absolute_value_in_mb'.

7.35.8. maintenance_reason_required

This property has no longer any relevance and has been deprecated. Its default value is true,

7.35.9. migration

Reference to cluster-wide configuration of migration of a running virtual machine to another host.

Note

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

7.35.10. optional_reason

This property has no longer any relevance and has been deprecated. Its default value is true.

7.35.11. 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.35.12. upgrade_correlation_id

The upgrade correlation identifier. Use to correlate events detailing the cluster upgrade to the upgrade itself.

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

7.35.14. vnc_encryption

Enable VNC encryption. Default value for this property is false.

7.36. ClusterFeature struct

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

Table 7.49. Attributes summary

NameTypeSummary

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.

7.37. ClusterLevel struct

Describes the capabilities supported by a specific cluster level.

Table 7.51. Attributes summary

NameTypeSummary

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.

7.38. ClusterUpgradeAction enum

The action type for cluster upgrade action.

Table 7.53. Values summary

NameSummary

finish

The upgrade action to be passed to finish the cluster upgrade process by marking the cluster’s upgrade_running flag to false.

start

The upgrade action to be passed to start the cluster upgrade process by marking the cluster’s upgrade_running flag to true.

update_progress

The upgrade action to be passed to update the cluster upgrade progress.

7.38.1. finish

The upgrade action to be passed to finish the cluster upgrade process by marking the cluster’s upgrade_running flag to false. This should be used at the end of the cluster upgrade process.

7.38.2. start

The upgrade action to be passed to start the cluster upgrade process by marking the cluster’s upgrade_running flag to true. This should used at the beginning of the cluster upgrade process.

7.38.3. update_progress

The upgrade action to be passed to update the cluster upgrade progress. This should be used as the upgrade progresses.

7.39. Configuration struct

Table 7.54. Attributes summary

NameTypeSummary

data

String

The document describing the virtual machine.

type

ConfigurationType

 

7.39.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.40. ConfigurationType enum

Configuration format types.

Table 7.55. Values summary

NameSummary

ova

ConfigurationType of type standard OVF.

ovf

ConfigurationType of type oVirt-compatible OVF.

7.40.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 the OVF specification.

7.40.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.41. Console struct

Representation for serial console device.

Table 7.56. Attributes summary

NameTypeSummary

enabled

Boolean

Enable/disable the serial console device.

7.42. Core struct

Table 7.57. Attributes summary

NameTypeSummary

index

Integer

 

socket

Integer

 

7.43. Cpu struct

Table 7.58. Attributes summary

NameTypeSummary

architecture

Architecture

 

cores

Core[]

 

cpu_tune

CpuTune

 

level

Integer

 

mode

CpuMode

 

name

String

 

speed

Decimal

 

topology

CpuTopology

 

type

String

 

7.44. CpuMode enum

Table 7.59. Values summary

NameSummary

custom

 

host_model

 

host_passthrough

 

7.45. CpuPinningPolicy enum

Type representing the CPU and NUMA pinning policy.

Table 7.60. Values summary

NameSummary

dedicated

The CPU pinning will be automatically calculated by the engine when a vm starts and it will be dropped when the vm stops.

isolate_threads

The CPU pinning will be automatically calculated by the engine when a vm starts, and it will be dropped when the vm stops.

manual

The CPU pinning will be manually configured.

none

The CPU pinning won’t be configured.

resize_and_pin_numa

The CPU and NUMA pinning will be configured by the dedicated host.

7.45.1. dedicated

The CPU pinning will be automatically calculated by the engine when a vm starts and it will be dropped when the vm stops.

The pinning is exclusive, that means that no other VM can use the pinned physical CPU.

7.45.2. isolate_threads

The CPU pinning will be automatically calculated by the engine when a vm starts, and it will be dropped when the vm stops.

The pinning is exclusive, each virtual thread will get an exclusive physical core. That means that no other VM can use the pinned physical CPU.

7.45.3. manual

The CPU pinning will be manually configured.

Currently, this means that the CPU pinning will be manually configured to the current virtual machine configuration. The VM needs to be pinned to at least one host. The Pinning is provided within the CPU configuration, using CpuTune.

7.45.4. none

The CPU pinning won’t be configured.

Currently, this means that the CPU pinning won’t be configured to the current virtual machine configuration. By default, the VM topology is set with 1 Socket, 1 Core and 1 Thread.

7.45.5. resize_and_pin_numa

The CPU and NUMA pinning will be configured by the dedicated host.

The CPU and NUMA pinning will use the dedicated host CPU topology. The virtual machine configuration will automatically be set to fit the host to get the highest possible performance.

7.46. CpuProfile struct

Table 7.61. Attributes summary

NameTypeSummary

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.

7.47. CpuTopology struct

Table 7.63. Attributes summary

NameTypeSummary

cores

Integer

 

sockets

Integer

 

threads

Integer

 

7.48. CpuTune struct

Table 7.64. Attributes summary

NameTypeSummary

vcpu_pins

VcpuPin[]

 

7.49. CpuType struct

Describes a supported CPU type.

Table 7.65. Attributes summary

NameTypeSummary

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

7.50. CreationStatus enum

Table 7.66. Values summary

NameSummary

complete

 

failed

 

in_progress

 

pending

 

7.51. CustomProperty struct

Custom property representation.

Table 7.67. Attributes summary

NameTypeSummary

name

String

Property name.

regexp

String

A regular expression defining the available values a custom property can get.

value

String

Property value.

7.52. DataCenter struct

Table 7.68. Attributes summary

NameTypeSummary

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

7.53. DataCenterStatus enum

Table 7.70. Values summary

NameSummary

contend

 

maintenance

 

not_operational

 

problematic

 

uninitialized

 

up

 

7.54. Device struct

A device wraps links to potential parents of a device.

Table 7.71. Attributes summary

NameTypeSummary

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.

7.55. Disk struct

Represents a virtual disk device.

Table 7.73. Attributes summary

NameTypeSummary

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

 

backup

DiskBackup

The backup behavior supported by the disk.

backup_mode

DiskBackupMode

The type of the disk backup (full/incremental), visible only when the disk backup is in progress.

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.

external_disk

String

Use external disk.

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

Indicates whether SCSI passthrough is enable and its policy.

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.55.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.55.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.55.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.55.4. external_disk

Use external disk.

An external disk can be a path to a local file or a block device, or a URL supported by QEMU such as:

  • nbd:<host>:<port>[:exportname=<export>]
  • nbd:unix:</path>[:exportname=<export>]
  • http://[<username>[:<password>]@]<host>/<path>
  • https://[<username>[:<password>]@]<host>/<path>
  • ftp://[<username>[:<password>]@]<host>/<path>
  • ftps://[<username>[:<password>]@]<host>/<path>

See the QEMU manual for additional supported protocols and more info.

7.55.5. 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.55.6. 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.55.7. provisioned_size

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

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

7.55.9. 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.55.10. sgio

Indicates whether SCSI passthrough is enable and its policy.

Setting a value of filtered/unfiltered will enable SCSI passthrough for a LUN disk with unprivileged/privileged SCSI I/O. To disable SCSI passthrough the value should be set to disabled

7.55.11. 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.55.12. 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.55.13. 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.

7.56. DiskAttachment struct

Describes how a disk is attached to a virtual machine.

Table 7.75. Attributes summary

NameTypeSummary

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

7.57. DiskBackup enum

Represents an enumeration of the backup mechanism that is enabled on the disk.

Table 7.77. Values summary

NameSummary

incremental

Incremental backup support.

none

No backup support.

7.58. DiskBackupMode enum

Represents an enumeration of backup modes

Table 7.78. Values summary

NameSummary

full

This disk supports full backup.

incremental

This disk supports incremental backup.

7.58.1. full

This disk supports full backup. You can query zero extents and download all disk data.

7.58.2. incremental

This disk supports incremental backup. You can query dirty extents and download changed blocks.

7.59. DiskContentType enum

The actual content residing on the disk.

Table 7.79. Values summary

NameSummary

backup_scratch

The disk contains protected VM backup data.

data

The disk contains data.

hosted_engine

The disk contains the Hosted Engine VM disk.

hosted_engine_configuration

The disk contains the Hosted Engine configuration disk.

hosted_engine_metadata

The disk contains the Hosted Engine metadata disk.

hosted_engine_sanlock

The disk contains the Hosted Engine Sanlock disk.

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.60. DiskFormat enum

The underlying storage format of disks.

Table 7.80. Values summary

NameSummary

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.61. DiskInterface enum

The underlying storage interface of disks communication with controller.

Table 7.81. Values summary

NameSummary

ide

Legacy controller device.

sata

SATA 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.61.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.61.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.61.3. virtio_scsi

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

7.62. DiskProfile struct

Table 7.82. Attributes summary

NameTypeSummary

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.

7.63. DiskSnapshot struct

Table 7.84. Attributes summary

NameTypeSummary

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

 

backup

DiskBackup

The backup behavior supported by the disk.

backup_mode

DiskBackupMode

The type of the disk backup (full/incremental), visible only when the disk backup is in progress.

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.

external_disk

String

Use external disk.

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

Indicates whether SCSI passthrough is enable and its policy.

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.63.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.63.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.63.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.63.4. external_disk

Use external disk.

An external disk can be a path to a local file or a block device, or a URL supported by QEMU such as:

  • nbd:<host>:<port>[:exportname=<export>]
  • nbd:unix:</path>[:exportname=<export>]
  • http://[<username>[:<password>]@]<host>/<path>
  • https://[<username>[:<password>]@]<host>/<path>
  • ftp://[<username>[:<password>]@]<host>/<path>
  • ftps://[<username>[:<password>]@]<host>/<path>

See the QEMU manual for additional supported protocols and more info.

7.63.5. 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.63.6. 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.63.7. provisioned_size

The virtual size of the disk, in bytes.

This attribute is mandatory when creating a new disk.

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

7.63.9. 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.63.10. sgio

Indicates whether SCSI passthrough is enable and its policy.

Setting a value of filtered/unfiltered will enable SCSI passthrough for a LUN disk with unprivileged/privileged SCSI I/O. To disable SCSI passthrough the value should be set to disabled

7.63.11. 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.63.12. 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.63.13. 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.

7.64. DiskStatus enum

Current status representation for disk.

Table 7.86. Values summary

NameSummary

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.64.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.65. DiskStorageType enum

Table 7.87. Values summary

NameSummary

cinder

 

image

 

lun

 

managed_block_storage

A storage type, used for a storage domain that was created using a cinderlib driver.

7.66. DiskType enum

Table 7.88. Values summary

NameSummary

data

 

system

 

7.67. Display struct

Represents a graphic console configuration.

Table 7.89. Attributes summary

NameTypeSummary

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.

disconnect_action_delay

Integer

Delay (in minutes) before the graphic console disconnect action is carried out.

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

The engine now sets it automatically according to the operating system.

smartcard_enabled

Boolean

Indicates if to use smart card authentication.

type

DisplayType

The graphic console protocol type.

7.67.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.67.2. certificate

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

7.67.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.67.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.67.5. disconnect_action_delay

Delay (in minutes) before the graphic console disconnect action is carried out. This option is only available for Shutdown disconnect action.

7.67.6. 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.67.7. 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.67.8. 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.67.9. 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.67.10. 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.67.11. single_qxl_pci

The engine now sets it automatically according to the operating system. Therefore, it has been deprecated since 4.4.5. 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.67.12. smartcard_enabled

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

7.68. DisplayType enum

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

Table 7.90. Values summary

NameSummary

spice

Display of type SPICE.

vnc

Display of type VNC.

7.68.1. spice

Display of type SPICE. See SPICE documentation for more details.

7.68.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.69. Dns struct

Represents the DNS resolver configuration.

Table 7.91. Attributes summary

NameTypeSummary

search_domains

Host[]

Array of hosts serving as search domains.

servers

Host[]

Array of hosts serving as DNS servers.

7.70. DnsResolverConfiguration struct

Represents the DNS resolver configuration.

Table 7.92. Attributes summary

NameTypeSummary

name_servers

String[]

Array of addresses of name servers.

7.70.1. name_servers

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

7.71. Domain struct

This type represents a directory service domain.

Table 7.93. Attributes summary

NameTypeSummary

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

 

7.72. DynamicCpu struct

Configuration of the Dynamic CPUs of a virtual machine.

Table 7.95. Attributes summary

NameTypeSummary

cpu_tune

CpuTune

 

topology

CpuTopology

 

7.73. EntityExternalStatus enum

Type representing an external entity status.

Table 7.96. Values summary

NameSummary

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

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

7.73.2. failure

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

7.74. EntityProfileDetail struct

Table 7.97. Attributes summary

NameTypeSummary

profile_details

ProfileDetail[]

 

7.75. ErrorHandling struct

Table 7.98. Attributes summary

NameTypeSummary

on_error

MigrateOnError

 

7.76. Event struct

Type representing an event.

Table 7.99. Attributes summary

NameTypeSummary

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.

log_on_host

Boolean

Specifies whether the event should also be written to the ${hypervisor.

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

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

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

7.76.4. log_on_host

Specifies whether the event should also be written to the ${hypervisor.name} log. If no host is specified the event description will be written to all hosts. Default is false.

7.77. EventSubscription struct

Table 7.101. Attributes summary

NameTypeSummary

address

String

The email address to which notifications should be sent.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

event

NotifiableEvent

The subscribed-for event.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

notification_method

NotificationMethod

The notification method: SMTP or SNMP.

user

User

The subscribing user.

7.77.1. address

The email address to which notifications should be sent.

When not provided, notifications are sent to the user’s email. Only a single address per user is currently supported. If a subscription with a different email address to that of existing subscriptions is added, a 409 (CONFLICT) status is returned with an explanation that the provided address conflicts with an existing address of an event-subscription for this user.

This field might be deprecated in the future, and notifications will always be sent on the user’s email address.

7.77.2. event

The subscribed-for event.

(Combined with the user, Uniquely identifies the event-subscription).

7.77.3. notification_method

The notification method: SMTP or SNMP.

Currently only SMTP supported by API. Support for SNMP will be added in the future.

7.77.4. user

The subscribing user.

Combined with the event-name, uniquely identifies the event-subscription.

7.78. ExternalComputeResource struct

Table 7.102. Attributes summary

NameTypeSummary

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

 

7.79. ExternalDiscoveredHost struct

Table 7.104. Attributes summary

NameTypeSummary

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

 

7.80. ExternalHost struct

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

See Foreman documentation for more details. See Satellite documentation for more details on Red Hat Satellite.

Table 7.106. Attributes summary

NameTypeSummary

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.

7.81. ExternalHostGroup struct

Table 7.108. Attributes summary

NameTypeSummary

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

 

7.82. ExternalHostProvider struct

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

See Foreman documentation for more details. See Satellite documentation for more details on Red Hat Satellite.

Table 7.110. Attributes summary

NameTypeSummary

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.82.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.83. ExternalNetworkProviderConfiguration struct

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

Table 7.112. Attributes summary

NameTypeSummary

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.

7.84. ExternalProvider struct

Represents an external provider.

Table 7.114. Attributes summary

NameTypeSummary

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.84.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.85. 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.115. Values summary

NameSummary

error

Error status.

failure

Failure status.

info

Info status.

ok

OK status.

warning

Warning status.

7.85.1. error

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

7.85.2. failure

Failure status. The relevant object is failing.

7.85.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.85.4. ok

OK status. The relevant object is working well.

7.85.5. warning

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

7.86. ExternalSystemType enum

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

Table 7.116. Values summary

NameSummary

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.87. ExternalTemplateImport struct

Describes the parameters for the template import operation from an external system. Currently supports OVA only.

Table 7.117. Attributes summary

NameTypeSummary

clone

Boolean

Optional.

url

String

The URL to be passed to the engine.

7.87.1. clone

Optional. Indicates if the identifiers of the imported template should be regenerated.

By default when a template is imported the identifiers are preserved. This means that the same template can’t be imported multiple times, as that identifiers needs to be unique. To allow importing the same template multiple times set this parameter to true, as the default is false.

7.87.2. url

The URL to be passed to the engine.

Example:

ova:///mnt/ova/ova_file.ova

7.88. ExternalVmImport struct

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

Table 7.119. Attributes summary

NameTypeSummary

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

Optional.

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

Optional. Specifies the disk allocation policy of the resulting virtual machine: true for sparse, false for preallocated.

If not specified: - When importing an OVA that was produced by oVirt, it will be determined according to the configuration of the disk within the OVF. - Otherwise, it will be set to true.

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

7.89. ExternalVmProviderType enum

Describes the type of external hypervisor system.

Table 7.121. Values summary

NameSummary

kvm

 

vmware

 

xen

 

7.90. Fault struct

Table 7.122. Attributes summary

NameTypeSummary

detail

String

 

reason

String

 

7.91. FenceType enum

Type representing the type of the fence operation.

Table 7.123. Values summary

NameSummary

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.92. FencingPolicy struct

Type representing a cluster fencing policy.

Table 7.124. Attributes summary

NameTypeSummary

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.92.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.92.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.92.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.92.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.93. File struct

Table 7.125. Attributes summary

NameTypeSummary

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

 

7.94. Filter struct

Table 7.127. Attributes summary

NameTypeSummary

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

 

7.95. FipsMode enum

Representation of the FIPS mode to the cluster.

Table 7.129. Values summary

NameSummary

disabled

The FIPS mode is disabled.

enabled

The FIPS mode is enabled.

undefined

The FIPS mode is not yet evaluated.

7.95.1. disabled

The FIPS mode is disabled.

Its implication is that the FIPS mode is disabled and the hosts within should be with FIPS mode disabled, otherwise they would be non-operational.

7.95.2. enabled

The FIPS mode is enabled.

Its implication is that the FIPS mode is enabled and the hosts within should be with FIPS mode enabled, otherwise they should be non-operational.

7.95.3. undefined

The FIPS mode is not yet evaluated.

Currently, its implication is that the FIPS mode is undetermined. Once a host is added, this value will switch according to the host settings.

7.96. FirewallType enum

Describes all firewall types supported by the system.

Table 7.130. Values summary

NameSummary

firewalld

FirewallD firewall type.

iptables

IPTables firewall type.

7.96.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.96.2. iptables

IPTables firewall type.

iptables is deprecated.

7.97. Floppy struct

The underlying representation of a floppy file.

Table 7.131. Attributes summary

NameTypeSummary

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.

7.98. FopStatistic struct

Table 7.133. Attributes summary

NameTypeSummary

name

String

 

statistics

Statistic[]

 

7.99. GlusterBrick struct

Table 7.134. Attributes summary

NameTypeSummary

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

 

7.100. GlusterBrickAdvancedDetails struct

Table 7.136. Attributes summary

NameTypeSummary

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

 

7.101. GlusterBrickMemoryInfo struct

Table 7.138. Attributes summary

NameTypeSummary

memory_pools

GlusterMemoryPool[]

 

7.102. GlusterBrickStatus enum

Table 7.139. Values summary

NameSummary

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.103. GlusterClient struct

Table 7.140. Attributes summary

NameTypeSummary

bytes_read

Integer

 

bytes_written

Integer

 

client_port

Integer

 

host_name

String

 

7.104. GlusterHook struct

Table 7.141. Attributes summary

NameTypeSummary

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

 

7.105. GlusterHookStatus enum

Table 7.143. Values summary

NameSummary

disabled

Hook is disabled in the cluster.

enabled

Hook is enabled in the cluster.

missing

Unknown/missing hook status.

7.106. GlusterMemoryPool struct

Table 7.144. Attributes summary

NameTypeSummary

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.107. GlusterServerHook struct

Table 7.145. Attributes summary

NameTypeSummary

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

 

7.108. GlusterState enum

Table 7.147. Values summary

NameSummary

down

 

unknown

 

up

 

7.109. GlusterVolume struct

Table 7.148. Attributes summary

NameTypeSummary

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

 

7.110. GlusterVolumeProfileDetails struct

Table 7.150. Attributes summary

NameTypeSummary

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.111. GlusterVolumeStatus enum

Table 7.151. Values summary

NameSummary

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.112. GlusterVolumeType enum

Type representing the type of Gluster Volume.

Table 7.152. Values summary

NameSummary

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.112.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.112.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.112.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.112.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.112.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.112.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.112.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.112.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.112.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.113. GracePeriod struct

Table 7.153. Attributes summary

NameTypeSummary

expiry

Integer

 

7.114. GraphicsConsole struct

Table 7.154. Attributes summary

NameTypeSummary

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

 

7.115. GraphicsType enum

The graphics protocol used to connect to the graphic console.

Table 7.156. Values summary

NameSummary

spice

Graphics protocol of type SPICE.

vnc

Graphics protocol of type VNC.

7.115.1. spice

Graphics protocol of type SPICE. See SPICE documentation for more details.

7.115.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.116. Group struct

This type represents all groups in the directory service.

Table 7.157. Attributes summary

NameTypeSummary

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.

7.117. 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.159. Attributes summary

NameTypeSummary

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.118. 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.160. Attributes summary

NameTypeSummary

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.119. HighAvailability struct

Type representing high availability of a virtual machine.

Table 7.161. Attributes summary

NameTypeSummary

enabled

Boolean

Define if the virtual machine is considered highly available.

priority

Integer

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

7.119.1. enabled

Define if the virtual machine is considered highly available. Configuring a VM lease is highly recommended (refer to that section) in order to prevent split-brain scenarios. Use a boot disk’s storage-domain or any other active storage-domain.

7.119.2. 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 ValueGUI 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 LabelAPI Value

Low

1

Medium

50

High

100

7.120. Hook struct

Represents a hook.

Table 7.162. Attributes summary

NameTypeSummary

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.

7.121. HookContentType enum

Represents content type of hook script.

Table 7.164. Values summary

NameSummary

binary

Binary content type of the hook.

text

Text content type of the hook.

7.122. HookStage enum

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

Table 7.165. Values summary

NameSummary

post

Stage after start of volume.

pre

Stage before start of volume.

7.123. HookStatus enum

Type represents the status of a hook.

Table 7.166. Values summary

NameSummary

disabled

Hook is disabled.

enabled

Hook is enabled.

missing

Hook is missing.

7.124. Host struct

Type representing a host.

Table 7.167. Attributes summary

NameTypeSummary

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', 'sync networks', or 'refresh capabilities', 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.

ovn_configured

Boolean

Indicates if the host has correctly configured OVN.

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.

reinstallation_required

Boolean

Specifies whether the host should be reinstalled.

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.

vgpu_placement

VgpuPlacement

Specifies the vGPU placement strategy.

7.124.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.124.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.124.3. kdump_status

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

7.124.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.124.5. libvirt_version

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

7.124.6. network_operation_in_progress

Specifies whether a network-related operation, such as 'setup networks', 'sync networks', or 'refresh capabilities', is currently being executed on this host.

Note

The header All-Content:true must be added to the request in order for this attribute to be included in the response.

7.124.7. override_iptables

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

7.124.8. 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.124.9. 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.124.10. 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.124.11. status_detail

The host status details. Relevant for Gluster hosts.

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

7.125. HostCpuUnit struct

Type representing a physical CPU of a host with the current pinning status.

Table 7.169. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

core_id

Integer

The id of the core the CPU belongs to.

cpu_id

Integer

The id of the CPU.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

runs_vdsm

Boolean

A flag indicating that the CPU runs the VDSM

socket_id

Integer

The id of the socket the CPU belongs to.

7.126. HostDevice struct

Table 7.171. Attributes summary

NameTypeSummary

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

 

m_dev_types

MDevType[]

List of all supported mdev types on the physical device,

name

String

A human-readable name in plain text.

physical_function

HostDevice

 

placeholder

Boolean

 

product

Product

 

vendor

Vendor

 

virtual_functions

Integer

 

7.126.1. driver

The name of the driver this device is bound to.

For example: pcieport or uhci_hcd.

7.127. HostDevicePassthrough struct

Table 7.173. Attributes summary

NameTypeSummary

enabled

Boolean

 

7.128. 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.174. Attributes summary

NameTypeSummary

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.

override_configuration

Boolean

 

properties

Property[]

 

speed

Integer

 

status

NicStatus

 

virtual_functions_configuration

HostNicVirtualFunctionsConfiguration

Describes the virtual functions configuration of a physical function NIC.

vlan

Vlan

 

7.128.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.128.2. bridged

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

7.129. HostNicVirtualFunctionsConfiguration struct

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

Table 7.176. Attributes summary

NameTypeSummary

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

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

7.129.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.130. 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.177. Values summary

NameSummary

stomp

JSON-RPC protocol on top of STOMP.

xml

XML-RPC protocol.

7.131. HostStatus enum

Type representing a host status.

Table 7.178. Values summary

NameSummary

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.131.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.131.2. initializing

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

7.131.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.131.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.131.5. maintenance

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

7.131.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.131.7. non_responsive

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

7.131.8. pending_approval

The host is pending administrator approval. This is relevant only for vintage ovirt-node / RHV-H. This property is no longer relevant since Vintage Node is no longer supported, and has been deprecated.

7.131.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.132. HostStorage struct

Table 7.179. Attributes summary

NameTypeSummary

address

String

 

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

driver_options

Property[]

The options to be passed when creating a storage domain using a cinder driver.

driver_sensitive_options

Property[]

Parameters containing sensitive information, to be passed when creating a storage domain using a cinder driver.

id

String

A unique identifier.

logical_units

LogicalUnit[]

 

mount_options

String

 

name

String

A human-readable name in plain text.

nfs_retrans

Integer

The number of times to retry a request before attempting further recovery actions.

nfs_timeo

Integer

The time in tenths of a second to wait for a response before retrying NFS requests.

nfs_version

NfsVersion

 

override_luns

Boolean

 

password

String

 

path

String

 

port

Integer

 

portal

String

 

target

String

 

type

StorageType

 

username

String

 

vfs_type

String

 

volume_group

VolumeGroup

 

7.132.1. driver_options

The options to be passed when creating a storage domain using a cinder driver.

For example (Kaminario backend):

POST /ovirt-engine/api/storagedomains/
<storage_domain>
 <name>kamniraio-cinder</name>
 <type>managed_block_storage</type>
 <storage>
   <type>managed_block_storage</type>
   <driver_options>
     <property>
       <name>san_ip</name>
       <value>192.168.1.1</value>
     </property>
     <property>
       <name>san_login</name>
       <value>username</value>
     </property>
     <property>
       <name>san_password</name>
       <value>password</value>
     </property>
     <property>
       <name>use_multipath_for_image_xfer</name>
       <value>true</value>
     </property>
     <property>
       <name>volume_driver</name>
       <value>cinder.volume.drivers.kaminario.kaminario_iscsi.KaminarioISCSIDriver</value>
     </property>
   </driver_options>
 </storage>
 <host>
   <name>host</name>
   </host>
</storage_domain>

7.132.2. driver_sensitive_options

Parameters containing sensitive information, to be passed when creating a storage domain using a cinder driver. These parameters are encrypted when they are saved.

For example, the following XML encrypts and saves a username, password and SAN IP address:

POST /ovirt-engine/api/storagedomains/
<storage_domain>
 <name>kamniraio-cinder</name>
 <type>managed_block_storage</type>
 <storage>
   <type>managed_block_storage</type>
   <driver_options>
     <property>
       <name>san_ip</name>
       <value>192.168.1.1</value>
     </property>
     <property>
       <name>san_login</name>
       <value>username</value>
     </property>
     <property>
       <name>san_password</name>
       <value>password</value>
     </property>
     <property>
       <name>use_multipath_for_image_xfer</name>
       <value>true</value>
     </property>
     <property>
       <name>volume_driver</name>
       <value>cinder.volume.drivers.kaminario.kaminario_iscsi.KaminarioISCSIDriver</value>
     </property>
   </driver_options>
   <driver_sensitive_options>
     <property>
       <name>username</name>
       <value>admin</value>
     </property>
     <property>
       <name>password</name>
       <value>123</value>
     </property>
     <property>
       <name>san_ip</name>
       <value>192.168.1.1</value>
     </property>
   </driver_sensitive_options>
 </storage>
 <host>
   <name>host</name>
 </host>
</storage_domain>

7.132.3. nfs_retrans

The number of times to retry a request before attempting further recovery actions. The value must be in the range of 0 to 65535. For more details see the description of the retrans mount option in the nfs man page.

7.132.4. nfs_timeo

The time in tenths of a second to wait for a response before retrying NFS requests. The value must be in the range of 0 to 65535. For more details see the description of the timeo mount option in the nfs man page.

7.133. HostType enum

This enumerated type is used to determine which type of operating system is used by the host.

Table 7.181. Values summary

NameSummary

ovirt_node

The host contains Red Hat Virtualization Host (RHVH): a new implementation of Red Hat Enterprise Virtualization Hypervisor (RHEV-H) which uses the same installer as Red Hat Enterprise Linux, CentOS, or Fedora.

rhel

The host contains a full Red Hat Enterprise Linux, CentOS, or Fedora installation.

rhev_h

The host contains Red Hat Enterprise Virtualization Hypervisor (RHEV-H), a small-scaled version of Red Hat Enterprise Linux, CentOS, or Fedora, used solely to host virtual machines.

7.133.1. ovirt_node

The host contains Red Hat Virtualization Host (RHVH): a new implementation of Red Hat Enterprise Virtualization Hypervisor (RHEV-H) which uses the same installer as Red Hat Enterprise Linux, CentOS, or Fedora. The main difference between RHVH and legacy RHEV-H is that RHVH has a writeable file system and will handle its own installation instead of having RPMs pushed to it by the Manager like in legacy RHEV-H.

7.133.2. rhev_h

The host contains Red Hat Enterprise Virtualization Hypervisor (RHEV-H), a small-scaled version of Red Hat Enterprise Linux, CentOS, or Fedora, used solely to host virtual machines.

This property is no longer relevant since Vintage Node is no longer supported, and has been deprecated.

7.134. HostedEngine struct

Table 7.182. Attributes summary

NameTypeSummary

active

Boolean

 

configured

Boolean

 

global_maintenance

Boolean

 

local_maintenance

Boolean

 

score

Integer

 

7.135. Icon struct

Icon of virtual machine or template.

Table 7.183. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

data

String

Base64 encode content of the icon file.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

media_type

String

Format of icon file.

name

String

A human-readable name in plain text.

7.135.1. media_type

Format of icon file.

One of:

  • image/jpeg
  • image/png
  • image/gif

7.136. Identified struct

This interface is the base model for all types that represent objects with an identifier.

Table 7.184. Attributes summary

NameTypeSummary

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.

7.137. Image struct

Represents an image entity.

Table 7.185. Attributes summary

NameTypeSummary

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.

size

Integer

The size of the image file.

type

ImageFileType

The type of the image file.

7.138. ImageFileType enum

Represents the file type of an image.

Table 7.187. Values summary

NameSummary

disk

The image is a disk format that can be used as a virtual machine’s disk.

floppy

The image is a floppy disk that can be attached to a virtual machine, for example to install the VirtIO drivers in Windows.

iso

The image is a `.

7.138.1. iso

The image is a .iso file that can be used as a CD-ROM to boot and install a virtual machine.

7.139. ImageTransfer struct

This type contains information regarding an image transfer being performed.

Table 7.188. Attributes summary

NameTypeSummary

active

Boolean

Indicates whether there’s at least one active session for this transfer, i,e there’s at least one live transfer session between the client and the daemon.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

direction

ImageTransferDirection

The direction indicates whether the transfer is sending image data (upload) or receiving image data (download).

format

DiskFormat

The format of the data sent during upload or received during download.

id

String

A unique identifier.

inactivity_timeout

Integer

The timeout in seconds of client inactivity, after which the transfer is aborted by the Red Hat Virtualization Manager.

name

String

A human-readable name in plain text.

phase

ImageTransferPhase

The current phase of the image transfer in progress.

proxy_url

String

The URL of the proxy server that the user inputs or outputs to.

shallow

Boolean

Download only the specified image instead of the entire image chain.

timeout_policy

ImageTransferTimeoutPolicy

Timeout policy determines how the system handles the transfer when a client is idle for more than inactivityTimeout.

transfer_url

String

The URL of the daemon server that the user can input or output to directly.

transferred

Integer

Indicates the amount of transferred bytes.

7.139.1. direction

The direction indicates whether the transfer is sending image data (upload) or receiving image data (download).

If a direction is not set during an addition of a new transfer, The default direction for the transfer will be upload.

7.139.2. format

The format of the data sent during upload or received during download. If not specified, defaults to disk’s format.

7.139.3. inactivity_timeout

The timeout in seconds of client inactivity, after which the transfer is aborted by the Red Hat Virtualization Manager. To disable the inactivity timeout specify '0'. If not specified, the value is defaulted to the engine-config value: TransferImageClientInactivityTimeoutInSeconds.

7.139.4. phase

The current phase of the image transfer in progress. Each transfer needs a managed session, which must be opened for the user to input or output an image. Please refer to image transfer for further documentation.

7.139.5. proxy_url

The URL of the proxy server that the user inputs or outputs to. This attribute is available only if the image transfer is in the transferring phase. See phase for details.

7.139.6. shallow

Download only the specified image instead of the entire image chain.

If true, when using format="raw" and direction="download", the transfer includes data only from the specified disk snapshot, and unallocated areas are reported as holes. By default, the transfer includes data from all disk snapshots.

When specifying a disk snapshot, the transfer includes only data for the specified disk snapshot. When specifying a disk, the transfer includes only data from the active disk snaphost.

This parameter has no effect when not using format="raw" or for direction="upload".

Example: Downloading a single snapshot:

<image_transfer>
  <snapshot id="2fb24fa2-a5db-446b-b733-4654661cd56d"/>
  <direction>download</direction>
  <format>raw</format>
  <shallow>true</shallow>
</image_transfer>

To download the active snapshot disk image (which is not accessible as a disk snapshot), specify the disk:

<image_transfer>
  <disk id="ff6be46d-ef5d-41d6-835c-4a68e8956b00"/>
  <direction>download</direction>
  <format>raw</format>
  <shallow>true</shallow>
</image_transfer>

In both cases you can now download a qcow2 image using imageio client:

from ovirt_imageio import client

client.download(
  transfer.transfer_url,
  "51275e7d-42e9-491f-9d65-b9211c897eac",
  backing_file="07c0ccac-0845-4665-9097-d0a3b16cf43b",
  backing_format="qcow2")

7.139.7. transfer_url

The URL of the daemon server that the user can input or output to directly.

This is as an alternative to the proxy_url. I.e. if the client has access to the host machine, it could bypass the proxy and transfer directly to the host, potentially improving the throughput performance. This attribute is available only if the image transfer is in the transferring phase. See phase for details.

7.140. ImageTransferDirection enum

The image transfer direction for a transfer.

When adding a new transfer, the user can choose whether the transfer will be to an image, choosing upload, or to transfer from an image- choosing download as an ImageTransferDirection.

Please refer to image transfer for further documentation.

Table 7.190. Values summary

NameSummary

download

The user must choose download when he/she wants to stream data from an image.

upload

The user can choose upload when he/she wants to stream data to an image.

7.141. ImageTransferPhase enum

A list of possible phases for an image transfer entity. Each of these values defines a specific point in a transfer flow.

Please refer to image transfer for more information.

Table 7.191. Values summary

NameSummary

cancelled

This phase will be set as a result of the user cancelling the transfer.

cancelled_system

This phase will be set as a result of the system cancelling the transfer.

cancelled_user

This phase will be set as a result of the user cancelling the transfer.

finalizing_cleanup

This phase indicates that the user cancelled the transfer, and necessary cleanup is being done.

finalizing_failure

This phase can only be set in the Administration Portal, and indicates that there was an error during the transfer, and it is being finalized with a failure.

finalizing_success

This phase will be set when the user calls finalize.

finished_cleanup

This phase indicates that the user cancelled the transfer, and necessary cleanup is done.

finished_failure

Indicates that the targeted image failed the verification, and cannot be used.

finished_success

Indicates that the transfer session was successfully closed, and the targeted image was verified and ready to be used.

initializing

The initial phase of an image transfer.

paused_system

This phase means the session timed out, or some other error occurred with this transfer; for example ovirt-imageio is not running in the selected host.

paused_user

This phase is a result of a pause call by the user, using pause.

resuming

The phase where the transfer has been resumed by the client calling resume.

transferring

The phase where the transfer session is open, and the client can input or output the desired image using the preferred tools.

unknown

An unknown phase.

7.141.1. cancelled

This phase will be set as a result of the user cancelling the transfer. The cancellation can only be performed in the Administration Portal.

7.141.2. finalizing_success

This phase will be set when the user calls finalize. Calling finalize is essential to finish the transfer session, and finish using the targeted image. After finalizing, the phase will be changed to finished_success or finished_failure.

Refer to image transfer for more information.

7.141.3. finished_failure

Indicates that the targeted image failed the verification, and cannot be used. After reaching this phase, the image transfer entity will be deleted, and the targeted image will be set to illegal. System cancelling the transfer will also result in this.

7.141.4. finished_success

Indicates that the transfer session was successfully closed, and the targeted image was verified and ready to be used. After reaching this phase, the image transfer entity will be deleted.

7.141.5. initializing

The initial phase of an image transfer. It is set while the transfer session is establishing. Once the session is established, the phase will be changed to transferring

7.141.6. paused_system

This phase means the session timed out, or some other error occurred with this transfer; for example ovirt-imageio is not running in the selected host. To resume the session, the client should call resume. After resuming, the phase will change to resuming.

7.141.7. resuming

The phase where the transfer has been resumed by the client calling resume. Resuming starts a new session, and after calling it, the phase will be changed to transferring, or paused_system in case of a failure.

7.141.8. unknown

An unknown phase. This will only be set in cases of unpredictable errors.

7.142. ImageTransferTimeoutPolicy enum

The image transfer timeout policy.

Define how the system handles a transfer when the client is inactive for inactivityTimeout seconds.

Please refer to image transfer for further documentation.

Table 7.192. Values summary

NameSummary

cancel

Cancel the transfer and unlock the disk.

legacy

LEGACY policy will preserve the legacy functionality which is the default.

pause

Pause the transfer.

7.142.1. cancel

Cancel the transfer and unlock the disk. For image transfer using upload direction, the disk is deleted.

7.142.2. legacy

LEGACY policy will preserve the legacy functionality which is the default. The default behaviour will cancel the transfer if the direction is download, and pause it if its upload.

7.142.3. pause

Pause the transfer. The transfer can be resumed or canceled by the user. The disk will remain locked while the transfer is paused.

7.143. InheritableBoolean enum

Enum representing the boolean value that can be either set, or inherited from a higher level. The inheritance order is virtual machine → cluster → engine-config.

Table 7.193. Values summary

NameSummary

false

Set the value to false on this level.

inherit

Inherit the value from higher level.

true

Set the value to true on this level.

7.144. Initialization struct

Table 7.194. Attributes summary

NameTypeSummary

active_directory_ou

String

 

authorized_ssh_keys

String

 

cloud_init

CloudInit

Deprecated attribute to specify cloud-init configuration.

cloud_init_network_protocol

CloudInitNetworkProtocol

Attribute specifying the cloud-init protocol to use for formatting the cloud-init network parameters.

configuration

Configuration

 

custom_script

String

 

dns_search

String

 

dns_servers

String

 

domain

String

 

host_name

String

 

input_locale

String

 

nic_configurations

NicConfiguration[]

 

org_name

String

 

regenerate_ids

Boolean

 

regenerate_ssh_keys

Boolean

 

root_password

String

 

system_locale

String

 

timezone

String

 

ui_language

String

 

user_locale

String

 

user_name

String

 

windows_license_key

String

 

7.144.1. cloud_init

Deprecated attribute to specify cloud-init configuration.

This attribute and the CloudInit type have been deprecated and will be removed in the future. To specify the cloud-init configuration, use the attributes inside the Initialization type. The mapping between the attributes of these two types are as follows:

CloudInitInitialization

authorized_keys

authorized_ssh_keys

dns.search_domains

dns_search

dns.servers

dns_servers

files

custom_script

host

host_name

network_configuration.nics

nic_configurations

regenerate_ssh_keys

regenerate_ssh_keys

timezone

timezone

users

user_name & root_password

For more details on how to use cloud-init see the examples in Python and Java.

7.144.2. cloud_init_network_protocol

Attribute specifying the cloud-init protocol to use for formatting the cloud-init network parameters. If omitted, a default value is used, as described in the CloudInitNetworkProtocol

7.145. InstanceType struct

Describes the hardware configuration of virtual machines.

For example medium instance type includes 1 virtual CPU and 4 GiB of memory. It is a top-level entity (e.g. not bound to any data center or cluster). The attributes that are used for instance types and are common to virtual machine and template types are:

  • console
  • cpu
  • custom_cpu_model
  • custom_emulated_machine
  • display
  • high_availability
  • io
  • memory
  • memory_policy
  • migration
  • migration_downtime
  • os
  • rng_device
  • soundcard_enabled
  • usb
  • virtio_scsi

When creating a virtual machine from both an instance type and a template, the virtual machine will inherit the hardware configurations from the instance type

Note

An instance type inherits it’s attributes from the template entity although most template attributes are not used in instance types.

Table 7.195. Attributes summary

NameTypeSummary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

 

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

 

custom_emulated_machine

String

 

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

status

TemplateStatus

The status of the template.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

version

TemplateVersion

Indicates whether this is the base version or a sub-version of another template.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

vm

Vm

The virtual machine configuration associated with this template.

7.145.1. auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Important

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

7.145.2. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

7.145.3. cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

7.145.4. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

7.145.5. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.145.6. initialization

Reference to the virtual machine’s initialization configuration.

Note

Since Red Hat Virtualization 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

7.145.7. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.145.8. lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

7.145.9. memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since Red Hat Virtualization 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Red Hat Virtualization Manager internally rounds values down to whole MiBs (1MiB = 220 bytes)

7.145.10. migration

Reference to configuration of migration of a running virtual machine to another host.

Note

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

7.145.11. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

7.145.12. origin

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.145.13. placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

7.145.14. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.145.15. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

7.145.16. tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

7.146. Io struct

Table 7.197. Attributes summary

NameTypeSummary

threads

Integer

 

7.147. Ip struct

Represents the IP configuration of a network interface.

Table 7.198. Attributes summary

NameTypeSummary

address

String

The text representation of the IP address.

gateway

String

The address of the default gateway.

netmask

String

The network mask.

version

IpVersion

The version of the IP protocol.

7.147.1. address

The text representation of the IP address.

For example, an IPv4 address will be represented as follows:

<ip>
  <address>192.168.0.1</address>
  ...
</ip>

An IPv6 address will be represented as follows:

<ip>
  <address>2620:52:0:20f0:4216:7eff:feaa:1b50</address>
  ...
</ip>

7.147.2. netmask

The network mask.

For IPv6 addresses the value is an integer in the range of 0-128, which represents the subnet prefix.

7.147.3. version

The version of the IP protocol.

Note

From version 4.1 of the Manager this attribute will be optional, and when a value is not provided, it will be inferred from the value of the address attribute.

7.148. IpAddressAssignment struct

Represents an IP address assignment for a network device.

For a static boot protocol assignment, subnet mask and IP address (and optinally default gateway) must be provided in the IP configuration.

Table 7.199. Attributes summary

NameTypeSummary

assignment_method

BootProtocol

Sets the boot protocol used to assign the IP configuration for a network device.

ip

Ip

Sets the IP configuration for a network device.

7.149. IpVersion enum

Defines the values for the IP protocol version.

Table 7.200. Values summary

NameSummary

v4

IPv4.

v6

IPv6.

7.150. IscsiBond struct

Table 7.201. Attributes summary

NameTypeSummary

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.

7.151. IscsiDetails struct

Table 7.203. Attributes summary

NameTypeSummary

address

String

 

disk_id

String

 

initiator

String

 

lun_mapping

Integer

 

password

String

 

paths

Integer

 

port

Integer

 

portal

String

 

product_id

String

 

serial

String

 

size

Integer

 

status

String

 

storage_domain_id

String

 

target

String

 

username

String

 

vendor_id

String

 

volume_group_id

String

 

7.152. Job struct

Represents a job, which monitors execution of a flow in the system. A job can contain multiple steps in a hierarchic structure. The steps can be processed in parallel, depends on the implementation of the flow.

Table 7.204. Attributes summary

NameTypeSummary

auto_cleared

Boolean

Indicates if the job should be cleared automatically after it was completed by the system.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

end_time

Date

The end time of the job.

external

Boolean

Indicates if the job is originated by an external system.

id

String

A unique identifier.

last_updated

Date

The last update date of the job.

name

String

A human-readable name in plain text.

start_time

Date

The start time of the job.

status

JobStatus

The status of the job.

7.152.1. external

Indicates if the job is originated by an external system. External jobs are managed externally, by the creator of the job.

7.153. JobStatus enum

Represents the status of the job.

Table 7.206. Values summary

NameSummary

aborted

The aborted job status.

failed

The failed job status.

finished

The finished job status.

started

The started job status.

unknown

The unknown job status.

7.153.1. aborted

The aborted job status. This status is applicable for an external job that was forcibly aborted.

7.153.2. finished

The finished job status. This status describes a completed job execution.

7.153.3. started

The started job status. This status represents a job which is currently being executed.

7.153.4. unknown

The unknown job status. This status represents jobs which their resolution is not known, i.e. jobs that were executed before the system was unexpectedly restarted.

7.154. KatelloErratum struct

Type representing a Katello erratum.

Table 7.207. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

issued

Date

The date when the Katello erratum was issued.

name

String

A human-readable name in plain text.

packages

Package[]

The list of packages which solve the issue reported by the Katello erratum.

severity

String

The severity of the Katello erratum.

solution

String

The solution for the issue described by the Katello erratum.

summary

String

The summary of the Katello erratum.

title

String

The title of the Katello erratum.

type

String

The type of the Katello erratum.

7.154.1. severity

The severity of the Katello erratum.

The supported severities are moderate, important or critical.

7.154.2. type

The type of the Katello erratum.

The supported types are bugfix, enhancement or security.

7.155. KdumpStatus enum

Table 7.209. Values summary

NameSummary

disabled

 

enabled

 

unknown

 

7.156. Kernel struct

Table 7.210. Attributes summary

NameTypeSummary

version

Version

 

7.157. Ksm struct

Table 7.211. Attributes summary

NameTypeSummary

enabled

Boolean

 

merge_across_nodes

Boolean

 

7.159. LogMaxMemoryUsedThresholdType enum

Describes all maximum memory threshold types supported by the system.

Table 7.213. Values summary

NameSummary

absolute_value_in_mb

Absolute value threshold type.

percentage

Percentage threshold type.

7.159.1. absolute_value_in_mb

Absolute value threshold type.

When an absolute value is specified, an audit log event is logged if the free memory in MB falls below the value specified in LogMaxMemoryUsedThreshold.

7.159.2. percentage

Percentage threshold type.

When a percentage is specified, an audit log event is logged if the memory used is above the value specified in LogMaxMemoryUsedThreshold.

7.160. LogSeverity enum

Enum representing a severity of an event.

Table 7.214. Values summary

NameSummary

alert

Alert severity.

error

Error severity.

normal

Normal severity.

warning

Warning severity.

7.160.1. alert

Alert severity. Used to specify a condition that requires an immediate attention.

7.160.2. error

Error severity. Used to specify that there is an error that needs to be examined.

7.160.3. normal

Normal severity. Used for information events.

7.160.4. warning

Warning severity. Used to warn something might be wrong.

7.161. LogicalUnit struct

Table 7.215. Attributes summary

NameTypeSummary

address

String

 

discard_max_size

Integer

The maximum number of bytes that can be discarded by the logical unit’s underlying storage in a single operation.

discard_zeroes_data

Boolean

True, if previously discarded blocks in the logical unit’s underlying storage are read back as zeros.

disk_id

String

 

id

String

 

lun_mapping

Integer

 

password

String

 

paths

Integer

 

port

Integer

 

portal

String

 

product_id

String

 

serial

String

 

size

Integer

 

status

LunStatus

 

storage_domain_id

String

 

target

String

 

username

String

 

vendor_id

String

 

volume_group_id

String

 

7.161.1. discard_max_size

The maximum number of bytes that can be discarded by the logical unit’s underlying storage in a single operation. A value of 0 means that the device does not support discard functionality.

Note

This is the software limit, and not the hardware limit, as noted in the queue-sysfs documentation for discard_max_bytes.

7.161.2. discard_zeroes_data

True, if previously discarded blocks in the logical unit’s underlying storage are read back as zeros. For more information please see the queue-sysfs documentation for discard_zeroes_data.

Important

Since version 4.2.1 of the system, the support for this attribute has been removed as the sysfs file, discard_zeroes_data, was deprecated in the kernel. It is preserved for backwards compatibility, but the value will always be false.

7.162. LunStatus enum

Table 7.216. Values summary

NameSummary

free

 

unusable

 

used

 

7.163. MDevType struct

Mediated device is a software device that allows to divide physical device’s resources.

See Libvirt-MDEV for further details.

Table 7.217. Attributes summary

NameTypeSummary

available_instances

Integer

MDev type available instances count.

description

String

MDev type description.

human_readable_name

String

MDev type human readable name.

name

String

MDev type name.

7.164. Mac struct

Represents a MAC address of a virtual network interface.

Table 7.218. Attributes summary

NameTypeSummary

address

String

MAC address.

7.165. MacPool struct

Represents a MAC address pool.

Example of an XML representation of a MAC address pool:

<mac_pool href="/ovirt-engine/api/macpools/123" id="123">
  <name>Default</name>
  <description>Default MAC pool</description>
  <allow_duplicates>false</allow_duplicates>
  <default_pool>true</default_pool>
  <ranges>
    <range>
      <from>00:1A:4A:16:01:51</from>
      <to>00:1A:4A:16:01:E6</to>
    </range>
  </ranges>
</mac_pool>

Table 7.219. Attributes summary

NameTypeSummary

allow_duplicates

Boolean

Defines whether duplicate MAC addresses are permitted in the pool.

comment

String

Free text containing comments about this object.

default_pool

Boolean

Defines whether this is the default pool.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

ranges

Range[]

Defines the range of MAC addresses for the pool.

7.165.1. allow_duplicates

Defines whether duplicate MAC addresses are permitted in the pool. If not specified, defaults to false.

7.165.2. default_pool

Defines whether this is the default pool. If not specified, defaults to false.

7.165.3. ranges

Defines the range of MAC addresses for the pool. Multiple ranges can be defined.

7.166. MemoryOverCommit struct

Table 7.221. Attributes summary

NameTypeSummary

percent

Integer

 

7.167. MemoryPolicy struct

Logical grouping of memory-related properties of virtual machine-like entities.

Table 7.222. Attributes summary

NameTypeSummary

ballooning

Boolean

 

guaranteed

Integer

The amount of memory, in bytes, that is guaranteed to not be drained by the balloon mechanism.

max

Integer

Maximum virtual machine memory, in bytes.

over_commit

MemoryOverCommit

 

transparent_huge_pages

TransparentHugePages

 

7.167.1. guaranteed

The amount of memory, in bytes, that is guaranteed to not be drained by the balloon mechanism.

The Red Hat Virtualization Manager internally rounds this value down to whole MiB (1MiB = 220 bytes).

Note

It can be updated while the virtual machine is running since Red Hat Virtualization 4.2 onwards, provided memory is updated in the same request as well, and the virtual machine is in state up.

7.167.2. max

Maximum virtual machine memory, in bytes.

The user provides the value in bytes, and the Red Hat Virtualization Manager rounds the value down to the nearest lower MiB value.

For example, if the user enters a value of 1073741825 (1 GiB + 1 byte), then the Red Hat Virtualization Manager will truncate that value to the nearest lower MiB boundary: in this case 1073741824 (1 GiB).

7.168. MessageBrokerType enum

Deprecated Message Broker type.

Ignored, because the deployment of OpenStack Neutron agent is dropped since Red Hat Virtualization 4.4.0.

Table 7.223. Values summary

NameSummary

qpid

 

rabbit_mq

 

7.169. Method struct

Table 7.224. Attributes summary

NameTypeSummary

id

SsoMethod

 

7.170. MigrateOnError enum

Table 7.225. Values summary

NameSummary

do_not_migrate

 

migrate

 

migrate_highly_available

 

7.171. MigrationBandwidth struct

Defines the bandwidth used by migration.

Table 7.226. Attributes summary

NameTypeSummary

assignment_method

MigrationBandwidthAssignmentMethod

The method used to assign the bandwidth.

custom_value

Integer

Custom bandwidth in Mbps.

7.171.1. custom_value

Custom bandwidth in Mbps. Will be applied only if the assignmentMethod attribute is custom.

7.172. MigrationBandwidthAssignmentMethod enum

Defines how the migration bandwidth is assigned.

Table 7.227. Values summary

NameSummary

auto

Takes the bandwidth from the Quality of Service if the Quality of Service is defined.

custom

Custom defined bandwidth in Mbit/s.

hypervisor_default

Takes the value as configured on the hypervisor.

7.172.1. auto

Takes the bandwidth from the Quality of Service if the Quality of Service is defined. If the Quality of Service is not defined the bandwidth is taken from the detected link speed being used. If nothing is detected, bandwidth falls back to the hypervisor_default value.

7.173. MigrationOptions struct

The type for migration options.

Table 7.228. Attributes summary

NameTypeSummary

auto_converge

InheritableBoolean

 

bandwidth

MigrationBandwidth

The bandwidth that is allowed to be used by the migration.

compressed

InheritableBoolean

 

custom_parallel_migrations

Integer

Specifies how many parallel migration connections to use.

encrypted

InheritableBoolean

Specifies whether the migration should be encrypted or not.

parallel_migrations_policy

ParallelMigrationsPolicy

Specifies whether and how to use parallel migration connections.

7.173.1. custom_parallel_migrations

Specifies how many parallel migration connections to use. May be specified only when ParallelMigrationsPolicy is CUSTOM. The valid range of values is 2-255. The recommended range of values is 2-16.

7.174. MigrationPolicy struct

A policy describing how the migration is treated, such as convergence or how many parallel migrations are allowed.

Table 7.230. Attributes summary

NameTypeSummary

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.

7.175. Network struct

The type for a logical network.

An example of the JSON representation of a logical network:

{
  "network" : [ {
    "data_center" : {
      "href" : "/ovirt-engine/api/datacenters/123",
      "id" : "123"
    },
    "stp" : "false",
    "mtu" : "0",
    "usages" : {
      "usage" : [ "vm" ]
    },
    "name" : "ovirtmgmt",
    "description" : "Management Network",
    "href" : "/ovirt-engine/api/networks/456",
    "id" : "456",
    "link" : [ {
      "href" : "/ovirt-engine/api/networks/456/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/ovirt-engine/api/networks/456/vnicprofiles",
      "rel" : "vnicprofiles"
    }, {
      "href" : "/ovirt-engine/api/networks/456/labels",
      "rel" : "labels"
    } ]
  } ]
}

An example of the XML representation of the same logical network:

<network href="/ovirt-engine/api/networks/456" id="456">
  <name>ovirtmgmt</name>
  <description>Management Network</description>
  <link href="/ovirt-engine/api/networks/456/permissions" rel="permissions"/>
  <link href="/ovirt-engine/api/networks/456/vnicprofiles" rel="vnicprofiles"/>
  <link href="/ovirt-engine/api/networks/456/labels" rel="labels"/>
  <data_center href="/ovirt-engine/api/datacenters/123" id="123"/>
  <stp>false</stp>
  <mtu>0</mtu>
  <usages>
    <usage>vm</usage>
  </usages>
</network>

Table 7.231. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

display

Boolean

Deprecated, 'usages' should be used to define network as a display network.

dns_resolver_configuration

DnsResolverConfiguration

The DNS resolver configuration will be reported when retrieving the network using GET.

id

String

A unique identifier.

ip

Ip

Deprecated, not in use.

mtu

Integer

Specifies the maximum transmission unit for the network.

name

String

A human-readable name in plain text.

port_isolation

Boolean

Defines whether communication between VMs running on the same host is blocked on this network.

profile_required

Boolean

Specifies whether upon creation of the network a virtual network interface profile should automatically be created.

required

Boolean

Defines whether the network is mandatory for all the hosts in the cluster.

status

NetworkStatus

The status of the network.

stp

Boolean

Specifies whether the spanning tree protocol is enabled for the network.

usages

NetworkUsage[]

Defines a set of usage elements for the network.

vdsm_name

String

The name of the network used on the host.

vlan

Vlan

A VLAN tag.

7.175.1. dns_resolver_configuration

The DNS resolver configuration will be reported when retrieving the network using GET. It is optional both when creating a new network or updating existing one.

7.175.2. port_isolation

Defines whether communication between VMs running on the same host is blocked on this network. Applies only to VM networks. It is on the network administrator to ensure that the communication between multiple hosts is blocked. This attribute can be set only on network creation and cannot be edited. When the value is not set, communication between VMs running on the same host is allowed.

7.175.3. required

Defines whether the network is mandatory for all the hosts in the cluster. In case a 'required' operational network is omitted from a host, the host will be marked as non_operational,

7.175.4. status

The status of the network. non_operational if the network defined as 'required' and omitted from any active cluster host. operational otherwise.

7.175.5. usages

Defines a set of usage elements for the network.

For example, users can specify that the network is to be used for virtual machine traffic and also for display traffic with the vm and display values.

7.175.6. vdsm_name

The name of the network used on the host. This alternative name is automatically generated by VDSM when the network name is found unsuitable to serve as a bridge name on the host. Unsuitable names contain spaces, special characters or are longer than 15 characters and are replaced with a UUID on the host. This parameter is read-only. Setting it will have no effect.

7.176. NetworkAttachment struct

Describes how a host connects to a network.

An XML representation of a network attachment on a host:

<network_attachment href="/ovirt-engine/api/hosts/123/nics/456/networkattachments/789" id="789">
  <network href="/ovirt-engine/api/networks/234" id="234"/>
  <host_nic href="/ovirt-engine/api/hosts/123/nics/123" id="123"/>
  <in_sync>true</in_sync>
  <ip_address_assignments>
    <ip_address_assignment>
      <assignment_method>static</assignment_method>
      <ip>
        <address>192.168.122.39</address>
        <gateway>192.168.122.1</gateway>
        <netmask>255.255.255.0</netmask>
        <version>v4</version>
      </ip>
    </ip_address_assignment>
  </ip_address_assignments>
  <reported_configurations>
    <reported_configuration>
      <name>mtu</name>
      <expected_value>1500</expected_value>
      <actual_value>1500</actual_value>
      <in_sync>true</in_sync>
    </reported_configuration>
    <reported_configuration>
      <name>bridged</name>
      <expected_value>true</expected_value>
      <actual_value>true</actual_value>
      <in_sync>true</in_sync>
    </reported_configuration>
    ...
  </reported_configurations>
</network_attachment>

The network element, with either a name or an id, is required in order to attach a network to a network interface card (NIC).

For example, to attach a network to a host network interface card, send a request like this:

POST /ovirt-engine/api/hosts/123/nics/456/networkattachments

With a request body like this:

<networkattachment>
  <network id="234"/>
</networkattachment>

To attach a network to a host, send a request like this:

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

With a request body like this:

<network_attachment>
  <network id="234"/>
  <host_nic id="456"/>
</network_attachment>

The ip_address_assignments and properties elements are updatable post-creation.

For example, to update a network attachment, send a request like this:

PUT /ovirt-engine/api/hosts/123/nics/456/networkattachments/789

With a request body like this:

<network_attachment>
  <ip_address_assignments>
    <ip_address_assignment>
      <assignment_method>static</assignment_method>
      <ip>
        <address>7.1.1.1</address>
        <gateway>7.1.1.2</gateway>
        <netmask>255.255.255.0</netmask>
        <version>v4</version>
      </ip>
    </ip_address_assignment>
  </ip_address_assignments>
</network_attachment>

To detach a network from the network interface card send a request like this:

DELETE /ovirt-engine/api/hosts/123/nics/456/networkattachments/789
Important

Changes to network attachment configuration must be explicitly committed.

An XML representation of a network attachment’s properties sub-collection:

<network_attachment>
  <properties>
    <property>
      <name>bridge_opts</name>
      <value>
        forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
      </value>
    </property>
  </properties>
  ...
</network_attachment>

Table 7.233. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

dns_resolver_configuration

DnsResolverConfiguration

DNS resolver configuration will be reported when retrieving the network attachment using GET.

id

String

A unique identifier.

in_sync

Boolean

 

ip_address_assignments

IpAddressAssignment[]

The IP configuration of the network.

name

String

A human-readable name in plain text.

properties

Property[]

Defines custom properties for the network configuration.

reported_configurations

ReportedConfiguration[]

A read-only list of configuration properties.

7.176.1. dns_resolver_configuration

DNS resolver configuration will be reported when retrieving the network attachment using GET. It is optional when creating a new network attachment or updating an existing one.

7.176.2. properties

Defines custom properties for the network configuration.

Bridge options have the set name of bridge_opts. Separate multiple entries with a whitespace character. The following keys are valid for bridge_opts:

NameDefault value

forward_delay

1500

gc_timer

3765

group_addr

1:80:c2:0:0:0

group_fwd_mask

0x0

hash_elasticity

4

hash_max

512

hello_time

200

hello_timer

70

max_age

2000

multicast_last_member_count

2

multicast_last_member_interval

100

multicast_membership_interval

26000

multicast_querier

0

multicast_querier_interval

25500

multicast_query_interval

13000

multicast_query_response_interval

1000

multicast_query_use_ifaddr

0

multicast_router

1

multicast_snooping

1

multicast_startup_query_count

2

multicast_startup_query_interval

3125

7.177. NetworkConfiguration struct

Table 7.235. Attributes summary

NameTypeSummary

dns

Dns

 

nics

Nic[]

 

7.178. NetworkFilter struct

Network filters filter packets sent to and from the virtual machine’s NIC according to defined rules.

There are several types of network filters supported based on libvirt. For more details about the different network filters see here.

The default Network Filter is based on network type and configuration. VM network’s default filter is vdsm-no-mac-spoof if EnableMACAntiSpoofingFilterRules is True, otherwise the filter is not configured, for OVN networks the filter is not configured.

In addition to libvirt’s network filters, there are two additional network filters: The first is called vdsm-no-mac-spoofing and is composed of no-mac-spoofing and no-arp-mac-spoofing. The second is called ovirt-no-filter and is used when no network filter is to be defined for the virtual machine’s NIC. The ovirt-no-filter network filter is only used for internal implementation, and does not exist on the NICs.

This is a example of the XML representation:

<network_filter id="00000019-0019-0019-0019-00000000026c">
  <name>example-filter</name>
  <version>
    <major>4</major>
    <minor>0</minor>
    <build>-1</build>
    <revision>-1</revision>
  </version>
</network_filter>

If any part of the version is not present, it is represented by -1.

Table 7.236. Attributes summary

NameTypeSummary

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.

version

Version

The minimum supported version of a specific NetworkFilter.

7.178.1. version

The minimum supported version of a specific NetworkFilter. This is the version that the NetworkFilter was first introduced in.

7.179. NetworkFilterParameter struct

Parameter for the network filter.

See Libvirt-Filters for further details. This is a example of the XML representation:

<network_filter_parameter id="123">
  <name>IP</name>
  <value>10.0.1.2</value>
</network_filter_parameter>

Table 7.237. Attributes summary

NameTypeSummary

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

Represents the value of the parameter.

7.180. NetworkLabel struct

Represents a label which can be added to a host network interface and to a network. The label binds the network to the host network interface by the label id.

Table 7.239. Attributes summary

NameTypeSummary

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.

7.181. NetworkPluginType enum

Network plug-in type.

Specifies the provider driver implementation on the host.

Since version 4.2 of the Red Hat Virtualization Manager, this type has been deprecated in favour of the external_plugin_type attribute of the OpenStackNetworkProvider type.

Table 7.241. Values summary

NameSummary

open_vswitch

Open vSwitch.

7.181.1. open_vswitch

Open vSwitch.

Specifies that Open vSwitch based driver implementation should be used for this provider.

Since version 4.2 of the Red Hat Virtualization Manager, this value has been deprecated. Use the string open_vswitch in the OpenStackNetworkProvider.external_plugin_type attribute instead.

7.182. NetworkStatus enum

Table 7.242. Values summary

NameSummary

non_operational

 

operational

 

7.183. NetworkUsage enum

This type indicates the purpose that the network is used for in the cluster.

Table 7.243. Values summary

NameSummary

default_route

The default gateway and the DNS resolver configuration of the host will be taken from this network.

display

The network will be used for SPICE and VNC traffic.

gluster

The network will be used for Gluster (bricks) data traffic.

management

The network will be used for communication between the Red Hat Virtualization Manager and the nodes.

migration

The network will be used for virtual machine migration.

vm

 

7.183.1. default_route

The default gateway and the DNS resolver configuration of the host will be taken from this network.

If this network is attached to the host, then the DNS resolver configuration will be taken from the dns_resolver_configuration attribute of the network attachment. If there is no dns_resolver_configuration attribute in this network attachment, then they will be taken from the dns_resolver_configuration of the network itself. If dns_resolver_configuration attribute isn’t present even there, DNS resolver configuration won’t be set.

If you set this flag on a network, then the the default gateway for the host will be taken from the gateway attribute of the ip_address_assignment of the network attachment.

7.183.2. management

The network will be used for communication between the Red Hat Virtualization Manager and the nodes. This is the network where the ovirtmgmt bridge will be created.

7.184. NfsProfileDetail struct

Table 7.244. Attributes summary

NameTypeSummary

nfs_server_ip

String

 

profile_details

ProfileDetail[]

 

7.185. NfsVersion enum

Table 7.245. Values summary

NameSummary

auto

 

v3

 

v4

 

v4_0

NFS 4.

v4_1

 

v4_2

NFS 4.

7.185.1. v4_0

NFS 4.0.

7.185.2. v4_2

NFS 4.2.

7.186. Nic struct

Represents a virtual machine NIC.

For example, the XML representation of a NIC will look like this:

<nic href="/ovirt-engine/api/vms/123/nics/456" id="456">
  <name>nic1</name>
  <vm href="/ovirt-engine/api/vms/123" id="123"/>
  <interface>virtio</interface>
  <linked>true</linked>
  <mac>
    <address>02:00:00:00:00:00</address>
  </mac>
  <plugged>true</plugged>
  <vnic_profile href="/ovirt-engine/api/vnicprofiles/789" id="789"/>
</nic>

Table 7.246. Attributes summary

NameTypeSummary

boot_protocol

BootProtocol

Defines how an IP address is assigned to the NIC.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

interface

NicInterface

The type of driver used for the NIC.

linked

Boolean

Defines if the NIC is linked to the virtual machine.

mac

Mac

The MAC address of the interface.

name

String

A human-readable name in plain text.

on_boot

Boolean

Defines if the network interface should be activated upon operation system startup.

plugged

Boolean

Defines if the NIC is plugged in to the virtual machine.

synced

Boolean

Defines if the NIC configuration on the virtual machine is synced with the configuration represented by engine.

7.187. NicConfiguration struct

The type describes the configuration of a virtual network interface.

Table 7.248. Attributes summary

NameTypeSummary

boot_protocol

BootProtocol

IPv4 boot protocol.

ip

Ip

IPv4 address details.

ipv6

Ip

IPv6 address details.

ipv6_boot_protocol

BootProtocol

IPv6 boot protocol.

name

String

Network interface name.

on_boot

Boolean

Specifies whether the network interface should be activated on the virtual machine guest operating system boot.

7.188. NicInterface enum

Defines the options for an emulated virtual network interface device model.

Table 7.249. Values summary

NameSummary

e1000

e1000.

e1000e

e1000e.

pci_passthrough

PCI Passthrough.

rtl8139

rtl8139.

rtl8139_virtio

Dual mode rtl8139, VirtIO.

spapr_vlan

sPAPR VLAN.

virtio

VirtIO.

7.189. NicStatus enum

Network interface card status.

Table 7.250. Values summary

NameSummary

down

The NIC is down and cannot be accessed.

up

The NIC is up and can be accessed.

7.190. NotifiableEvent enum

Type representing a subset of events in the Red Hat Virtualization server: those which a user may subscribe to receive a notification about.

Table 7.251. Values summary

NameSummary

cluster_alert_ha_reservation

HA Reservation check has failed

cluster_alert_ha_reservation_down

HA Reservation check has passed

dwh_error

ETL Service Error

dwh_stopped

ETL Service Stopped

engine_backup_completed

Engine backup completed successfully

engine_backup_failed

Engine backup failed

engine_backup_started

Engine backup started

engine_ca_certification_has_expired

Engine CA’s certification has expired

engine_ca_certification_is_about_to_expire

Engine CA’s certification is about to expire

engine_certification_has_expired

Engine’s certification has expired

engine_certification_is_about_to_expire

Engine’s certification is about to expire

engine_stop

Engine has stopped

faulty_multipaths_on_host

Faulty multipath paths on host

gluster_brick_status_changed

Detected change in status of brick

gluster_hook_add_failed

Failed to add Gluster Hook on conflicting servers

gluster_hook_added

Added Gluster Hook

gluster_hook_conflict_detected

Detected conflict in Gluster Hook

gluster_hook_detected_delete

Detected removal of Gluster Hook

gluster_hook_detected_new

Detected new Gluster Hook

gluster_hook_disable

Gluster Hook Disabled

gluster_hook_disable_failed

Failed to Disable Gluster Hook

gluster_hook_enable

Gluster Hook Enabled

gluster_hook_enable_failed

Failed to Enable Gluster Hook

gluster_hook_remove_failed

Failed to remove Gluster Hook from cluster

gluster_hook_removed

Removed Gluster Hook

gluster_server_add_failed

Failed to Add Gluster Server

gluster_server_remove

Gluster Server Removed

gluster_server_remove_failed

Failed to Remove Gluster Server

gluster_service_restart_failed

Failed to re-start Gluster Service

gluster_service_restarted

Gluster Service re-started

gluster_service_start_failed

Failed to start Gluster service

gluster_service_started

Gluster Service started

gluster_service_stop_failed

Failed to stop Gluster service

gluster_service_stopped

Gluster Service stopped

gluster_volume_add_brick

Gluster Volume brick(s) added

gluster_volume_add_brick_failed

Failed to add brick(s) on Gluster Volume

gluster_volume_all_snapshots_delete_failed

Failed to delete snapshots on the volume

gluster_volume_all_snapshots_deleted

All the snapshots deleted on the volume

gluster_volume_brick_replaced

Gluster Volume Brick Replaced

gluster_volume_confirmed_space_low

Low space for volume confirmed

gluster_volume_create

Gluster Volume Created

gluster_volume_create_failed

Gluster Volume could not be created

gluster_volume_delete

Gluster Volume deleted

gluster_volume_delete_failed

Gluster Volume could not be deleted

gluster_volume_migrate_brick_data_finished

Gluster Volume migration of data for remove brick finished

gluster_volume_option_added

Gluster Volume Option added

gluster_volume_option_modified

Gluster Volume Option modified

gluster_volume_option_set_failed

Gluster Volume Option could not be set

gluster_volume_options_reset

Gluster Volume Options reset

gluster_volume_options_reset_all

All the Gluster Volume Options reset

gluster_volume_options_reset_failed

Gluster Volume Options could not be reset

gluster_volume_profile_start

Gluster Volume Profile started

gluster_volume_profile_start_failed

Failed to start Gluster Volume Profile

gluster_volume_profile_stop

Gluster Volume Profile stopped

gluster_volume_profile_stop_failed

Failed to stop Gluster Volume Profile

gluster_volume_rebalance_finished

Gluster Volume rebalance finished

gluster_volume_rebalance_not_found_from_cli

Could not find information for rebalance on volume from CLI.

gluster_volume_rebalance_start

Gluster Volume Rebalance started

gluster_volume_rebalance_start_detected_from_cli

Detected start of rebalance on gluster volume from CLI

gluster_volume_rebalance_start_failed

Gluster Volume Rebalance could not be started

gluster_volume_rebalance_stop

Gluster Volume Rebalance stopped

gluster_volume_rebalance_stop_failed

Gluster Volume Rebalance could not be stopped

gluster_volume_remove_bricks

Gluster Volume Bricks Removed

gluster_volume_remove_bricks_failed

Gluster Volume Bricks could not be removed

gluster_volume_remove_bricks_stop

Stopped removing bricks from Gluster Volume

gluster_volume_remove_bricks_stop_failed

Failed to stop remove bricks from Gluster Volume

gluster_volume_replace_brick_failed

Gluster Volume Replace Brick Failed

gluster_volume_replace_brick_start

Gluster Volume Replace Brick Started

gluster_volume_replace_brick_start_failed

Gluster Volume Replace Brick could not be started

gluster_volume_snapshot_activate_failed

Failed to activate snapshot on the volume

gluster_volume_snapshot_activated

Snapshot activated on the volume

gluster_volume_snapshot_create_failed

Could not create snapshot for volume ${glusterVolumeName} on cluster ${clusterName}.

gluster_volume_snapshot_created

Snapshot ${snapname} created for volume ${glusterVolumeName} on cluster ${clusterName}.

gluster_volume_snapshot_deactivate_failed

Failed to de-activate snapshot on the volume

gluster_volume_snapshot_deactivated

Snapshot de-activated on the volume

gluster_volume_snapshot_delete_failed

Failed to delete snapshot on volume

gluster_volume_snapshot_deleted

Snapshot deleted on volume

gluster_volume_snapshot_restore_failed

Failed to restore snapshot on the volume

gluster_volume_snapshot_restored

Snapshot restore on the volume

gluster_volume_start

Gluster volume started

gluster_volume_start_failed

Gluster Volume could not be started

gluster_volume_stop

Gluster volume stopped

gluster_volume_stop_failed

Gluster Volume could not be stopped

ha_vm_failed

Highly-Available VM failed

ha_vm_restart_failed

Highly-Available VM restart failed

host_activate_failed

Failed to activate Host

host_activate_manual_ha

Host was activated, but the Hosted Engine HA service may still be in maintenance mode

host_approve_failed

Failed to approve Host

host_bond_slave_state_down

Host’s slave of bond changed state to down

host_certificate_has_invalid_san

Host’s certificate contains invalid subject alternative name (SAN)

host_certification_has_expired

Host’s certification has expired

host_certification_is_about_to_expire

Host’s certification is about to expire

host_failure

Host is non responsive

host_high_cpu_use

Host cpu usage exceeded defined threshold

host_high_mem_use

Host memory usage exceeded defined threshold

host_high_swap_use

Host swap memory usage exceeded defined threshold

host_initiated_run_vm_failed

Failed to restart VM on a different host

host_install_failed

Host installation failed

host_interface_high_network_use

Host network interface usage exceeded defined threshold

host_interface_state_down

Host’s interface changed state to down

host_low_mem

Host free memory is under defined threshold

host_low_swap

Host free swap memory is under defined threshold

host_recover_failed

Host failed to recover

host_set_nonoperational

Host state was set to non-operational

host_set_nonoperational_domain

Host state was set to non-operational due to inaccessible Storage Domain

host_set_nonoperational_iface_down

Host state was set to non-operational due to a missing Interface

host_slow_storage_response_time

Slow storage response time

host_time_drift_alert

Host has time-drift

host_untrusted

Host state was set to non-operational.

host_updates_are_available

Host has available updates

host_updates_are_available_with_packages

Host has available packages to update

importexport_import_template_from_trusted_to_untrusted

Template imported from trusted cluster into non-trusted cluster

importexport_import_template_from_untrusted_to_trusted

Template imported from non-trusted cluster into trusted cluster

importexport_import_vm_from_trusted_to_untrusted

Import VM from trusted cluster into non-trusted cluster

importexport_import_vm_from_untrusted_to_trusted

Import VM from non-trusted cluster into trusted cluster

irs_confirmed_disk_space_low

Confirmed low disk space

irs_disk_space_low

Low disk space

irs_disk_space_low_error

Critically low disk space

irs_failure

Failed to access Storage

mac_address_is_external

VM with external MAC address

multipath_devices_without_valid_paths_on_host

Multipath devices without valid paths on host

network_update_display_for_cluster_with_active_vm

Display network was updated on cluster with an active VM

network_update_display_for_host_with_active_vm

Display network was updated on host with an active VM

no_faulty_multipaths_on_host

No faulty multipath paths on host

number_of_lvs_on_storage_domain_exceeded_threshold

Storage Domain’s number of LVs exceeded threshold

remove_gluster_volume_bricks_not_found_from_cli

Could not find information for remove brick on volume from CLI.

start_removing_gluster_volume_bricks

Started removing bricks from Volume

start_removing_gluster_volume_bricks_detected_from_cli

Detected start of brick removal for bricks on volume from CLI

start_removing_gluster_volume_bricks_failed

Could not remove volume bricks

system_change_storage_pool_status_no_host_for_spm

Failed electing an SPM for the Data-Center

system_deactivated_storage_domain

Storage Domain state was set to inactive

user_add_vm_from_trusted_to_untrusted

A non-trusted VM was created from trusted Template

user_add_vm_from_untrusted_to_trusted

A trusted VM was created from non-trusted Template

user_add_vm_template_from_trusted_to_untrusted

A non-trusted Template was created from trusted VM

user_add_vm_template_from_untrusted_to_trusted

A trusted Template was created from non-trusted VM

user_host_maintenance

Host was switched to Maintenance Mode

user_host_maintenance_manual_ha

Host was switched to Maintenance Mode, but Hosted Engine HA maintenance mode could not be enabled

user_host_maintenance_migration_failed

Failed to switch Host to Maintenance mode

user_update_vm_from_trusted_to_untrusted

VM moved from trusted cluster to non-trusted cluster

user_update_vm_from_untrusted_to_trusted

VM moved from non-trusted cluster to trusted cluster

user_update_vm_template_from_trusted_to_untrusted

Template moved from trusted cluster to non-trusted cluster

user_update_vm_template_from_untrusted_to_trusted

Template moved from a non-trusted cluster to a trusted cluster

vm_console_connected

VM console connected

vm_console_disconnected

VM console disconnected

vm_down_error

VM is down with error

vm_failure

VM cannot be found on Host

vm_migration_failed

Migration failed

vm_migration_start

Starting migration of VM

vm_migration_to_server_failed

Migration of VM to a destination host failed

vm_not_responding

VM is not responding

vm_paused

VM has been paused

vm_paused_eio

VM has been paused due to a storage I/O error

vm_paused_enospc

VM has been paused due to lack of storage space

vm_paused_eperm

VM has been paused due to storage read/write permissions problem

vm_paused_error

VM has been paused due to unknown storage error

vm_recovered_from_pause_error

VM has recovered from paused back to up

vm_set_ticket

VM console session initiated

vm_status_restored

VM status restored

7.190.1. gluster_volume_rebalance_not_found_from_cli

Could not find information for rebalance on volume from CLI. Marking it as unknown.

7.190.2. host_untrusted

Host state was set to non-operational. Host is untrusted by the attestation service

7.190.3. remove_gluster_volume_bricks_not_found_from_cli

Could not find information for remove brick on volume from CLI. Marking it as unknown.

7.191. NotificationMethod enum

Type representing the notification method for an event subscription. Currently only SMTP is supported by the API In the future support for SNMP notifications may be added.

Table 7.252. Values summary

NameSummary

smtp

Notification by e-mail.

snmp

Notification by SNMP.

7.191.1. smtp

Notification by e-mail.

Event-subscriptions with SMTP notification method will contain an email address in the address field.

7.191.2. snmp

Notification by SNMP.

Event-subscriptions with SNMP notification method will contain an SNMP address in the address field.

7.192. NumaNode struct

Represents a physical NUMA node.

Example XML representation:

<host_numa_node href="/ovirt-engine/api/hosts/0923f1ea/numanodes/007cf1ab" id="007cf1ab">
  <cpu>
    <cores>
      <core>
        <index>0</index>
      </core>
    </cores>
  </cpu>
  <index>0</index>
  <memory>65536</memory>
  <node_distance>40 20 40 10</node_distance>
  <host href="/ovirt-engine/api/hosts/0923f1ea" id="0923f1ea"/>
</host_numa_node>

Table 7.253. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

cpu

Cpu

 

description

String

A human-readable description in plain text.

id

String

A unique identifier.

index

Integer

 

memory

Integer

Memory of the NUMA node in MB.

name

String

A human-readable name in plain text.

node_distance

String

 

7.193. NumaNodePin struct

Represents the pinning of a virtual NUMA node to a physical NUMA node.

Table 7.255. Attributes summary

NameTypeSummary

host_numa_node

NumaNode

Deprecated.

index

Integer

The index of a physical NUMA node to which the virtual NUMA node is pinned.

pinned

Boolean

Deprecated.

7.193.1. host_numa_node

Deprecated. Has no function.

7.193.2. pinned

Deprecated. Should always be true.

7.194. NumaTuneMode enum

Table 7.256. Values summary

NameSummary

interleave

 

preferred

 

strict

 

7.195. OpenStackImage struct

Table 7.257. Attributes summary

NameTypeSummary

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.

7.196. OpenStackImageProvider struct

Table 7.259. Attributes summary

NameTypeSummary

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.

tenant_name

String

Defines the tenant name for OpenStack Identity API v2.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

7.196.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.196.2. tenant_name

Defines the tenant name for OpenStack Identity API v2.0.

7.197. OpenStackNetwork struct

Table 7.261. Attributes summary

NameTypeSummary

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.

7.198. OpenStackNetworkProvider struct

Table 7.263. Attributes summary

NameTypeSummary

agent_configuration

AgentConfiguration

Deprecated Agent configuration settings.

authentication_url

String

Defines the external provider authentication URL address.

auto_sync

Boolean

Indicates if the networks of this provider are automatically synchronized.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

external_plugin_type

String

Network plug-in type.

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.

plugin_type

NetworkPluginType

Network plug-in type.

project_domain_name

String

Defines the project’s domain name for OpenStack Identity API v3.

project_name

String

Defines the project name for OpenStack Identity API v3.

properties

Property[]

Array of provider name/value properties.

read_only

Boolean

Indicates whether the provider is read-only.

requires_authentication

Boolean

Defines whether provider authentication is required or not.

tenant_name

String

Defines the tenant name for OpenStack Identity API v2.

type

OpenStackNetworkProviderType

The type of provider.

unmanaged

Boolean

Indicates whether the provider is unmanaged by Red Hat Virtualization.

url

String

Defines URL address of the external provider.

user_domain_name

String

Defines the domain name of the username in ExternalProvider for OpenStack Identity API v3.

username

String

Defines user name to be used during authentication process.

7.198.1. agent_configuration

Deprecated Agent configuration settings.

Ignored, because the deployment of OpenStack Neutron agent is dropped since Red Hat Virtualization 4.4.0.

7.198.2. auto_sync

Indicates if the networks of this provider are automatically synchronized.

If true, the networks of this provider are automatically and cyclically synchronized to Red Hat Virtualization in the background. This means that all new networks of this provider are imported, and all discarded networks are removed from all clusters that have this external provider as the default provider. If the name of a network is changed on the provider, the change is synchronized to the network entity in Red Hat Virtualization. Furthermore, if a new cluster that has the provider as the default provider is added, already imported networks are attached to this new cluster during synchronization.

The automatically initiated import triggers the following steps:

  • The networks of the external provider will be imported to every data center in the data centers of the clusters that have that external provider as the default provider.
  • A vNIC profile will be created for each involved data center and network.
  • The networks will be assigned to each cluster that has that external provider as the default provider.

All users are allowed to use the new vNIC Profile.

The default is false for backwards compatibility.

7.198.3. external_plugin_type

Network plug-in type.

This attribute allows you to choose the correct provider driver on the host when an external NIC is added or modified. If automated installation of the driver is supported (only available for some predefined implementations, for example ovirt-provider-ovn), this attribute will also allow the system to decide which driver implementation to install on newly added hosts.

7.198.4. plugin_type

Network plug-in type.

Since version 4.2 of the Red Hat Virtualization Manager, this attribute has been deprecated in favour of external_plugin_type. This attribute is only valid for providers of type open_vswitch, and will only be returned when the value of the external_plugin_type attribute value is equal to open_vswitch.

If both plugin_type and external_plugin_type are specified during an update, the value of plugin_type will be ignored.

For external providers this value will not be shown and will be ignored during update requests.

7.198.5. read_only

Indicates whether the provider is read-only.

A read-only provider does not allow adding, modifying, or deleting of networks or subnets. Port-related operations are allowed, as they are required for the provisioning of virtual NICs.

7.198.6. 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.198.7. tenant_name

Defines the tenant name for OpenStack Identity API v2.0.

7.198.8. unmanaged

Indicates whether the provider is unmanaged by Red Hat Virtualization.

If true, authentication and subnet control are entirely left to the external provider and are unmanaged by Red Hat Virtualization.

The default is false for backwards compatibility.

7.199. OpenStackNetworkProviderType enum

The OpenStack network provider can either be implemented by OpenStack Neutron, in which case the Neutron agent is automatically installed on the hosts, or it can be an external provider implementing the OpenStack API, in which case the virtual interface driver is a custom solution installed manually.

Table 7.265. Values summary

NameSummary

external

Indicates that the provider is an external one, implementing the OpenStack Neutron API.

neutron

Indicates that the provider is OpenStack Neutron.

7.199.1. external

Indicates that the provider is an external one, implementing the OpenStack Neutron API. The virtual interface driver in this case is implemented by the external provider.

7.199.2. neutron

Indicates that the provider is OpenStack Neutron. The standard OpenStack Neutron agent is used as the virtual interface driver.

7.200. OpenStackProvider struct

Table 7.266. Attributes summary

NameTypeSummary

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.

tenant_name

String

Defines the tenant name for OpenStack Identity API v2.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

7.200.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.200.2. tenant_name

Defines the tenant name for OpenStack Identity API v2.0.

7.201. OpenStackSubnet struct

Table 7.267. Attributes summary

NameTypeSummary

cidr

String

Defines network CIDR.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

dns_servers

String[]

Defines a list of DNS servers.

gateway

String

Defines IP gateway.

id

String

A unique identifier.

ip_version

String

Defines IP version.

name

String

A human-readable name in plain text.

7.201.1. ip_version

Defines IP version.

Values can be v4' for IPv4 or `v6 for IPv6.

7.202. OpenStackVolumeProvider struct

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 7.269. Attributes summary

NameTypeSummary

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.

tenant_name

String

Defines the tenant name for OpenStack Identity API v2.

url

String

Defines URL address of the external provider.

username

String

Defines user name to be used during authentication process.

7.202.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.202.2. tenant_name

Defines the tenant name for OpenStack Identity API v2.0.

7.203. OpenStackVolumeType struct

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 7.271. Attributes summary

NameTypeSummary

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.

properties

Property[]

 

7.204. OpenstackVolumeAuthenticationKey struct

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 7.273. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

creation_date

Date

 

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

usage_type

OpenstackVolumeAuthenticationKeyUsageType

 

uuid

String

 

value

String

 

7.205. OpenstackVolumeAuthenticationKeyUsageType enum

Openstack Volume (Cinder) integration has been replaced by Managed Block Storage.

Table 7.275. Values summary

NameSummary

ceph

 

7.206. OperatingSystem struct

Information describing the operating system. This is used for both virtual machines and hosts.

Table 7.276. Attributes summary

NameTypeSummary

boot

Boot

Configuration of the boot sequence.

cmdline

String

Custom kernel parameters for starting the virtual machine if Linux operating system is used.

custom_kernel_cmdline

String

A custom part of the host kernel command line.

initrd

String

Path to custom initial ramdisk on ISO storage domain if Linux operating system is used.

kernel

String

Path to custom kernel on ISO storage domain if Linux operating system is used.

reported_kernel_cmdline

String

The host kernel command line as reported by a running host.

type

String

Operating system name in human readable form.

version

Version

 

7.206.1. boot

Configuration of the boot sequence.

Note

Not used for hosts.

7.206.2. cmdline

Custom kernel parameters for starting the virtual machine if Linux operating system is used.

Note

Not used for hosts.

7.206.3. custom_kernel_cmdline

A custom part of the host kernel command line. This will be merged with the existing kernel command line.

You must reinstall and then reboot the host to apply the changes implemented by this attribute.

During each host deploy procedure, kernel parameters that were added in the previous host deploy procedure are removed using grubby --update-kernel DEFAULT --remove-args <previous_custom_params>, and the current kernel command line customization is applied using grubby --update-kernel DEFAULT --args <custom_params>. The Manager internally keeps track of the last-applied kernel parameters customization.

Note

This attribute is currently only used for hosts.

7.206.4. initrd

Path to custom initial ramdisk on ISO storage domain if Linux operating system is used.

For example iso://initramfs-3.10.0-514.6.1.el7.x86_64.img.

Note

Not used for hosts.

7.206.5. kernel

Path to custom kernel on ISO storage domain if Linux operating system is used.

For example iso://vmlinuz-3.10.0-514.6.1.el7.x86_64.

Note

Not used for hosts.

7.206.6. reported_kernel_cmdline

The host kernel command line as reported by a running host.

This is a read-only attribute. Attempts to change this attribute are silently ignored.

Note

This attribute is currently only used for hosts.

7.206.7. type

Operating system name in human readable form.

For example Fedora or RHEL. In general one of the names returned by the operating system service.

Note

Read only for hosts.

7.207. OperatingSystemInfo struct

Represents a guest operating system.

Table 7.277. Attributes summary

NameTypeSummary

architecture

Architecture

Operating system architecture.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

large_icon

Icon

Large icon of the guest operating system.

name

String

A human-readable name in plain text.

small_icon

Icon

Small icon of the guest operating system.

tpm_support

TpmSupport

TPM support status.

7.207.1. large_icon

Large icon of the guest operating system. Maximum dimensions: width 150px, height 120px.

7.207.2. small_icon

Small icon of the guest operating system. Maximum dimensions: width 43px, height 43px.

7.208. Option struct

Table 7.278. Attributes summary

NameTypeSummary

name

String

 

type

String

 

value

String

 

7.209. OsType enum

Type representing kind of operating system.

Warning

This type has been deprecated with the introduction of the OperatingSystemInfo type. Operating systems are available as a top-level collection in the API: operating_systems.

The end-user declares the type of the operating system installed in the virtual machine (guest operating system) by selecting one of these values. This declaration enables the system to tune the virtual machine configuration for better user experience. For example, the system chooses devices that are most suitable for the operating system. Note that the system rely on user’s selection and does not verify it by inspecting the actual guest operating system installed.

Table 7.279. Values summary

NameSummary

other

Other type of operating system, not specified by the other values.

other_linux

Distribution of Linux other than those specified by the other values.

rhel_3

Red Hat Enterprise Linux 3 32-bit.

rhel_3x64

Red Hat Enterprise Linux 3 64-bit.

rhel_4

Red Hat Enterprise Linux 4 32-bit.

rhel_4x64

Red Hat Enterprise Linux 4 64-bit.

rhel_5

Red Hat Enterprise Linux 5 32-bit.

rhel_5x64

Red Hat Enterprise Linux 5 64-bit.

rhel_6

Red Hat Enterprise Linux 6 32-bit.

rhel_6x64

Red Hat Enterprise Linux 6 64-bit.

unassigned

This value is mapped to other.

windows_2003

Windows 2003 32-bit.

windows_2003x64

Windows 2003 64-bit.

windows_2008

Windows 2008 32-bit.

windows_2008r2x64

Windows 2008 R2 64-bit.

windows_2008x64

Windows 2008 64-bit.

windows_2012x64

Windows 2012 64-bit.

windows_7

Windows 7 32-bit.

windows_7x64

Windows 7 64-bit.

windows_8

Windows 8 32-bit.

windows_8x64

Windows 8 64-bit.

windows_xp

Windows XP.

7.210. Package struct

Type representing a package.

This is an example of the package element:

<package>
  <name>libipa_hbac-1.9.2-82.11.el6_4.i686</name>
</package>

Table 7.280. Attributes summary

NameTypeSummary

name

String

The name of the package.

7.211. ParallelMigrationsPolicy enum

Type representing parallel migration connections policy.

Table 7.281. Values summary

NameSummary

auto

Choose automatically between parallel and non-parallel connections.

auto_parallel

Use parallel connections and select their number automatically.

custom

Use manually specified number of parallel connections.

disabled

Use non-parallel connections.

inherit

Use cluster value (applicable only to VMs).

7.211.1. auto

Choose automatically between parallel and non-parallel connections. If parallel connections are used, select their number automatically.

7.211.2. custom

Use manually specified number of parallel connections. The number of parallel connections must be set in MigrationOptions.customParallelMigrations.

7.212. Payload struct

Table 7.282. Attributes summary

NameTypeSummary

files

File[]

 

type

VmDeviceType

 

volume_id

String

 

7.213. PayloadEncoding enum

Table 7.283. Values summary

NameSummary

base64

 

plaintext

 

7.214. Permission struct

Type represents a permission.

Table 7.284. Attributes summary

NameTypeSummary

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.

7.215. Permit struct

Type represents a permit.

Table 7.286. Attributes summary

NameTypeSummary

administrative

Boolean

Specifies whether permit is administrative or not.

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.

7.216. PmProxy struct

Table 7.288. Attributes summary

NameTypeSummary

type

PmProxyType

 

7.217. PmProxyType enum

Table 7.289. Values summary

NameSummary

cluster

The fence proxy is selected from the same cluster as the fenced host.

dc

The fence proxy is selected from the same data center as the fenced host.

other_dc

The fence proxy is selected from a different data center than the fenced host.

7.218. PolicyUnitType enum

Holds the types of all internal policy unit types.

Table 7.290. Values summary

NameSummary

filter

 

load_balancing

 

weight

 

7.219. PortMirroring struct

7.220. PowerManagement struct

Table 7.291. Attributes summary

NameTypeSummary

address

String

The host name or IP address of the host.

agents

Agent[]

Specifies fence agent options when multiple fences are used.

automatic_pm_enabled

Boolean

Toggles the automated power control of the host in order to save energy.

enabled

Boolean

Indicates whether power management configuration is enabled or disabled.

kdump_detection

Boolean

Toggles whether to determine if kdump is running on the host before it is shut down.

options

Option[]

Fencing options for the selected type= specified with the option name="" and value="" strings.

password

String

A valid, robust password for power management.

pm_proxies

PmProxy[]

Determines the power management proxy.

status

PowerManagementStatus

Determines the power status of the host.

type

String

Fencing device code.

username

String

A valid user name for power management.

7.220.1. agents

Specifies fence agent options when multiple fences are used.

Use the order sub-element to prioritize the fence agents. Agents are run sequentially according to their order until the fence action succeeds. When two or more fence agents have the same order, they are run concurrently. Other sub-elements include type, ip, user, password, and options.

7.220.2. automatic_pm_enabled

Toggles the automated power control of the host in order to save energy. When set to true, the host will be automatically powered down if the cluster’s load is low, and powered on again when required. This is set to true when a host is created, unless disabled by the user.

7.220.3. kdump_detection

Toggles whether to determine if kdump is running on the host before it is shut down. When set to true, the host will not shut down during a kdump process. This is set to true when a host has power management enabled, unless disabled by the user.

7.220.4. type

Fencing device code.

A list of valid fencing device codes are available in the capabilities collection.

7.221. PowerManagementStatus enum

Table 7.292. Values summary

NameSummary

off

Host is OFF.

on

Host is ON.

unknown

Unknown status.

7.222. Product struct

Table 7.293. Attributes summary

NameTypeSummary

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.

7.223. ProductInfo struct

Product information.

The entry point contains a product_info element to help an API user determine the legitimacy of the Red Hat Virtualization environment. This includes the name of the product, the vendor and the version.

Verify a genuine Red Hat Virtualization environment

The follow elements identify a genuine Red Hat Virtualization environment:

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

Table 7.294. Attributes summary

NameTypeSummary

instance_id

String

The ID of this particular installation of the product.

name

String

The name of the product, for example oVirt Engine.

vendor

String

The name of the vendor, for example `ovirt.

version

Version

The version number of the product.

7.223.1. vendor

The name of the vendor, for example ovirt.org.

7.224. ProfileDetail struct

Table 7.295. Attributes summary

NameTypeSummary

block_statistics

BlockStatistic[]

 

duration

Integer

 

fop_statistics

FopStatistic[]

 

profile_type

String

 

statistics

Statistic[]

 

7.225. Property struct

Table 7.296. Attributes summary

NameTypeSummary

name

String

 

value

String

 

7.226. ProxyTicket struct

Table 7.297. Attributes summary

NameTypeSummary

value

String

 

7.227. QcowVersion enum

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 storage domain’s version which the disk is created on. Storage domains with version lower than V4 support QCOW2 version 2 volumes, while V4 storage domains also support QCOW2 version 3. For more information about features of the different QCOW versions, see here.

Table 7.298. Values summary

NameSummary

qcow2_v2

The Copy On Write default compatibility version It means that every QEMU can use it.

qcow2_v3

The Copy On Write compatibility version which was introduced in QEMU 1.

7.227.1. qcow2_v3

The Copy On Write compatibility version which was introduced in QEMU 1.1 It means that the new format is in use.

7.228. Qos struct

This type represents the attributes to define Quality of service (QoS).

For storage the type is storage, the attributes max_throughput, max_read_throughput, max_write_throughput, max_iops, max_read_iops and max_write_iops are relevant.

For resources with computing capabilities the type is cpu, the attribute cpu_limit is relevant.

For virtual machines networks the type is network, the attributes inbound_average, inbound_peak, inbound_burst, outbound_average, outbound_peak and outbound_burst are relevant.

For host networks the type is hostnetwork, the attributes outbound_average_linkshare, outbound_average_upperlimit and outbound_average_realtime are relevant.

Table 7.299. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

cpu_limit

Integer

The maximum processing capability in %.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

inbound_average

Integer

The desired average inbound bit rate in Mbps (Megabits per sec).

inbound_burst

Integer

The amount of data that can be delivered in a single burst, in MB.

inbound_peak

Integer

The maximum inbound rate in Mbps (Megabits per sec).

max_iops

Integer

Maximum permitted number of input and output operations per second.

max_read_iops

Integer

Maximum permitted number of input operations per second.

max_read_throughput

Integer

Maximum permitted throughput for read operations.

max_throughput

Integer

Maximum permitted total throughput.

max_write_iops

Integer

Maximum permitted number of output operations per second.

max_write_throughput

Integer

Maximum permitted throughput for write operations.

name

String

A human-readable name in plain text.

outbound_average

Integer

The desired average outbound bit rate in Mbps (Megabits per sec).

outbound_average_linkshare

Integer

Weighted share.

outbound_average_realtime

Integer

The committed rate in Mbps (Megabits per sec).

outbound_average_upperlimit

Integer

The maximum bandwidth to be used by a network in Mbps (Megabits per sec).

outbound_burst

Integer

The amount of data that can be sent in a single burst, in MB.

outbound_peak

Integer

The maximum outbound rate in Mbps (Megabits per sec).

type

QosType

The kind of resources this entry can be assigned.

7.228.1. cpu_limit

The maximum processing capability in %.

Used to configure computing resources.

7.228.2. inbound_average

The desired average inbound bit rate in Mbps (Megabits per sec).

Used to configure virtual machines networks. If defined, inbound_peak and inbound_burst also has to be set.

See Libvirt-QOS for further details.

7.228.3. inbound_burst

The amount of data that can be delivered in a single burst, in MB.

Used to configure virtual machine networks. If defined, inbound_average and inbound_peak must also be set.

See Libvirt-QOS for further details.

7.228.4. inbound_peak

The maximum inbound rate in Mbps (Megabits per sec).

Used to configure virtual machines networks. If defined, inbound_average and inbound_burst also has to be set.

See Libvirt-QOS for further details.

7.228.5. max_iops

Maximum permitted number of input and output operations per second.

Used to configure storage. Must not be set if max_read_iops or max_write_iops is set.

7.228.6. max_read_iops

Maximum permitted number of input operations per second.

Used to configure storage. Must not be set if max_iops is set.

7.228.7. max_read_throughput

Maximum permitted throughput for read operations.

Used to configure storage. Must not be set if max_throughput is set.

7.228.8. max_throughput

Maximum permitted total throughput.

Used to configure storage. Must not be set if max_read_throughput or max_write_throughput is set.

7.228.9. max_write_iops

Maximum permitted number of output operations per second.

Used to configure storage. Must not be set if max_iops is set.

7.228.10. max_write_throughput

Maximum permitted throughput for write operations.

Used to configure storage. Must not be set if max_throughput is set.

7.228.11. outbound_average

The desired average outbound bit rate in Mbps (Megabits per sec).

Used to configure virtual machines networks. If defined, outbound_peak and outbound_burst also has to be set.

See Libvirt-QOS for further details.

7.228.12. outbound_average_linkshare

Weighted share.

Used to configure host networks. Signifies how much of the logical link’s capacity a specific network should be allocated, relative to the other networks attached to the same logical link. The exact share depends on the sum of shares of all networks on that link. By default this is a number in the range 1-100.

7.228.13. outbound_average_realtime

The committed rate in Mbps (Megabits per sec).

Used to configure host networks. The minimum bandwidth required by a network. The committed rate requested is not guaranteed and will vary depending on the network infrastructure and the committed rate requested by other networks on the same logical link.

7.228.14. outbound_average_upperlimit

The maximum bandwidth to be used by a network in Mbps (Megabits per sec).

Used to configure host networks. If outboundAverageUpperlimit and outbound_average_realtime are provided, the outbound_averageUpperlimit must not be lower than the outbound_average_realtime.

See Libvirt-QOS for further details.

7.228.15. outbound_burst

The amount of data that can be sent in a single burst, in MB.

Used to configure virtual machine networks. If defined, outbound_average and outbound_peak must also be set.

See Libvirt-QOS for further details.

7.228.16. outbound_peak

The maximum outbound rate in Mbps (Megabits per sec).

Used to configure virtual machines networks. If defined, outbound_average and outbound_burst also has to be set.

See Libvirt-QOS for further details.

7.229. QosType enum

This type represents the kind of resource the Quality of service (QoS) can be assigned to.

Table 7.301. Values summary

NameSummary

cpu

The Quality of service (QoS) can be assigned to resources with computing capabilities.

hostnetwork

The Quality of service (QoS) can be assigned to host networks.

network

The Quality of service (QoS) can be assigned to virtual machines networks.

storage

The Quality of service (QoS) can be assigned to storage.

7.230. Quota struct

Represents a quota object.

An example XML representation of a quota:

<quota href="/ovirt-engine/api/datacenters/7044934e/quotas/dcad5ddc" id="dcad5ddc">
  <name>My Quota</name>
  <description>A quota for my oVirt environment</description>
  <cluster_hard_limit_pct>0</cluster_hard_limit_pct>
  <cluster_soft_limit_pct>0</cluster_soft_limit_pct>
  <data_center href="/ovirt-engine/api/datacenters/7044934e" id="7044934e"/>
  <storage_hard_limit_pct>0</storage_hard_limit_pct>
  <storage_soft_limit_pct>0</storage_soft_limit_pct>
</quota>

Table 7.302. Attributes summary

NameTypeSummary

cluster_hard_limit_pct

Integer

 

cluster_soft_limit_pct

Integer

 

comment

String

Free text containing comments about this object.

data_center

DataCenter

 

description

String

A human-readable description in plain text.

disks

Disk[]

 

id

String

A unique identifier.

name

String

A human-readable name in plain text.

storage_hard_limit_pct

Integer

 

storage_soft_limit_pct

Integer

 

users

User[]

 

vms

Vm[]

 

7.231. QuotaClusterLimit struct

Table 7.304. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

memory_limit

Decimal

 

memory_usage

Decimal

 

name

String

A human-readable name in plain text.

vcpu_limit

Integer

 

vcpu_usage

Integer

 

7.232. QuotaModeType enum

Table 7.306. Values summary

NameSummary

audit

 

disabled

 

enabled

 

7.233. QuotaStorageLimit struct

Table 7.307. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

limit

Integer

 

name

String

A human-readable name in plain text.

usage

Decimal

 

7.234. Range struct

Table 7.309. Attributes summary

NameTypeSummary

from

String

 

to

String

 

7.235. Rate struct

Determines maximum speed of consumption of bytes from random number generator device.

Table 7.310. Attributes summary

NameTypeSummary

bytes

Integer

Number of bytes allowed to consume per period.

period

Integer

Duration of one period in milliseconds.

7.236. RegistrationAffinityGroupMapping struct

This type describes how to map affinity groups as part of the object registration. An object can be a virtual machine, template, etc.

An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <affinity_group_mappings>
     <registration_affinity_group_mapping>
       <from>
         <name>affinity</name>
       </from>
       <to>
         <name>affinity2</name>
       </to>
     </registration_affinity_group_mapping>
    </affinity_group_mappings>
  </registration_configuration>
</action>

7.237. RegistrationAffinityLabelMapping struct

This type describes how to map affinity labels as part of the object registration. An object can be a virtual machine, template, etc.

An example of an XML representation using mapping:

<action>
  <registration_configuration>
    <affinity_label_mappings>
     <registration_affinity_label_mapping>
       <from>
         <name>affinity_label</name>
       </from>
       <to>
         <name>affinity_label2</name>
       </to>
     </registration_affinity_label_mapping>
    </affinity_label_mappings>
  </registration_configuration>
</action>

7.238. RegistrationClusterMapping struct

This type describes how to map clusters as part of the object registration. An object can be a virtual machine, template, etc.

An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <cluster_mappings>
      <registration_cluster_mapping>
        <from>
          <name>myoriginalcluster</name>
        </from>
        <to>
          <name>mynewcluster</name>
        </to>
      </registration_cluster_mapping>
    </cluster_mappings>
  </registration_configuration>
</action>

7.239. RegistrationConfiguration struct

This type describes how an object (virtual machine, template, etc) is registered, and is used for the implementation of disaster recovery solutions.

Each mapping contained in this type can be used to map objects in the original system to corresponding objects in the system where the virtual machine or template is being registered. For example, there could be a primary setup with a virtual machine configured on cluster A, and an active secondary setup with cluster B. Cluster B is compatible with that virtual machine, and in case of a disaster recovery scenario the storage domain can be imported to the secondary setup, and the user can register the virtual machine to cluster B.

In that case, we can automate the recovery process by defining a cluster mapping. After the entity is registered, its OVF will indicate it belongs to cluster A, but the mapping will indicate that cluster A will be replaced with cluster B. Red Hat Virtualization Manager should do the switch and register the virtual machine to cluster B in the secondary site.

Cluster mapping is just one example, there are different types of mappings:

  • Cluster mapping.
  • LUN mapping.
  • Role mapping.
  • Domain mapping.
  • Permissions mapping.
  • Affinity Group mapping.
  • Affinity Label mapping.
  • Virtual NIC profile mapping.

Each mapping will be used for its specific OVF’s data once the register operation takes place in the Red Hat Virtualization Manager.

An example of an XML representation using the mapping:

<action>
  <registration_configuration>
    <cluster_mappings>
      <registration_cluster_mapping>
        <from>
          <name>myoriginalcluster</name>
        </from>
        <to>
          <name>mynewcluster</name>
        </to>
      </registration_cluster_mapping>
    </cluster_mappings>
    <role_mappings>
      <registration_role_mapping>
        <from>
          <name>SuperUser</name>
        </from>
        <to>
          <name>UserVmRunTimeManager</name>
        </to>
      </registration_role_mapping>
    </role_mappings>
    <domain_mappings>
      <registration_domain_mapping>
        <from>
          <name>redhat</name>
        </from>
        <to>
          <name>internal</name>
        </to>
      </registration_domain_mapping>
    </domain_mappings>
    <lun_mappings>
     <registration_lun_mapping>
       <from id="111">
       </from>
       <to id="222">
         <alias>weTestLun</alias>
         <lun_storage>
           <type>iscsi</type>
           <logical_units>
              <logical_unit id="36001405fb1ddb4b91e44078f1fffcfef">
                 <address>44.33.11.22</address>
                 <port>3260</port>
                 <portal>1</portal>
                 <target>iqn.2017-11.com.name.redhat:444</target>
              </logical_unit>
           </logical_units>
         </lun_storage>
       </to>
     </registration_lun_mapping>
    </lun_mappings>
    <affinity_group_mappings>
     <registration_affinity_group_mapping>
       <from>
         <name>affinity</name>
       </from>
       <to>
         <name>affinity2</name>
       </to>
     </registration_affinity_group_mapping>
    </affinity_group_mappings>
    <affinity_label_mappings>
     <registration_affinity_label_mapping>
       <from>
         <name>affinity_label</name>
       </from>
       <to>
         <name>affinity_label2</name>
       </to>
     </registration_affinity_label_mapping>
    </affinity_label_mappings>
    <vnic_profile_mappings>
      <registration_vnic_profile_mapping>
        <from>
          <name>gold</name>
          <network>
            <name>red</name>
          </network>
        </from>
        <to id="738dd914-8ec8-4a8b-8628-34672a5d449b"/>
      </registration_vnic_profile_mapping>
      <registration_vnic_profile_mapping>
        <from>
          <name>silver</name>
          <network>
            <name>blue</name>
          </network>
        </from>
        <to>
          <name>copper</name>
          <network>
            <name>orange</name>
          </network>
        </to>
      </registration_vnic_profile_mapping>
    </vnic_profile_mappings>
  </registration_configuration>
</action>

Table 7.314. Attributes summary

NameTypeSummary

affinity_group_mappings

RegistrationAffinityGroupMapping[]

Describes how the affinity groups are mapped.

affinity_label_mappings

RegistrationAffinityLabelMapping[]

Describes how the affinity labels are mapped.

cluster_mappings

RegistrationClusterMapping[]

Describes how the clusters that the object references are mapped.

domain_mappings

RegistrationDomainMapping[]

Describes how the users' domains are mapped.

lun_mappings

RegistrationLunMapping[]

Describes how the LUNs are mapped.

role_mappings

RegistrationRoleMapping[]

Describes how the roles are mapped.

vnic_profile_mappings

RegistrationVnicProfileMapping[]

Mapping rules for virtual NIC profiles that will be applied during the register process.

7.240. RegistrationDomainMapping struct

This type describes how to map the users' domain as part of the object registration. An object can be a virtual machine, template, etc. NOTE: This is based on the assumption that user names will be the same, and that only the domain name will be changed.

An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <domain_mappings>
      <registration_domain_mapping>
        <from>
          <name>redhat</name>
        </from>
        <to>
          <name>internal</name>
        </to>
      </registration_domain_mapping>
    </domain_mappings>
  </registration_configuration>
</action>

7.241. RegistrationLunMapping struct

This type describes how to map LUNs as part of the object registration. An object can be a virtual machine, template, etc.

An external LUN disk is an entity which does not reside on a storage domain. It must be specified because it doesn’t need to exist in the environment where the object is registered. An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <lun_mappings>
      <registration_lun_mapping>
    <lun_mappings>
     <registration_lun_mapping>
       <from id="111">
       </from>
       <to id="222">
         <alias>weTestLun</alias>
         <lun_storage>
           <type>iscsi</type>
           <logical_units>
              <logical_unit id="36001405fb1ddb4b91e44078f1fffcfef">
                 <address>44.33.11.22</address>
                 <port>3260</port>
                 <portal>1</portal>
                 <target>iqn.2017-11.com.name.redhat:444</target>
              </logical_unit>
           </logical_units>
         </lun_storage>
       </to>
     </registration_lun_mapping>
    </lun_mappings>
  </registration_configuration>
</action>

7.242. RegistrationRoleMapping struct

This type describes how to map roles as part of the object registration. An object can be a virtual machine, template, etc.

A role mapping is intended to map correlating roles between the primary site and the secondary site. For example, there may be permissions with role UserVmRunTimeManager for the virtual machine that is being registered. Therefore we can send a mapping that will register the virtual machine in the secondary setup using the SuperUser role instead of UserVmRunTimeManager An example of an XML representation using this mapping:

<action>
  <registration_configuration>
    <role_mappings>
      <registration_eole_mapping>
        <from>
          <name>SuperUser</name>
        </from>
        <to>
          <name>UserVmRunTimeManager</name>
        </to>
      </registration_role_mapping>
    </role_mappings>
  </registration_configuration>
</action>

7.243. RegistrationVnicProfileMapping struct

Maps an external virtual NIC profile to one that exists in the Red Hat Virtualization Manager. The target may be specified as a profile ID or a pair of profile name and network name.

If, for example, the desired virtual NIC profile mapping includes the following lines:

Source network nameSource network profile nameTarget virtual NIC profile ID\names

red

gold

738dd914-8ec8-4a8b-8628-34672a5d449b

<empty> (no network name)

<empty> (no network profile name)

892a12ec-2028-4451-80aa-ff3bf55d6bac

blue

silver

orange\copper

yellow

platinum

<empty> (no profile)

green

bronze

 

Then the following snippet should be added to RegistrationConfiguration

<vnic_profile_mappings>
  <registration_vnic_profile_mapping>
    <from>
      <name>gold</name>
      <network>
        <name>red</name>
      </network>
    </from>
    <to id="738dd914-8ec8-4a8b-8628-34672a5d449b"/>
  </registration_vnic_profile_mapping>
  <registration_vnic_profile_mapping>
    <from>
      <name></name>
      <network>
        <name></name>
      </network>
    </from>
    <to id="892a12ec-2028-4451-80aa-ff3bf55d6bac"/>
  </registration_vnic_profile_mapping>
  <registration_vnic_profile_mapping>
    <from>
      <name>silver</name>
      <network>
        <name>blue</name>
      </network>
    </from>
    <to>
      <name>copper</name>
      <network>
        <name>orange</name>
      </network>
    </to>
  </registration_vnic_profile_mapping>
  <registration_vnic_profile_mapping>
    <from>
      <name>platinum</name>
      <network>
        <name>yellow</name>
      </network>
    </from>
    <to>
      <name></name>
      <network>
        <name></name>
      </network>
    </to>
  </registration_vnic_profile_mapping>
  <registration_vnic_profile_mapping>
    <from>
      <name>bronze</name>
      <network>
        <name>green</name>
      </network>
    </from>
  </registration_vnic_profile_mapping>
</vnic_profile_mappings>

7.244. ReportedConfiguration struct

Table 7.319. Attributes summary

NameTypeSummary

actual_value

String

 

expected_value

String

 

in_sync

Boolean

false when the network attachment contains uncommitted network configuration.

name

String

 

7.245. ReportedDevice struct

Table 7.320. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

ips

Ip[]

 

mac

Mac

 

name

String

A human-readable name in plain text.

type

ReportedDeviceType

 

7.246. ReportedDeviceType enum

Table 7.322. Values summary

NameSummary

network

 

7.247. ResolutionType enum

Table 7.323. Values summary

NameSummary

add

 

copy

 

7.248. RngDevice struct

Random number generator (RNG) device model.

Table 7.324. Attributes summary

NameTypeSummary

rate

Rate

Determines maximum speed of consumption of bytes from random number generator device.

source

RngSource

Backend of the random number generator device.

7.249. RngSource enum

Representing the random generator backend types.

Table 7.325. Values summary

NameSummary

hwrng

Obtains random data from the /dev/hwrng (usually specialized HW generator) device.

random

Obtains random data from the /dev/random device.

urandom

Obtains random data from the /dev/urandom device.

7.249.1. urandom

Obtains random data from the /dev/urandom device.

This RNG source is meant to replace random RNG source for non-cluster-aware entities (i.e. Blank template and instance types) and entities associated with clusters with compatibility version 4.1 or higher.

7.250. Role struct

Represents a system role.

Table 7.326. Attributes summary

NameTypeSummary

administrative

Boolean

Defines the role as administrative-only or not.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

mutable

Boolean

Defines the ability to update or delete the role.

name

String

A human-readable name in plain text.

7.250.1. mutable

Defines the ability to update or delete the role.

Roles with mutable set to false are predefined roles.

7.251. RoleType enum

Type representing whether a role is administrative or not. A user which was granted at least one administrative role is considered an administrator.

Table 7.328. Values summary

NameSummary

admin

Administrative role.

user

User role.

7.252. SchedulingPolicy struct

Table 7.329. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

default_policy

Boolean

 

description

String

A human-readable description in plain text.

id

String

A unique identifier.

locked

Boolean

 

name

String

A human-readable name in plain text.

properties

Property[]

 

7.253. SchedulingPolicyUnit struct

Table 7.331. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

enabled

Boolean

 

id

String

A unique identifier.

internal

Boolean

 

name

String

A human-readable name in plain text.

properties

Property[]

 

type

PolicyUnitType

 

7.254. ScsiGenericIO enum

When a direct LUN disk is using SCSI passthrough the privileged I/O policy is determined by this enum.

Table 7.332. Values summary

NameSummary

disabled

Disable SCSI passthrough.

filtered

Disallow privileged SCSI I/O.

unfiltered

Allow privileged SCSI I/O.

7.255. SeLinux struct

Represents SELinux in the system.

Table 7.333. Attributes summary

NameTypeSummary

mode

SeLinuxMode

SELinux current mode.

7.256. SeLinuxMode enum

Represents an SELinux enforcement mode.

Table 7.334. Values summary

NameSummary

disabled

SELinux is disabled in the kernel.

enforcing

SELinux is running and enforcing permissions.

permissive

SELinux is running and logging but not enforcing permissions.

7.257. SerialNumber struct

Table 7.335. Attributes summary

NameTypeSummary

policy

SerialNumberPolicy

 

value

String

 

7.258. SerialNumberPolicy enum

Type representing the policy of a Serial Number.

Table 7.336. Values summary

NameSummary

custom

This policy allows the user to provide an arbitrary string as the Serial Number.

host

This policy is the legacy policy.

none

This policy is used to remove the Serial Number Policy, moving it to default: null.

vm

This policy will use the Virtual Machine ID as the Serial Number.

7.258.1. host

This policy is the legacy policy. It will use the Host ID as the Serial Number.

7.259. Session struct

Describes a user session to a virtual machine.

Table 7.337. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

console_user

Boolean

Indicates if this is a console session.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

ip

Ip

The IP address the user is connected from.

name

String

A human-readable name in plain text.

protocol

String

The protocol used by the session.

7.259.1. console_user

Indicates if this is a console session.

The value will be true for console users (SPICE or VNC), and false for others (such as RDP or SSH).

7.259.2. ip

The IP address the user is connected from.

Currently only available for console users.

7.259.3. protocol

The protocol used by the session.

Currently not used. Intended for info about how the user is connected: through SPICE, VNC, SSH, or RDP.

7.260. SkipIfConnectivityBroken struct

Table 7.339. Attributes summary

NameTypeSummary

enabled

Boolean

If enabled, we will not fence a host in case more than a configurable percentage of hosts in the cluster lost connectivity as well.

threshold

Integer

Threshold for connectivity testing.

7.260.1. enabled

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

Threshold for connectivity testing. If at least the threshold percentage of hosts in the cluster lost connectivity then fencing will not take place.

7.261. SkipIfSdActive struct

This type represents the storage related configuration in the fencing policy.

Table 7.340. Attributes summary

NameTypeSummary

enabled

Boolean

If enabled, we will skip fencing in case the host maintains its lease in the storage.

7.261.1. enabled

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.262. Snapshot struct

Represents a snapshot object.

Example XML representation:

<snapshot id="456" href="/ovirt-engine/api/vms/123/snapshots/456">
  <actions>
    <link rel="restore" href="/ovirt-engine/api/vms/123/snapshots/456/restore"/>
  </actions>
  <vm id="123" href="/ovirt-engine/api/vms/123"/>
  <description>Virtual Machine 1 - Snapshot A</description>
  <type>active</type>
  <date>2010-08-16T14:24:29</date>
  <persist_memorystate>false</persist_memorystate>
</snapshot>

Table 7.341. Attributes summary

NameTypeSummary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

 

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

 

custom_emulated_machine

String

 

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

date

Date

The date when this snapshot has been created.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

fqdn

String

Fully qualified domain name of the virtual machine.

guest_operating_system

GuestOperatingSystem

What operating system is installed on the virtual machine.

guest_time_zone

TimeZone

What time zone is used by the virtual machine (as returned by guest agent).

has_illegal_images

Boolean

Indicates whether the virtual machine has snapshots with disks in ILLEGAL state.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

next_run_configuration_exists

Boolean

Virtual machine configuration has been changed and requires restart of the virtual machine.

numa_tune_mode

NumaTuneMode

How the NUMA topology is applied.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

payloads

Payload[]

Optional payloads of the virtual machine, used for ISOs to configure it.

persist_memorystate

Boolean

Indicates if the content of the memory of the virtual machine is included in the snapshot.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

run_once

Boolean

If true, the virtual machine has been started using the run once command, meaning it’s configuration might differ from the stored one for the purpose of this single run.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

snapshot_status

SnapshotStatus

Status of the snapshot.

snapshot_type

SnapshotType

Type of the snapshot.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

start_time

Date

The date in which the virtual machine was started.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

status

VmStatus

The current status of the virtual machine.

status_detail

String

Human readable detail of current status.

stop_reason

String

The reason the virtual machine was stopped.

stop_time

Date

The date in which the virtual machine was stopped.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

use_latest_template_version

Boolean

If true, the virtual machine is reconfigured to the latest version of it’s template when it is started.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

7.262.1. auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Important

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

7.262.2. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

7.262.3. cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

7.262.4. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

7.262.5. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.262.6. initialization

Reference to the virtual machine’s initialization configuration.

Note

Since Red Hat Virtualization 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

7.262.7. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.262.8. lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

7.262.9. memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since Red Hat Virtualization 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Red Hat Virtualization Manager internally rounds values down to whole MiBs (1MiB = 220 bytes)

7.262.10. migration

Reference to configuration of migration of a running virtual machine to another host.

Note

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

7.262.11. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

7.262.12. next_run_configuration_exists

Virtual machine configuration has been changed and requires restart of the virtual machine. Changed configuration is applied at processing the virtual machine’s shut down.

7.262.13. numa_tune_mode

How the NUMA topology is applied. Deprecated in favor of NUMA tune per vNUMA node.

7.262.14. origin

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.262.15. persist_memorystate

Indicates if the content of the memory of the virtual machine is included in the snapshot.

When a snapshot is created the default value is true.

7.262.16. placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

7.262.17. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.262.18. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

7.262.19. stop_reason

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual machine.

7.262.20. tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

7.263. SnapshotStatus enum

Represents the current status of the snapshot.

Table 7.343. Values summary

NameSummary

in_preview

The snapshot is being previewed.

locked

The snapshot is locked.

ok

The snapshot is OK.

7.263.1. locked

The snapshot is locked.

The snapshot is locked when it is in process of being created, deleted, restored or previewed.

7.264. SnapshotType enum

Represents the type of the snapshot.

Table 7.344. Values summary

NameSummary

active

Reference to the current configuration of the virtual machines.

preview

The active snapshot will become preview if some snapshot is being previewed.

regular

Snapshot created by user.

stateless

Snapshot created internally for stateless virtual machines.

7.264.1. preview

The active snapshot will become preview if some snapshot is being previewed.

In other words, this is the active snapshot before preview.

7.264.2. stateless

Snapshot created internally for stateless virtual machines.

This snapshot is created when the virtual machine is started and it is restored when the virtual machine is shut down.

7.265. SpecialObjects struct

This type contains references to special objects, such as blank templates and the root of a hierarchy of tags.

7.266. Spm struct

Table 7.346. Attributes summary

NameTypeSummary

priority

Integer

 

status

SpmStatus

 

7.267. SpmStatus enum

Table 7.347. Values summary

NameSummary

contending

 

none

 

spm

 

7.268. Ssh struct

Table 7.348. Attributes summary

NameTypeSummary

authentication_method

SshAuthenticationMethod

 

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

fingerprint

String

Fingerprint of SSH public key for a host.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

port

Integer

 

public_key

String

SSH public key of the host using SSH public key format as defined in link:https://tools.

user

User

 

7.268.1. fingerprint

Fingerprint of SSH public key for a host. This field is deprecated since 4.4.5 and will be removed in the future.

Please use publicKey instead.

7.268.2. public_key

SSH public key of the host using SSH public key format as defined in RFC4253.

7.269. SshAuthenticationMethod enum

Table 7.349. Values summary

NameSummary

password

 

publickey

 

7.270. SshPublicKey struct

Table 7.350. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

content

String

Contains a saved SSH key.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

7.271. Sso struct

Table 7.352. Attributes summary

NameTypeSummary

methods

Method[]

 

7.272. SsoMethod enum

Table 7.353. Values summary

NameSummary

guest_agent

 

7.273. Statistic struct

A generic type used for all kinds of statistics.

Statistic contains the statistics values for various entities. The following object contain statistics:

  • Disk
  • Host
  • HostNic
  • NumaNode
  • Nic
  • Vm
  • GlusterBrick
  • Step
  • GlusterVolume

An example of a XML representation:

<statistics>
  <statistic id="1234" href="/ovirt-engine/api/hosts/1234/nics/1234/statistics/1234">
    <name>data.current.rx</name>
    <description>Receive data rate</description>
    <values type="DECIMAL">
      <value>
        <datum>0</datum>
      </value>
    </values>
    <type>GAUGE</type>
    <unit>BYTES_PER_SECOND</unit>
    <host_nic id="1234" href="/ovirt-engine/api/hosts/1234/nics/1234"/>
  </statistic>
  ...
</statistics>
Note

This statistics sub-collection is read-only.

Table 7.354. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

kind

StatisticKind

The type of statistic measures.

name

String

A human-readable name in plain text.

type

ValueType

The data type for the statistical values that follow.

unit

StatisticUnit

The unit or rate to measure of the statistical values.

values

Value[]

A data set that contains datum.

7.274. StatisticKind enum

Table 7.356. Values summary

NameSummary

counter

 

gauge

 

7.275. StatisticUnit enum

Table 7.357. Values summary

NameSummary

bits_per_second

 

bytes

 

bytes_per_second

 

count_per_second

 

none

 

percent

 

seconds

 

7.276. Step struct

Represents a step, which is part of job execution. Step is used to describe and track a specific execution unit which is part of a wider sequence. Some steps support reporting their progress.

Table 7.358. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

end_time

Date

The end time of the step.

external

Boolean

Indicates if the step is originated by an external system.

external_type

ExternalSystemType

The external system which is referenced by the step.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

number

Integer

The order of the step in current hierarchy level.

progress

Integer

The step progress (if reported) in percentages.

start_time

Date

The start time of the step.

status

StepStatus

The status of the step.

type

StepEnum

The type of the step.

7.276.1. external

Indicates if the step is originated by an external system. External steps are managed externally, by the creator of the step.

7.277. StepEnum enum

Type representing a step type.

Table 7.360. Values summary

NameSummary

executing

The executing step type.

finalizing

The finalizing step type.

rebalancing_volume

The rebalancing volume step type.

removing_bricks

The removing bricks step type.

unknown

The unknown step type.

validating

The validation step type.

7.277.1. executing

The executing step type. Used to track the main execution block of the job. Usually it will be a parent step of several sub-steps which describe portions of the execution step.

7.277.2. finalizing

The finalizing step type. Describes the post-execution steps requires to complete the job.

7.277.3. rebalancing_volume

The rebalancing volume step type. Describes a step type which is part of Gluster flow.

7.277.4. removing_bricks

The removing bricks step type. Describes a step type which is part of Gluster flow.

7.277.5. unknown

The unknown step type. Describes a step type which its origin is unknown.

7.277.6. validating

The validation step type. Used to verify the correctness of parameters and the validity of the parameters prior to the execution.

7.278. StepStatus enum

Represents the status of the step.

Table 7.361. Values summary

NameSummary

aborted

The aborted step status.

failed

The failed step status.

finished

The finished step status.

started

The started step status.

unknown

The unknown step status.

7.278.1. aborted

The aborted step status. This status is applicable for an external step that was forcibly aborted.

7.278.2. finished

The finished step status. This status describes a completed step execution.

7.278.3. started

The started step status. This status represents a step which is currently being executed.

7.278.4. unknown

The unknown step status. This status represents steps which their resolution is not known, i.e. steps that were executed before the system was unexpectedly restarted.

7.279. StorageConnection struct

Represents a storage server connection.

Example XML representation:

<storage_connection id="123">
  <address>mynfs.example.com</address>
  <type>nfs</type>
  <path>/exports/mydata</path>
</storage_connection>

Table 7.362. Attributes summary

NameTypeSummary

address

String

A storage server connection’s address.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

mount_options

String

The mount options of an NFS storage server connection.

name

String

A human-readable name in plain text.

nfs_retrans

Integer

The NFS retrans value of an NFS storage server connection.

nfs_timeo

Integer

The NFS timeo value of an NFS storage server connection.

nfs_version

NfsVersion

The NFS version of an NFS storage server connection.

password

String

The password of an iSCSI storage server connection.

path

String

The path of an NFS storage server connection.

port

Integer

The port of an iSCSI storage server connection.

portal

String

The portal of an iSCSI storage server connection.

target

String

The target of an iSCSI storage server connection.

type

StorageType

A storage server connection’s type.

username

String

The user name of an iSCSI storage server connection.

vfs_type

String

The VFS type of an NFS storage server connection.

7.280. StorageConnectionExtension struct

Table 7.364. Attributes summary

NameTypeSummary

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

 

target

String

 

username

String

 

7.281. StorageDomain struct

Storage domain.

An XML representation of a NFS storage domain with identifier 123:

<storage_domain href="/ovirt-engine/api/storagedomains/123" id="123">
  <name>mydata</name>
  <description>My data</description>
  <available>38654705664</available>
  <committed>1073741824</committed>
  <critical_space_action_blocker>5</critical_space_action_blocker>
  <external_status>ok</external_status>
  <master>true</master>
  <storage>
    <address>mynfs.example.com</address>
    <nfs_version>v3</nfs_version>
    <path>/exports/mydata</path>
    <type>nfs</type>
  </storage>
  <storage_format>v3</storage_format>
  <type>data</type>
  <used>13958643712</used>
  <warning_low_space_indicator>10</warning_low_space_indicator>
  <wipe_after_delete>false</wipe_after_delete>
  <data_centers>
    <data_center href="/ovirt-engine/api/datacenters/456" id="456"/>
  </data_centers>
</storage_domain>

Table 7.366. Attributes summary

NameTypeSummary

available

Integer

 

backup

Boolean

This attribute indicates whether a data storage domain is used as backup domain or not.

block_size

Integer

Specifies block size in bytes for a storage domain.

comment

String

Free text containing comments about this object.

committed

Integer

 

critical_space_action_blocker

Integer

 

description

String

A human-readable description in plain text.

discard_after_delete

Boolean

Indicates whether disks' blocks on block storage domains will be discarded right before they are deleted.

external_status

ExternalStatus

 

id

String

A unique identifier.

import

Boolean

 

master

Boolean

 

name

String

A human-readable name in plain text.

status

StorageDomainStatus

 

storage

HostStorage

 

storage_format

StorageFormat

 

supports_discard

Boolean

Indicates whether a block storage domain supports discard operations.

supports_discard_zeroes_data

Boolean

Indicates whether a block storage domain supports the property that discard zeroes the data.

type

StorageDomainType

 

used

Integer

 

warning_low_space_indicator

Integer

 

wipe_after_delete

Boolean

Serves as the default value of wipe_after_delete for disks on this storage domain.

7.281.1. backup

This attribute indicates whether a data storage domain is used as backup domain or not. If the domain is set to backup then it will be used to store virtual machines and templates for disaster recovery purposes in the same way we use export storage domain. This attribute is only available with data storage domain and not with ISO domain or export storage domain. User can use this functionality while creating a data storage domain or importing a data storage domain.

7.281.2. block_size

Specifies block size in bytes for a storage domain. Can be omitted and in that case will be defaulted to 512 bytes. Not all storage domains support all possible sizes.

7.281.3. discard_after_delete

Indicates whether disks' blocks on block storage domains will be discarded right before they are deleted.

If true, and a disk on this storage domain has its wipe_after_delete value enabled, then when the disk is deleted:

  1. It is first wiped.
  2. Then its blocks are discarded.
  3. Finally it is deleted.

Note that:

  • Discard after delete will always be false for non block storage types.
  • Discard after delete can be set to true only if the storage domain supports discard.

7.281.4. supports_discard

Indicates whether a block storage domain supports discard operations. A storage domain only supports discard if all of the logical units that it is built from support discard; that is, if each logical unit’s discard_max_size value is greater than 0. This is one of the conditions necessary for a virtual disk in this storage domain to have its pass_discard attribute enabled.

7.281.5. supports_discard_zeroes_data

Indicates whether a block storage domain supports the property that discard zeroes the data. A storage domain only supports the property that discard zeroes the data if all of the logical units that it is built from support it; that is, if each logical unit’s discard_zeroes_data value is true.

Important

Since version 4.2.1 of the system, the support for this attribute has been removed as the sysfs file, discard_zeroes_data, was deprecated in the kernel. It is preserved for backwards compatibility, but the value will always be false.

7.281.6. wipe_after_delete

Serves as the default value of wipe_after_delete for disks on this storage domain.

That is, newly created disks will get their wipe_after_delete value from their storage domains by default. Note that the configuration value SANWipeAfterDelete serves as the default value of block storage domains' wipe_after_delete value.

7.282. StorageDomainLease struct

Represents a lease residing on a storage domain.

A lease is a Sanlock resource residing on a special volume on the storage domain, this Sanlock resource is used to provide storage base locking.

7.283. StorageDomainStatus enum

Table 7.369. Values summary

NameSummary

activating

 

active

 

detaching

 

inactive

 

locked

 

maintenance

 

mixed

 

preparing_for_maintenance

 

unattached

 

unknown

 

7.284. StorageDomainType enum

Indicates the kind of data managed by a storage domain.

Table 7.370. Values summary

NameSummary

data

Data domains are used to store the disks and snapshots of the virtual machines and templates in the system.

export

Export domains are temporary storage repositories used to copy and move virtual machines and templates between data centers and Red Hat Virtualization environments.

image

Image domain store images that can be imported into from an external system.

iso

ISO domains store ISO files (or logical CDs) used to install and boot operating systems and applications for the virtual machines.

managed_block_storage

Managed block storage domains are created on block storage devices.

volume

Volume domains store logical volumes that can be used as disks for virtual machines.

7.284.1. data

Data domains are used to store the disks and snapshots of the virtual machines and templates in the system. In addition, snapshots of the disks are also stored in data domains. Data domains cannot be shared across data centers.

7.284.2. export

Export domains are temporary storage repositories used to copy and move virtual machines and templates between data centers and Red Hat Virtualization environments. Export domains can also be used to backup virtual machines. An export domain can be moved between data centers but it can only be active in one data center at a time.

7.284.3. image

Image domain store images that can be imported into from an external system. For example, images from an OpenStack Glance image repository.

7.284.4. iso

ISO domains store ISO files (or logical CDs) used to install and boot operating systems and applications for the virtual machines. ISO domains remove the data center’s need for physical media. An ISO domain can be shared across different data centers.

7.284.5. managed_block_storage

Managed block storage domains are created on block storage devices. These domains are accessed and managed by cinder.

7.284.6. volume

Volume domains store logical volumes that can be used as disks for virtual machines. For example, volumes from an OpenStack Cincer block storage service.

7.285. StorageFormat enum

Type which represents a format of storage domain.

Table 7.371. Values summary

NameSummary

v1

Version 1 of the storage domain format is applicable to NFS, iSCSI and FC storage domains.

v2

Version 2 of the storage domain format is applicable to iSCSI and FC storage domains.

v3

Version 3 of the storage domain format is applicable to NFS, POSIX, iSCSI and FC storage domains.

v4

Version 4 of the storage domain format.

v5

Version 5 of the storage domain format is applicable to NFS, POSIX, and Gluster storage domains.

7.285.1. v1

Version 1 of the storage domain format is applicable to NFS, iSCSI and FC storage domains.

Each storage domain contains metadata describing its own structure, and all of the names of physical volumes that are used to back virtual machine disk images. Master domains additionally contain metadata for all the domains and physical volume names in the storage pool. The total size of this metadata is limited to 2 KiB, limiting the number of storage domains that can be in a pool. Template and virtual machine base images are read only.

7.285.2. v2

Version 2 of the storage domain format is applicable to iSCSI and FC storage domains.

All storage domain and pool metadata is stored as logical volume tags rather than written to a logical volume. Metadata about virtual machine disk volumes is still stored in a logical volume on the domains. Physical volume names are no longer included in the metadata. Template and virtual machine base images are read only.

7.285.3. v3

Version 3 of the storage domain format is applicable to NFS, POSIX, iSCSI and FC storage domains.

All storage domain and pool metadata is stored as logical volume tags rather than written to a logical volume. Metadata about virtual machine disk volumes is still stored in a logical volume on the domains. Virtual machine and template base images are no longer read only. This change enables live snapshots, live storage migration, and clone from snapshot. Support for Unicode metadata is added, for non-English volume names.

7.285.4. v5

Version 5 of the storage domain format is applicable to NFS, POSIX, and Gluster storage domains.

Added support for 4096 bytes block sizes and variable sanlock alignments.

7.286. StorageType enum

Type representing a storage domain type.

Table 7.372. Values summary

NameSummary

cinder

Cinder storage domain.

fcp

Fibre-Channel storage domain.

glance

Glance storage domain.

glusterfs

Gluster-FS storage domain.

iscsi

iSCSI storage domain.

localfs

Storage domain on Local storage.

managed_block_storage

Managed block storage domain.

nfs

NFS storage domain.

posixfs

POSIX-FS storage domain.

7.286.1. cinder

Cinder storage domain. For more details on Cinder please go to Cinder.

7.286.2. glance

Glance storage domain. For more details on Glance please go to Glance.

7.286.3. glusterfs

Gluster-FS storage domain. For more details on Gluster please go to Gluster.

7.286.4. managed_block_storage

Managed block storage domain. A storage domain managed using cinderlib. For supported storage drivers, see Available Drivers.

7.287. SwitchType enum

Describes all switch types supported by the Manager.

Table 7.373. Values summary

NameSummary

legacy

The native switch type.

ovs

The Open vSwitch type.

7.288. SystemOption struct

Type representing a configuration option of the system.

Table 7.374. Attributes summary

NameTypeSummary

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.

values

SystemOptionValue[]

Values of the option for various system versions.

7.289. SystemOptionValue struct

Type representing a pair of value and version of a configuration option.

Table 7.375. Attributes summary

NameTypeSummary

value

String

Configuration option’s value for specific version.

version

String

Configuration option’s version.

7.290. Tag struct

Represents a tag in the system.

Table 7.376. Attributes summary

NameTypeSummary

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.

7.291. Template struct

The type that represents a virtual machine template. Templates allow for a rapid instantiation of virtual machines with common configuration and disk states.

Table 7.378. Attributes summary

NameTypeSummary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

 

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

 

custom_emulated_machine

String

 

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

status

TemplateStatus

The status of the template.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

version

TemplateVersion

Indicates whether this is the base version or a sub-version of another template.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

vm

Vm

The virtual machine configuration associated with this template.

7.291.1. auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Important

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

7.291.2. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

7.291.3. cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

7.291.4. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

7.291.5. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.291.6. initialization

Reference to the virtual machine’s initialization configuration.

Note

Since Red Hat Virtualization 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

7.291.7. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.291.8. lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

7.291.9. memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since Red Hat Virtualization 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Red Hat Virtualization Manager internally rounds values down to whole MiBs (1MiB = 220 bytes)

7.291.10. migration

Reference to configuration of migration of a running virtual machine to another host.

Note

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

7.291.11. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

7.291.12. origin

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.291.13. placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

7.291.14. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.291.15. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

7.291.16. tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

7.292. TemplateStatus enum

Type representing a status of a virtual machine template.

Table 7.380. Values summary

NameSummary

illegal

This status indicates that at least one of the disks of the template is illegal.

locked

This status indicates that some operation that prevents other operations with the template is being executed.

ok

This status indicates that the template is valid and ready for use.

7.293. TemplateVersion struct

Type representing a version of a virtual machine template.

Table 7.381. Attributes summary

NameTypeSummary

version_name

String

The name of this version.

version_number

Integer

The index of this version in the versions hierarchy of the template.

7.293.1. version_number

The index of this version in the versions hierarchy of the template. The index 1 represents the original version of a template that is also called base version.

7.294. Ticket struct

Type representing a ticket that allows virtual machine access.

Table 7.383. Attributes summary

NameTypeSummary

expiry

Integer

Time to live for the ticket in seconds.

value

String

The virtual machine access ticket.

7.295. TimeZone struct

Time zone representation.

Table 7.384. Attributes summary

NameTypeSummary

name

String

Name of the time zone.

utc_offset

String

UTC offset.

7.295.1. utc_offset

UTC offset.

Offset from UTC.

7.296. TpmSupport enum

Table 7.385. Values summary

NameSummary

required

TPM is required by the operating system

supported

TPM is supported but optional

unsupported

 

7.297. TransparentHugePages struct

Type representing a transparent huge pages (THP) support.

Table 7.386. Attributes summary

NameTypeSummary

enabled

Boolean

Enable THP support.

7.298. TransportType enum

Protocol used to access a Gluster volume.

Table 7.387. Values summary

NameSummary

rdma

Remote direct memory access.

tcp

TCP.

7.299. UnmanagedNetwork struct

Table 7.388. Attributes summary

NameTypeSummary

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.

7.300. Usb struct

Configuration of the USB device of a virtual machine.

Table 7.390. Attributes summary

NameTypeSummary

enabled

Boolean

Determines whether the USB device should be included or not.

type

UsbType

USB type, currently only native is supported.

7.301. UsbType enum

Type of USB device redirection.

Table 7.391. Values summary

NameSummary

legacy

Legacy USB redirection.

native

Native USB redirection.

7.301.1. legacy

Legacy USB redirection.

This USB type has been deprecated since version 3.6 of the engine, and has been completely removed in version 4.1. It is preserved only to avoid syntax errors in existing scripts. If it is used it will be automatically replaced by native.

7.301.2. native

Native USB redirection.

Native USB redirection allows KVM/SPICE USB redirection for Linux and Windows virtual machines. Virtual (guest) machines require no guest-installed agents or drivers for native USB. On Linux clients, all packages required for USB redirection are provided by the virt-viewer package. On Windows clients, you must also install the usbdk package.

7.302. User struct

Represents a user in the system.

Table 7.392. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

department

String

 

description

String

A human-readable description in plain text.

domain_entry_id

String

 

email

String

 

id

String

A unique identifier.

last_name

String

 

logged_in

Boolean

 

name

String

A human-readable name in plain text.

namespace

String

Namespace where the user resides.

password

String

 

principal

String

Similar to user_name.

user_name

String

The user’s username.

user_options

Property[]

User options allow you to save key/value properties which are used to customize the settings per individual user.

7.302.1. namespace

Namespace where the user resides. When using the authorization provider that stores users in the LDAP server, this attribute equals the naming context of the LDAP server. See oVirt Engine Extension AAA LDAP for more information. When using the built-in authorization provider that stores users in the database this attribute is ignored. See oVirt Engine extension - AAA - JDBC for more information.

7.302.2. principal

Similar to user_name. The format depends on the LDAP provider. With most LDAP providers it is the value of the uid LDAP attribute. In the case of Active Directory it is the User Principal Name (UPN).

7.302.3. user_name

The user’s username. The format depends on authorization provider type. In most LDAP providers it is the value of the uid LDAP attribute. In Active Directory it is the User Principal Name (UPN). UPN or uid must be followed by the authorization provider name. For example, in the case of LDAP’s uid attribute it is: myuser@myextension-authz. In the case of Active Directory using UPN it is: myuser@mysubdomain.mydomain.com@myextension-authz. This attribute is a required parameter when adding a new user.

7.302.4. user_options

User options allow you to save key/value properties which are used to customize the settings per individual user. Note that since version 4.4.5 this property is deprecated and preserved only for backwards compatibility. It will be removed in the future. Please use the options endpoint instead.

7.303. UserOption struct

User options allow you to save key/value properties which are used to customize the settings per individual user.

Table 7.394. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

content

String

JSON content encoded as string.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

name

String

A human-readable name in plain text.

7.303.1. content

JSON content encoded as string. Any valid JSON is supported.

7.304. Value struct

Table 7.396. Attributes summary

NameTypeSummary

datum

Decimal

 

detail

String

 

7.305. ValueType enum

Table 7.397. Values summary

NameSummary

decimal

 

integer

 

string

 

7.306. VcpuPin struct

Table 7.398. Attributes summary

NameTypeSummary

cpu_set

String

 

vcpu

Integer

 

7.307. Vendor struct

Table 7.399. Attributes summary

NameTypeSummary

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.

7.308. Version struct

Table 7.400. Attributes summary

NameTypeSummary

build

Integer

 

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

full_version

String

 

id

String

A unique identifier.

major

Integer

 

minor

Integer

 

name

String

A human-readable name in plain text.

revision

Integer

 

7.309. VgpuPlacement enum

The vGPU placement strategy.

It can either put vGPUs on the first available physical cards, or spread them over multiple physical cards.

Table 7.401. Values summary

NameSummary

consolidated

Use consolidated placement.

separated

Use separated placement.

7.309.1. consolidated

Use consolidated placement. Each vGPU is placed on the first physical card with available space.

This is the default placement, utilizing all available space on the physical cards.

7.309.2. separated

Use separated placement. Each vGPU is placed on a separate physical card, if possible.

This can be useful for improving vGPU performance.

7.310. VirtioScsi struct

Type representing the support of virtio-SCSI. If it supported we use virtio driver for SCSI guest device.

Table 7.402. Attributes summary

NameTypeSummary

enabled

Boolean

Enable Virtio SCSI support.

7.311. VirtualNumaNode struct

Represents the virtual NUMA node.

An example XML representation:

<vm_numa_node href="/ovirt-engine/api/vms/123/numanodes/456" id="456">
  <cpu>
    <cores>
      <core>
        <index>0</index>
      </core>
    </cores>
  </cpu>
  <index>0</index>
  <memory>1024</memory>
  <numa_node_pins>
    <numa_node_pin>
      <index>0</index>
    </numa_node_pin>
  </numa_node_pins>
  <vm href="/ovirt-engine/api/vms/123" id="123" />
</vm_numa_node>

Table 7.403. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

cpu

Cpu

 

description

String

A human-readable description in plain text.

id

String

A unique identifier.

index

Integer

 

memory

Integer

Memory of the NUMA node in MB.

name

String

A human-readable name in plain text.

node_distance

String

 

numa_node_pins

NumaNodePin[]

 

numa_tune_mode

NumaTuneMode

How the NUMA topology is applied.

7.312. Vlan struct

Type representing a Virtual LAN (VLAN) type.

Table 7.405. Attributes summary

NameTypeSummary

id

Integer

Virtual LAN ID.

7.313. Vm struct

Represents a virtual machine.

Table 7.406. Attributes summary

NameTypeSummary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

 

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

 

custom_emulated_machine

String

 

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

fqdn

String

Fully qualified domain name of the virtual machine.

guest_operating_system

GuestOperatingSystem

What operating system is installed on the virtual machine.

guest_time_zone

TimeZone

What time zone is used by the virtual machine (as returned by guest agent).

has_illegal_images

Boolean

Indicates whether the virtual machine has snapshots with disks in ILLEGAL state.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

next_run_configuration_exists

Boolean

Virtual machine configuration has been changed and requires restart of the virtual machine.

numa_tune_mode

NumaTuneMode

How the NUMA topology is applied.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

payloads

Payload[]

Optional payloads of the virtual machine, used for ISOs to configure it.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

run_once

Boolean

If true, the virtual machine has been started using the run once command, meaning it’s configuration might differ from the stored one for the purpose of this single run.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

start_time

Date

The date in which the virtual machine was started.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

status

VmStatus

The current status of the virtual machine.

status_detail

String

Human readable detail of current status.

stop_reason

String

The reason the virtual machine was stopped.

stop_time

Date

The date in which the virtual machine was stopped.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

use_latest_template_version

Boolean

If true, the virtual machine is reconfigured to the latest version of it’s template when it is started.

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

7.313.1. auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Important

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

7.313.2. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

7.313.3. cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

7.313.4. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

7.313.5. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.313.6. initialization

Reference to the virtual machine’s initialization configuration.

Note

Since Red Hat Virtualization 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

7.313.7. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.313.8. lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

7.313.9. memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since Red Hat Virtualization 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Red Hat Virtualization Manager internally rounds values down to whole MiBs (1MiB = 220 bytes)

7.313.10. migration

Reference to configuration of migration of a running virtual machine to another host.

Note

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

7.313.11. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

7.313.12. next_run_configuration_exists

Virtual machine configuration has been changed and requires restart of the virtual machine. Changed configuration is applied at processing the virtual machine’s shut down.

7.313.13. numa_tune_mode

How the NUMA topology is applied. Deprecated in favor of NUMA tune per vNUMA node.

7.313.14. origin

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.313.15. placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

7.313.16. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.313.17. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

7.313.18. stop_reason

The reason the virtual machine was stopped. Optionally set by user when shutting down the virtual machine.

7.313.19. tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

7.314. VmAffinity enum

Table 7.408. Values summary

NameSummary

migratable

 

pinned

 

user_migratable

 

7.315. VmBase struct

Represents basic virtual machine configuration. This is used by virtual machines, templates and instance types.

Table 7.409. Attributes summary

NameTypeSummary

auto_pinning_policy

AutoPinningPolicy

Specifies if and how the auto CPU and NUMA configuration is applied.

bios

Bios

Reference to virtual machine’s BIOS configuration.

comment

String

Free text containing comments about this object.

console

Console

Console configured for this virtual machine.

cpu

Cpu

The configuration of the virtual machine CPU.

cpu_pinning_policy

CpuPinningPolicy

Specifies if and how the CPU and NUMA configuration is applied.

cpu_shares

Integer

 

creation_time

Date

The virtual machine creation date.

custom_compatibility_version

Version

Virtual machine custom compatibility version.

custom_cpu_model

String

 

custom_emulated_machine

String

 

custom_properties

CustomProperty[]

Properties sent to VDSM to configure various hooks.

delete_protected

Boolean

If true, the virtual machine cannot be deleted.

description

String

A human-readable description in plain text.

display

Display

The virtual machine display configuration.

domain

Domain

Domain configured for this virtual machine.

high_availability

HighAvailability

The virtual machine high availability configuration.

id

String

A unique identifier.

initialization

Initialization

Reference to the virtual machine’s initialization configuration.

io

Io

For performance tuning of IO threading.

large_icon

Icon

Virtual machine’s large icon.

lease

StorageDomainLease

Reference to the storage domain this virtual machine/template lease reside on.

memory

Integer

The virtual machine’s memory, in bytes.

memory_policy

MemoryPolicy

Reference to virtual machine’s memory management configuration.

migration

MigrationOptions

Reference to configuration of migration of a running virtual machine to another host.

migration_downtime

Integer

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

multi_queues_enabled

Boolean

If true, each virtual interface will get the optimal number of queues, depending on the available virtual Cpus.

name

String

A human-readable name in plain text.

origin

String

The origin of this virtual machine.

os

OperatingSystem

Operating system type installed on the virtual machine.

placement_policy

VmPlacementPolicy

The configuration of the virtual machine’s placement policy.

rng_device

RngDevice

Random Number Generator device configuration for this virtual machine.

serial_number

SerialNumber

Virtual machine’s serial number in a cluster.

small_icon

Icon

Virtual machine’s small icon.

soundcard_enabled

Boolean

If true, the sound card is added to the virtual machine.

sso

Sso

Reference to the Single Sign On configuration this virtual machine is configured for.

start_paused

Boolean

If true, the virtual machine will be initially in 'paused' state after start.

stateless

Boolean

If true, the virtual machine is stateless - it’s state (disks) are rolled-back after shutdown.

storage_error_resume_behaviour

VmStorageErrorResumeBehaviour

Determines how the virtual machine will be resumed after storage error.

time_zone

TimeZone

The virtual machine’s time zone set by oVirt.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

tunnel_migration

Boolean

If true, the network data transfer will be encrypted during virtual machine live migration.

type

VmType

Determines whether the virtual machine is optimized for desktop or server.

usb

Usb

Configuration of USB devices for this virtual machine (count, type).

virtio_scsi

VirtioScsi

Reference to VirtIO SCSI configuration.

virtio_scsi_multi_queues

Integer

Number of queues for a Virtio-SCSI contoller this field requires virtioScsiMultiQueuesEnabled to be true see virtioScsiMultiQueuesEnabled for more info

virtio_scsi_multi_queues_enabled

Boolean

If true, the Virtio-SCSI devices will obtain a number of multiple queues depending on the available virtual Cpus and disks, or according to the specified virtioScsiMultiQueues.

7.315.1. auto_pinning_policy

Specifies if and how the auto CPU and NUMA configuration is applied.

Important

Since version 4.5 of the engine this operation is deprecated, and preserved only for backwards compatibility. It might be removed in the future. Please use CpuPinningPolicy instead.

7.315.2. cpu

The configuration of the virtual machine CPU.

The socket configuration can be updated without rebooting the virtual machine. The cores and the threads require a reboot.

For example, to change the number of sockets to 4 immediately, and the number of cores and threads to 2 after reboot, send the following request:

PUT /ovirt-engine/api/vms/123

With a request body:

<vm>
  <cpu>
    <topology>
      <sockets>4</sockets>
      <cores>2</cores>
      <threads>2</threads>
    </topology>
  </cpu>
</vm>

7.315.3. cpu_pinning_policy

Specifies if and how the CPU and NUMA configuration is applied. When not specified the previous behavior of CPU pinning string will determine CpuPinningPolicy to None or Manual.

7.315.4. custom_compatibility_version

Virtual machine custom compatibility version.

Enables a virtual machine to be customized to its own compatibility version. If custom_compatibility_version is set, it overrides the cluster’s compatibility version for this particular virtual machine.

The compatibility version of a virtual machine is limited by the data center the virtual machine resides in, and is checked against capabilities of the host the virtual machine is planned to run on.

7.315.5. high_availability

The virtual machine high availability configuration. If set, the virtual machine will be automatically restarted when it unexpectedly goes down.

7.315.6. initialization

Reference to the virtual machine’s initialization configuration.

Note

Since Red Hat Virtualization 4.1.8 this property can be cleared by sending an empty tag.

For example, to clear the initialization attribute send a request like this:

PUT /ovirt-engine/api/vms/123

With a request body like this:

<vm>
  <initialization/>
</vm>

The response to such a request, and requests with the header All-Content: true will still contain this attribute.

7.315.7. large_icon

Virtual machine’s large icon. Either set by user or refers to image set according to operating system.

7.315.8. lease

Reference to the storage domain this virtual machine/template lease reside on.

A virtual machine running with a lease requires checking while running that the lease is not taken by another host, preventing another instance of this virtual machine from running on another host. This provides protection against split-brain in highly available virtual machines. A template can also have a storage domain defined for a lease in order to have the virtual machines created from this template to be preconfigured with this storage domain as the location of the leases.

7.315.9. memory

The virtual machine’s memory, in bytes.

For example, to update a virtual machine to contain 1 Gibibyte (GiB) of memory, send the following request:

PUT /ovirt-engine/api/vms/123

With the following request body:

<vm>
  <memory>1073741824</memory>
</vm>

Memory hot plug is supported from Red Hat Virtualization 3.6 onwards. You can use the example above to increase memory while the virtual machine is in state up. The size increment must be dividable by the value of the HotPlugMemoryBlockSizeMb configuration value (256 MiB by default). If the memory size increment is not dividable by this value, the memory size change is only stored to next run configuration. Each successful memory hot plug operation creates one or two new memory devices.

Memory hot unplug is supported since Red Hat Virtualization 4.2 onwards. Memory hot unplug can only be performed when the virtual machine is in state up. Only previously hot plugged memory devices can be removed by the hot unplug operation. The requested memory decrement is rounded down to match sizes of a combination of previously hot plugged memory devices. The requested memory value is stored to next run configuration without rounding.

Note

Memory in the example is converted to bytes using the following formula:
1 GiB = 230 bytes = 1073741824 bytes.

Note

Red Hat Virtualization Manager internally rounds values down to whole MiBs (1MiB = 220 bytes)

7.315.10. migration

Reference to configuration of migration of a running virtual machine to another host.

Note

API for querying migration policy by ID returned by this method is not implemented yet. Use /ovirt-engine/api/options/MigrationPolicies to get a list of all migration policies with their IDs.

7.315.11. migration_downtime

Maximum time the virtual machine can be non responsive during its live migration to another host in ms.

Set either explicitly for the virtual machine or by engine-config -s DefaultMaximumMigrationDowntime=[value]

7.315.12. origin

The origin of this virtual machine.

Possible values:

  • ovirt
  • rhev
  • vmware
  • xen
  • external
  • hosted_engine
  • managed_hosted_engine
  • kvm
  • physical_machine
  • hyperv

7.315.13. placement_policy

The configuration of the virtual machine’s placement policy.

This configuration can be updated to pin a virtual machine to one or more hosts.

Note

Virtual machines that are pinned to multiple hosts cannot be live migrated, but in the event of a host failure, any virtual machine configured to be highly available is automatically restarted on one of the other hosts to which the virtual machine is pinned.

For example, to pin a virtual machine to two hosts, send the following request:

PUT /api/vms/123

With a request body like this:

<vm>
  <high_availability>
    <enabled>true</enabled>
    <priority>1</priority>
  </high_availability>
  <placement_policy>
    <hosts>
      <host>
        <name>Host1</name>
      </host>
      <host>
        <name>Host2</name>
      </host>
    </hosts>
    <affinity>pinned</affinity>
  </placement_policy>
</vm>

7.315.14. small_icon

Virtual machine’s small icon. Either set by user or refers to image set according to operating system.

7.315.15. sso

Reference to the Single Sign On configuration this virtual machine is configured for. The user can be automatically signed in the virtual machine’s operating system when console is opened.

7.315.16. tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

7.316. VmDeviceType enum

Table 7.411. Values summary

NameSummary

cdrom

 

floppy

 

7.317. VmMediatedDevice struct

VM mediated device is a fake device specifying properties of vGPU mediated devices. It is not an actual device, it just serves as a specification how to configure a part of a host device.

Table 7.412. Attributes summary

NameTypeSummary

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.

spec_params

Property[]

Properties of the device.

7.318. VmPlacementPolicy struct

Table 7.414. Attributes summary

NameTypeSummary

affinity

VmAffinity

 

7.319. VmPool struct

Type representing a virtual machines pool.

Table 7.416. Attributes summary

NameTypeSummary

auto_storage_select

Boolean

Indicates if the pool should automatically distribute the disks of the virtual machines across the multiple storage domains where the template is copied.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

display

Display

The display settings configured for virtual machines in the pool.

id

String

A unique identifier.

max_user_vms

Integer

The maximum number of virtual machines in the pool that could be assigned to a particular user.

name

String

A human-readable name in plain text.

prestarted_vms

Integer

The system attempts to prestart the specified number of virtual machines from the pool.

rng_device

RngDevice

The random number generator device configured for virtual machines in the pool.

size

Integer

The number of virtual machines in the pool.

soundcard_enabled

Boolean

Indicates if sound card should be configured for virtual machines in the pool.

stateful

Boolean

Virtual machine pool’s stateful flag.

tpm_enabled

Boolean

If true, a TPM device is added to the virtual machine.

type

VmPoolType

The deallocation policy of virtual machines in the pool.

use_latest_template_version

Boolean

Indicates if virtual machines in the pool are updated to newer versions of the template the pool is based on.

7.319.1. auto_storage_select

Indicates if the pool should automatically distribute the disks of the virtual machines across the multiple storage domains where the template is copied.

When the template used by the pool is present in multiple storage domains, the disks of the virtual machines of the pool will be created in one of those storage domains. By default, or when the value of this attribute is false, that storage domain is selected when the pool is created, and all virtual machines will use the same. If this attribute is true, then, when a virtual machine is added to the pool, the storage domain that has more free space is selected.

7.319.2. display

The display settings configured for virtual machines in the pool.

Warning

Please note that this attribute is not working and is now deprecated. Please use Vm.display instead.

7.319.3. prestarted_vms

The system attempts to prestart the specified number of virtual machines from the pool.

These virtual machines are started without being attached to any user. That way, users can acquire virtual machines from the pool faster.

7.319.4. stateful

Virtual machine pool’s stateful flag.

Virtual machines from a stateful virtual machine pool are always started in stateful mode (stateless snapshot is not created). The state of the virtual machine is preserved even when the virtual machine is passed to a different user.

7.319.5. tpm_enabled

If true, a TPM device is added to the virtual machine. By default the value is false. This property is only visible when fetching if "All-Content=true" header is set.

7.320. VmPoolType enum

Type representing the deallocation policy of virtual machines in a virtual machines pool.

Table 7.418. Values summary

NameSummary

automatic

This policy indicates that virtual machines in the pool are automcatically deallocated by the system.

manual

This policy indicates that virtual machines in the pool are deallocated manually by the administrator.

7.320.1. automatic

This policy indicates that virtual machines in the pool are automcatically deallocated by the system.

With this policy, when a virtual machine that is part of the pool and is assigned to a user is shut-down, it is detached from the user, its state is restored to the pool’s default state, and the virtual machine returns to pool (i.e., the virtual machine can then be assigned to another user).

7.320.2. manual

This policy indicates that virtual machines in the pool are deallocated manually by the administrator.

With this policy, a virtual machine that is part of the pool remains assigned to its user and preserves its state on shut-down. In order to return the virtual machine back to the pool, the administrator needs to deallocate it explicitly by removing the user’s permissions on that virtual machine.

7.321. VmStatus enum

Type representing a status of a virtual machine.

Table 7.419. Values summary

NameSummary

down

This status indicates that the virtual machine process is not running.

image_locked

This status indicates that the virtual machine process is not running and there is some operation on the disks of the virtual machine that prevents it from being started.

migrating

This status indicates that the virtual machine process is running and the virtual machine is being migrated from one host to another.

not_responding

This status indicates that the hypervisor detected that the virtual machine is not responding.

paused

This status indicates that the virtual machine process is running and the virtual machine is paused.

powering_down

This status indicates that the virtual machine process is running and it is about to stop running.

powering_up

This status indicates that the virtual machine process is running and the guest operating system is being loaded.

reboot_in_progress

This status indicates that the virtual machine process is running and the guest operating system is being rebooted.

restoring_state

This status indicates that the virtual machine process is about to run and the virtual machine is going to awake from hibernation.

saving_state

This status indicates that the virtual machine process is running and the virtual machine is being hibernated.

suspended

This status indicates that the virtual machine process is not running and a running state of the virtual machine was saved.

unassigned

This status is set when an invalid status is received.

unknown

This status indicates that the system failed to determine the status of the virtual machine.

up

This status indicates that the virtual machine process is running and the guest operating system is loaded.

wait_for_launch

This status indicates that the virtual machine process is about to run.

7.321.1. paused

This status indicates that the virtual machine process is running and the virtual machine is paused. This may happen in two cases: when running a virtual machine is paused mode and when the virtual machine is being automatically paused due to an error.

7.321.2. powering_up

This status indicates that the virtual machine process is running and the guest operating system is being loaded. Note that if no guest-agent is installed, this status is set for a predefined period of time, that is by default 60 seconds, when running a virtual machine.

7.321.3. restoring_state

This status indicates that the virtual machine process is about to run and the virtual machine is going to awake from hibernation. In this status, the running state of the virtual machine is being restored.

7.321.4. saving_state

This status indicates that the virtual machine process is running and the virtual machine is being hibernated. In this status, the running state of the virtual machine is being saved. Note that this status does not mean that the guest operating system is being hibernated.

7.321.5. suspended

This status indicates that the virtual machine process is not running and a running state of the virtual machine was saved. This status is similar to Down, but when the VM is started in this status its saved running state is restored instead of being booted using the normal procedue.

7.321.6. unknown

This status indicates that the system failed to determine the status of the virtual machine. The virtual machine process may be running or not running in this status. For instance, when host becomes non-responsive the virtual machines that ran on it are set with this status.

7.321.7. up

This status indicates that the virtual machine process is running and the guest operating system is loaded. Note that if no guest-agent is installed, this status is set after a predefined period of time, that is by default 60 seconds, when running a virtual machine.

7.321.8. wait_for_launch

This status indicates that the virtual machine process is about to run. This status is set when a request to run a virtual machine arrives to the host. It is possible that the virtual machine process will fail to run.

7.322. VmStorageErrorResumeBehaviour enum

If the storage, on which this virtual machine has some disks gets unresponsive, the virtual machine gets paused.

This are the possible options, what should happen with the virtual machine in the moment the storage gets available again.

Table 7.420. Values summary

NameSummary

auto_resume

The virtual machine gets resumed automatically in the moment the storage is available again.

kill

The virtual machine will be killed after a timeout (configurable on the hypervisor).

leave_paused

Do nothing with the virtual machine.

7.322.1. auto_resume

The virtual machine gets resumed automatically in the moment the storage is available again.

This is the only behavior available before 4.2.

7.322.2. kill

The virtual machine will be killed after a timeout (configurable on the hypervisor).

This is the only option supported for highly available virtual machines with leases. The reason is that the highly available virtual machine is restarted using the infrastructure and any kind of resume risks split brains.

7.322.3. leave_paused

Do nothing with the virtual machine.

Useful if there is a custom failover implemented and the user does not want the virtual machine to get resumed.

7.323. VmSummary struct

Type containing information related to virtual machines on a particular host.

Table 7.421. Attributes summary

NameTypeSummary

active

Integer

The number of virtual machines active on the host.

migrating

Integer

The number of virtual machines migrating to or from the host.

total

Integer

The number of virtual machines present on the host.

7.324. VmType enum

Type representing what the virtual machine is optimized for.

Table 7.422. Values summary

NameSummary

desktop

The virtual machine is intended to be used as a desktop.

high_performance

The virtual machine is intended to be used as a high performance virtual machine.

server

The virtual machine is intended to be used as a server.

7.324.1. desktop

The virtual machine is intended to be used as a desktop.

Currently, its implication is that a sound device will automatically be added to the virtual machine.

7.324.2. high_performance

The virtual machine is intended to be used as a high performance virtual machine.

Currently, its implication is that the virtual machine configuration will automatically be set for running with the highest possible performance, and with performance metrics as close to bare metal as possible.

Some of the recommended configuration settings for the highest possible performance cannot be set automatically; manually setting them before running the virtual machine is recommended.

The following configuration changes are set automatically:

  • Enable headless mode.
  • Enable serial console.
  • Enable pass-through host CPU.
  • Enable I/O threads.
  • Enable I/O threads pinning and set the pinning topology.
  • Enable the paravirtualized random number generator PCI (virtio-rng) device.
  • Disable all USB devices.
  • Disable the soundcard device.
  • Disable the smartcard device.
  • Disable the memory balloon device.
  • Disable the watchdog device.
  • Disable migration.
  • Disable high availability.

The following recommended configuration changes have to be set manually by the user:

  • Enable CPU pinning topology.
  • Enable non-uniform memory access (NUMA) pinning topology.
  • Enable and set huge pages configuration.
  • Disable kernel same-page merging (KSM).

7.324.3. server

The virtual machine is intended to be used as a server.

Currently, its implication is that a sound device will not automatically be added to the virtual machine.

7.325. VnicPassThrough struct

Table 7.423. Attributes summary

NameTypeSummary

mode

VnicPassThroughMode

Defines whether the vNIC will be implemented as a virtual device, or as a pass-through to a host device.

7.326. VnicPassThroughMode enum

Describes whether the vNIC is to be implemented as a pass-through device or a virtual one.

Table 7.424. Values summary

NameSummary

disabled

To be implemented as a virtual device.

enabled

To be implemented as a pass-through device.

7.327. VnicProfile struct

A vNIC profile is a collection of settings that can be applied to individual NIC.

Table 7.425. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

custom_properties

CustomProperty[]

Custom properties applied to the vNIC profile.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

migratable

Boolean

Marks whether pass_through NIC is migratable or not.

name

String

A human-readable name in plain text.

pass_through

VnicPassThrough

Enables passthrough to an SR-IOV-enabled host NIC.

port_mirroring

Boolean

Enables port mirroring.

7.327.1. migratable

Marks whether pass_through NIC is migratable or not.

If pass_through.mode is set to disabled this option has no meaning, and it will be considered to be true. If you omit this option from a request, by default, this will be set to true.

When migrating a virtual machine, this virtual machine will be migrated only if all pass_through NICs are flagged as migratable.

7.327.2. pass_through

Enables passthrough to an SR-IOV-enabled host NIC.

A vNIC profile enables a NIC to be directly connected to a virtual function (VF) of an SR-IOV-enabled host NIC, if passthrough is enabled. The NIC will then bypass the software network virtualization and connect directly to the VF for direct device assignment.

Passthrough cannot be enabled if the vNIC profile is already attached to a NIC. If a vNIC profile has passthrough enabled, qos and port_mirroring are disabled for the vNIC profile.

7.327.3. port_mirroring

Enables port mirroring.

Port mirroring copies layer 3 network traffic on a given logical network and host to a NIC on a virtual machine. This virtual machine can be used for network debugging and tuning, intrusion detection, and monitoring the behavior of other virtual machines on the same host and logical network. The only traffic copied is internal to one logical network on one host. There is no increase in traffic on the network external to the host; however a virtual machine with port mirroring enabled uses more host CPU and RAM than other virtual machines.

Port mirroring has the following limitations:

  • Hot linking a NIC with a vNIC profile that has port mirroring enabled is not supported.
  • Port mirroring cannot be altered when the vNIC profile is attached to a virtual machine.

Given the above limitations, it is recommended that you enable port mirroring on an additional, dedicated vNIC profile.

Important

Enabling port mirroring reduces the privacy of other network users.

7.328. VnicProfileMapping struct

Deprecated type that maps an external virtual NIC profile to one that exists in the Red Hat Virtualization Manager.

If, for example, the desired virtual NIC profile’s mapping includes the following two lines:

Source network nameSource network profile nameTarget virtual NIC profile ID

red

gold

738dd914-8ec8-4a8b-8628-34672a5d449b

blue

silver

892a12ec-2028-4451-80aa-ff3bf55d6bac

The following form is deprecated since 4.2.1 and will be removed in the future:

<vnic_profile_mappings>
  <vnic_profile_mapping>
    <source_network_name>red</source_network_name>
    <source_network_profile_name>gold</source_network_profile_name>
    <target_vnic_profile id="738dd914-8ec8-4a8b-8628-34672a5d449b"/>
  </vnic_profile_mapping>
  <vnic_profile_mapping>
    <source_network_name>blue</source_network_name>
    <source_network_profile_name>silver</source_network_profile_name>
    <target_vnic_profile id="892a12ec-2028-4451-80aa-ff3bf55d6bac"/>
  </vnic_profile_mapping>
</vnic_profile_mappings>

Table 7.427. Attributes summary

NameTypeSummary

source_network_name

String

Deprecated attribute describing the name of the external network.

source_network_profile_name

String

Deprecated attribute describing the name of the external network profile.

7.328.1. source_network_name

Deprecated attribute describing the name of the external network.

Warning

Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future.

7.328.2. source_network_profile_name

Deprecated attribute describing the name of the external network profile.

Warning

Please note that this attribute has been deprecated since version 4.2.1 of the engine, and preserved only for backward compatibility. It will be removed in the future.

7.329. VolumeGroup struct

Table 7.429. Attributes summary

NameTypeSummary

id

String

 

logical_units

LogicalUnit[]

 

name

String

 

7.330. Watchdog struct

This type represents a watchdog configuration.

Table 7.430. Attributes summary

NameTypeSummary

action

WatchdogAction

Watchdog action to be performed when watchdog is triggered.

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

id

String

A unique identifier.

model

WatchdogModel

Model of watchdog device.

name

String

A human-readable name in plain text.

7.330.1. model

Model of watchdog device. Currently supported only I6300ESB.

7.331. WatchdogAction enum

This type describes available watchdog actions.

Table 7.432. Values summary

NameSummary

dump

Virtual machine process will get core dumped to the default path on the host.

none

No action will be performed when watchdog action is triggered.

pause

Virtual machine will be paused when watchdog action is triggered.

poweroff

Virtual machine will be powered off when watchdog action is triggered.

reset

Virtual machine will be rebooted when watchdog action is triggered.

7.331.1. none

No action will be performed when watchdog action is triggered. However log message will still be generated.

7.332. WatchdogModel enum

This type represents the watchdog model.

Table 7.433. Values summary

NameSummary

diag288

The watchdog model for S390X machines.

i6300esb

PCI based watchdog model.

7.332.1. diag288

The watchdog model for S390X machines.

S390X has an integrated watchdog facility that is controlled via the DIAG288 instruction. Use this model for S390X virtual machines.

7.332.2. i6300esb

PCI based watchdog model.

Use the I6300ESB watchdog for x86_64 and PPC64 virtual machines.

7.333. Weight struct

Table 7.434. Attributes summary

NameTypeSummary

comment

String

Free text containing comments about this object.

description

String

A human-readable description in plain text.

factor

Integer

 

id

String

A unique identifier.

name

String

A human-readable name in plain text.