Red Hat Training
A Red Hat training course is available for Red Hat Virtualization
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. |
