Chapter 15. Virtual Machines

15.1. Virtual Machine Elements

The vms collection provides information about virtual machines in a Red Hat Virtualization environment. An API user accesses this information through the rel="vms" link obtained from the entry point URI.
Additional information can be retrieved for GET requests using the All-Content: true header.
The following table shows specific elements contained in a virtual machine resource representation.

Table 15.1. Virtual machine elements

Element Type Description Properties
link rel="applications" relationship A link to the applications sub-collection for virtual machine resources, which shows the applications installed on the virtual machine.  
link rel="disks" relationship A link to the disks sub-collection for virtual machine resources.  
link rel="nics" relationship A link to the nics sub-collection for virtual machine resources.  
link rel="numanodes" relationship A link to the numanodes sub-collection for virtual machine resources.  
link rel="cdroms" relationship A link to the cdroms sub-collection for virtual machine resources.  
link rel="snapshots" relationship A link to the snapshots sub-collection for virtual machine resources.  
link rel="tags" relationship A link to the tags sub-collection for virtual machine resources.  
link rel="permissions" relationship A link to the permissions sub-collection for virtual machine permissions.  
link rel="statistics" relationship A link to the statistics sub-collection for virtual machine resources.
link rel="reporteddevices"
relationship
A link to the reporteddevices sub-collection for virtual machine resources.
 
link rel="watchdogs"
relationship
A link to the watchdogs sub-collection for virtual machine resources.
 
link rel="sessions"
relationship
A link to the sessions sub-collection for virtual machine resources.
 
type enumerated The virtual machine type. A list of enumerated values are available in capabilities.
status See below The virtual machine status.
memory integer The amount of memory allocated to the guest in bytes.
cpu complex
Defines CPU details for the virtual machine. The topology sub-element sets number of logical sockets available to the guest and the number of cores per socket. The total cores available to the virtual machine equals the number of sockets multiplied by the cores per socket.
The cputune sub-element maps virtual CPUs to physical host CPUs using a series of vcpupin elements. Each vcpupin elements contains a virtual CPU attribute (vcpu) and an attribute to define which physical to use (cpuset). Set the cpuset to either a single CPU (cpuset="0"), multiple CPUs (cpuset="0,2"), a CPU range (cpuset="0-3") or a CPU range with exclusion (cpuset="0-3,^2").
The cpu_mode sub-element defines how closely the virtual CPU relates to the host CPU. It has three values: custom is the default if no mode is given, host_model copies the host CPU as best as libvirt can understand, and host_passthrough passes all aspects of the host to the guest, even those that libvirt does not recognize. However, host_passthrough will prevent migration of that virtual machine.
os type= string, e.g. RHEL5 or WindowsXP The guest operating system type.
os boot dev= enumerated A list of boot devices described by a dev attribute on a boot element. A list of enumerated values are available in capabilities.
os kernel string A path to a kernel image the virtual machine is configured to boot. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
os initrd string A path to an initrd image to be used with the previously specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
os cmdline string A kernel command line parameter string to be used with the defined kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
high_availability complex Set enabled to true if the virtual machine should be automatically restarted if the virtual machine or its host crashes. A priority element controls the order in which virtual machines are re-started.  
display complex
The display type (either vnc or spice), port, and the number of monitors. The allow_reconnect Boolean value specifies if a client can reconnect to the machine via display.
The smartcard_enabled sub-element is a Boolean (true or false) to specify if a Smartcard attached to a client is passed through to a virtual machine. The default is false.
 
cluster id= GUID A reference to the virtual machine's host cluster.
template id= GUID A reference to the template on which this virtual machine is based.
domain id= GUID A reference to the virtual machine's domain.
start_time xsd:dateTime format: YYYY-MM-DDThh:mm:ss The date and time at which this virtual machine was started.
stop_time xsd:dateTime format: YYYY-MM-DDThh:mm:ss The date and time at which this virtual machine was stopped.
creation_time xsd:dateTime format: YYYY-MM-DDThh:mm:ss The date and time at which this virtual machine was created.
origin One of rhev, ovirt, vmware or xen The system from which this virtual machine originated.
stateless Boolean: true or false true if the virtual machine is stateless. A stateless virtual machine contains a snapshot of its disk image taken at boot and deleted at shutdown. This means state changes do not persist after a reboot.  
delete_protected Boolean: true or false If set to true, the virtual machine cannot be deleted.  
sso string A reference to the method of single sign-on for the virtual machine. Includes a method element with an ip attribute.  
placement_policy complex Sets the placement policy for virtual machine migration. Requires a default host= and an affinity (one of migratable, user_migratable or pinned). Leave the host element empty to set no preferred host. Use multiple host elements to specify a subset of preferred hosts within a cluster.  
memory_policy complex Sets the memory policy for virtual machines. Defines the minimum amount of guaranteed memory on a host in order for the virtual machine to run.  
quota id= GUID Sets a quota for the virtual machine.  
custom_properties complex A set of user-defined environment variable passed as parameters to custom scripts. Each custom_property contains name and value attributes. A list of enumerated values are available in capabilities.  
usb complex Defines the USB policy for a virtual machine. Requires an enabled element set to a Boolean value and a type element set to either native or legacy.

