4.22. vm

The vm resource type groups all virtual machine resources in a Red Hat Virtualization environment.

Table 4.58. Virtual machine parameters

Name Type Description Required User Creatable User Updatable
--name
string
The name of the virtual machine
Yes
Yes
Yes
--template-id|name
string
A reference to the template used as the basis for the virtual machine.
Yes
Yes
No
--cluster-id|name
string
A reference to the cluster that includes this VM.
Yes
Yes
Yes
--instance_type-id|name
string
Defines the instance type. Specify custom, large, medium, small, tiny, or xlarge.
No
Yes
Yes
--quota-id
string
A reference to the quota usage for the virtual machine.
No
Yes
No
--timezone
string
The Sysprep time zone setting for a Windows virtual machine.
No
Yes
Yes
--os-boot
collection
The boot device for the virtual machine. Specify cdrom, hd, or network.
No
Yes
Yes
--custom_properties-custom_property
collection
A set of user-defined environment variables passed as parameters to custom scripts.
No
Yes
Yes
--os-type
string
The operating system type for this virtual machine.
No
Yes
Yes
--usb-enabled
boolean
Defines the USB policy for a virtual machine. Set to true to enable USB on the virtual machine.
No
Yes
Yes
--usb-type
string
Defines the USB type if enabled.
No
Yes
Yes
--type
string
Defines the virtual machine type. Specify either desktop or server.
No
Yes
Yes
--os-initRd
string
A path to an initrd image to be used with a specified kernel. This option supports booting a Linux kernel directly rather than through the BIOS bootloader.
No
Yes
Yes
--display-monitors
int
Defines the number of displays available.
No
Yes
Yes
--display-single_qxl_pci
boolean
Set to true to drive multiple monitors using a single virtual PCI device.
No
Yes
Yes
--display-type
string
Defines the display type. Specify either spice or vnc.
No
Yes
Yes
--display-allow_override
boolean
Set to true to allow override of the virtual machine console settings.
No
Yes
Yes
--display-smartcard_enabled
boolean
Set to true to enable the Smart card feature.
No
Yes
Yes
--display-file_transfer_enabled
boolean
Set to true to enable SPICE file transfer.
No
Yes
Yes
--display-copy_paste_enabled
boolean
Set to true to enable SPICE clipboard copy and paste.
No
Yes
Yes
--display-keyboard_layout
string
Defines the keyboard layout for the virtual machine. This option is only available when using the VNC protocol. Specify formats such as en-US.
No
Yes
Yes
--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.
No
Yes
Yes
--cpu-topology-cores
int
The number of CPU cores available to the virtual machine.
No
Yes
Yes
--cpu-architecture
string
Defines the CPU architecture. Specify x86_64, ppc64, or undefined.
No
Yes
Yes
--memory
long
The amount of memory for the virtual machine in bytes.
No
Yes
Yes
--memory_policy-guaranteed
long
The minimum amount of memory, in bytes, guaranteed on a host in order for the virtual machine to run.
No
Yes
Yes
--memory_policy-ballooning
boolean
Set to true to enable memory balloon device.
No
Yes
Yes
--high_availability-priority
int
Sets the priority value (migration and restart order) of each virtual machine using high availability.
No
Yes
Yes
--high_availability-enabled
boolean
Defines whether high availability is enabled for the virtual machine.
No
Yes
Yes
--domain-name
string
The domain name of the virtual machine.
No
Yes
Yes
--description
string
A description of the virtual machine.
No
Yes
Yes
--comment
string
A comment for the virtual machine.
No
Yes
Yes
--stateless
boolean
Set to true if the virtual machine is stateless. A stateless virtual machine contains a snapshot of its disk image taken at boot and removed at shutdown. This means state changes do not persist after a reboot.
No
Yes
Yes
--permissions-clone
boolean
Set to true to copy the permissions of the source virtual machine to the template.
No
Yes
Yes
--delete_protected
boolean
Set to true to make it impossible to delete a virtual machine created from this template.
No
Yes
Yes
--sso-methods-method
collection
Defines the single sign-on method used. For example, --sso-methods-method method.id=GUEST_AGENT.
No
Yes
Yes
--rng_device-rate-bytes
int
Specifies how many bytes are permitted to be consumed per period.
No
Yes
Yes
--rng_device-rate-period
int
Specifies the duration of a period in milliseconds. If specified, --rng_device-rate-bytes must be specified as well.
No
Yes
Yes
--rng_device-source
string
The source of the random number generator. Specify either random or hwrng.
No
Yes
Yes
--console-enabled
boolean
Set to true to enable the VirtIO console device feature.
No
Yes
Yes
--cpu-mode
string
Defines the CPU mode. Specify custom, host_model, or host_passthrough.
No
Yes
Yes
--cpu-topology-sockets
int
The number of CPU sockets available to the virtual machine.
No
Yes
Yes
--cpu_shares
int
The level of CPU resources a virtual machine can demand relative to other virtual machines. For example, 512 for low priority virtual machines, 1024 for medium priority virtual machines, and 2048 for high priority virtual machines.
No
Yes
Yes
--placement_policy-affinity
string
The migration affinity for each virtual machine. Specify migratable, user_migratable, or pinned.
No
Yes
Yes
--placement_policy-host-id|name
string
A reference to the preferred host for migration affinity.
No
Yes
Yes
--origin
string
The virtual machine's origin. Specify rhev, vmware, or xen.
No
Yes
Yes
--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.
No
Yes
Yes
--disks-clone
boolean
Defines whether to clone the disk from the defined template.
No
Yes
No
--disks-disk
collection
References to disks attached to the virtual machine.
No
Yes
Yes
--tunnel_migration
boolean
Set to true to enable data transport over a libvirt daemon. A tunneled transport uses a stronger encryption algorithm but increases the data load during transport.
No
Yes
Yes
--migration_downtime
int
Defines the maximum number of milliseconds that the virtual machine can be down during live migration.
No
Yes
Yes
--virtio_scsi-enabled
boolean
Set to true to allow attaching a VirtIO console device to the virtual machine.
No
Yes
Yes
--soundcard_enabled:
boolean
Set to true to enable sound cards.
No
Yes
Yes
--payloads-payload
collection
Defines content to send to the virtual machine upon booting.
No
Yes
Yes
--initialization-configuration-type
string
Defines the virtual machine format. Accepts only ovf.
No
Yes
Yes
--initialization-configuration-data
string
This parameter must match the --initialization-configuration-type parameter. Accepts only ovf.
No
Yes
Yes
--cpu-cpu_tune-vcpu_pin
collection
Defines which virtual CPUs of a virtual machine to pin to the physical CPUs of a host.
No
Yes
Yes
--serial_number-policy
string
Defines the serial number policy for the virtual machine template. Specify host, vm, or custom. If custom is used, also define the serial number value using --serial_number-value.
No
Yes
Yes
--serial_number-value
string
Defines the serial number for the virtual machine template.
No
Yes
Yes
--bios-boot_menu-enabled
boolean
Set to true to enable boot menu.
No
Yes
Yes
--numa_tune_mode
string
Defines how to allocate memory for the domain process on a NUMA host. Specify interleave, strict, or preferred. If no value is given, the parameter defaults to strict.
No
Yes
Yes
--cpu_profile-id
string
Defines the CPU profile to use. Use the list cpuprofiles command to retrieve a full list of CPU profile IDs.
No
Yes
Yes
--expect
'201-created'
Request becomes asynchronous until the expected HTTP header is returned. Useful for long-running tasks that would otherwise return as successful before the task is completed.
No
No
No
--correlation_id
string
A tagging identifier of an action for cross-system logging. If the client does not define the identifier, one will be generated.
No
Yes
No
The --os-boot parameter is a collection that uses the sub-parameters in the following table.

Table 4.59. --os-boot parameters

Name Type Description
boot.dev
string
The boot device for the virtual machine template. Specify cdrom, hd, or network.
The --custom_properties-custom_property parameter is a collection that uses the sub-parameters in the following table.

Table 4.60. --custom_properties-custom_property parameters

Name Type Description
custom_property.name
string
The custom property name.
custom_property.value
string
The custom property value.
The --sso-methods-method parameter is a collection that uses the sub-parameters in the following table.

Table 4.61. --sso-methods-method parameters

Name Type Description
method.id
string
The single sign-on method used: GUEST_AGENT.
The --disks-disk parameter is a collection that uses the sub-parameters in the following table.

Table 4.62. --disks-disk parameters

Name Type Description
disk.id
string
A reference to a virtual disk.
storage_domains.storage_domain
collection
Defines a set of sub-parameters for the disk's storage domain.
The --payloads-payload parameter is a collection that uses the sub-parameters in the following table.

Table 4.63. --payloads-payload parameters

Name Type Description
payload.type
string
Payload delivery type. Specify either cdrom or floppy.
payload.file.name
string
The payload file name and location on the root file system of the virtual machine.
payload.file.content
string
The content to deliver to the file.
The --cpu-cpu_tune-vcpu_pin parameter is a collection that uses the sub-parameters in the following table.

Table 4.64. --cpu-cpu_tune-vcpu_pin

Name Type Description
vcpu_pin.vcpu
int
The virtual CPU to assign.
vcpu_pin.cpu_set
string
The physical CPUs on the host.

Example 4.45. Creating a new virtual machine

[RHEVM shell (connected)]# add vm --name MyVM --template-name Blank --cluster-name Default --memory 536870912

Example 4.46. Updating a virtual machine

[RHEVM shell (connected)]# update vm MyVM --memory 1073741824

Example 4.47. Deleting a virtual machine

[RHEVM shell (connected)]# remove vm MyVM
The following table lists actions for a virtual machine resource.

Table 4.65. Virtual machine actions

Action Description
start Launch a virtual machine.
stop Stop a virtual machine.
shutdown Shut down a virtual machine.
suspend Suspend a virtual machine.
detach Detach a virtual machine from a pool.
migrate Migrate a virtual machine to another host.
cancelmigration Stop migration in progress.
export Export a virtual machine to an export storage domain.
move Move virtual disks to another storage domain.
ticket Create a ticket for console access.
logon Enable user logon for console access using third-party applications.