Important

The Legacy USB option has been deprecated and will be removed in Red Hat Virtualization 4.1.
 
migration_downtime integer Represents the maximum number of milliseconds the virtual machine can be down during live migration. A value of 0 means that the VDSM default will be used.  
cpu_profile id= GUID A reference to the virtual machine's cpu profile.  
next_run_configuration Boolean: true or false true if changes to the virtual machine's configuration will be applied when the virtual machine is next restarted.  
numa_tune_mode string Reference to the mode of memory allocation (interleave, strict, or preferred) of the host NUMA node.  
guest_info complex A reference to the guest client information. Includes an ip element with an address= attribute.
vmpool complex A reference to the virtual machine pool. This element only appears for virtual machines part of a pool.
timezone tz database format: Area/Location The Sysprep timezone setting for a Windows virtual machine.  
domain complex The Sysprep domain setting for a Windows virtual machine. Requires a name from the domains collection.  
initialization complex
Defines a list of values applied to the virtual machine on boot using Cloud-Init for Linux-based virtual machines, or Sysprep for Windows-based virtual machines.

Cloud-Init

  • host_name: The host name of the virtual machine.
  • timezone: The time zone for the virtual machine.
  • user_name: The user name for the virtual machine.
  • root_password: The password for the user, or root password if no user is specified.
  • authorized_ssh_keys: SSH keys to be added to the authorized keys file of the virtual machine. You can enter multiple SSH keys by separating each SSH key with a line break.
  • regenerate_ssh_keys: Whether to regenerate SSH key for the virtual machine. Possible values are true or false.
  • dns_servers: A space-separated list of DNS servers.
  • dns_search: A space-separated list of DNS search domains.
  • nic_configurations: Defines a network interface controller for the virtual machine. Network interface controllers are defined as nic_configuration objects under this collection that each specify the name, ip, boot_protocol, and on_boot.
  • custom_script: A custom script to run on the virtual machine when it starts.

Sysprep

  • host_name: The host name of the virtual machine.
  • domain: The domain of which the virtual machine is a member.
  • authorized_ssh_keys: SSH keys to be added to the authorized keys file of the virtual machine. You can enter multiple SSH keys by separating each SSH key with a line break.
  • regenerate_ssh_keys: Whether to regenerate SSH key for the virtual machine. Possible values are true or false.
  • timezone: The time zone for the virtual machine.
  • root_password: The password for the admin user of the virtual machine.
  • custom_script: A custom script to run on the virtual machine when it starts.
  • input_locale: The locale for user input.
  • ui_language: The language used for user interface elements such as buttons and menus.
  • system_locale: The locale for the overall system.
  • user_locale: The locale for users.
  • active_directory_ou: The organizational unit in the Active Directory domain to which the virtual machine belongs.
  • org_name: The name of the organization to which the virtual machine belongs.
payloads complex
Defines a set of payload elements to deliver content to a virtual machine upon boot. Each payload requires a type attribute, either cdrom or floppy, and a set of file elements. Within each file element is a name element that specifies the name and location of the file, and a content element that defines the content to deliver to the file.
The payloads element is used by the cloud-init feature. When cloud-init is used to configure a virtual machine, a payload is automatically created with the type attribute set to cd-rom and two file sub-elements, openstack/latest/meta_data.json and openstack/latest/user_data, which pass configuration parameters to the virtual machine.
 
The status contains one of the following enumerative values: unassigned, down, up, powering_up, powered_down, paused, migrating_from, migrating_to, unknown, not_responding, wait_for_launch, reboot_in_progress, saving_state, restoring_state, suspended, image_illegal, image_locked or powering_down. These states are listed in vm_states under capabilities.