Develop for XenServer

Class: VM

A virtual machine (or ‘guest’).

Fields for class: VM

Field Type Qualifier Description
actions_after_crash on_crash_behaviour RO/constructor action to take if the guest crashes
actions_after_reboot on_normal_exit RW action to take after the guest has rebooted itself
actions_after_shutdown on_normal_exit RW action to take after the guest has shutdown itself
actions_after_softreboot on_softreboot_behavior RW action to take after soft reboot
affinity host ref RW A host which the VM has some affinity for (or NULL). This is used as a hint to the start call when it decides where to run the VM. Resource constraints may cause the VM to be started elsewhere.
allowed_operations vm_operations set RO/runtime list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client.
appliance VM_appliance ref RO/constructor the appliance to which this VM belongs
attached_PCIs PCI ref set RO/runtime Currently passed-through PCI devices
bios_strings (string -> string) map RO/runtime BIOS strings
blobs (string -> blob ref) map RO/runtime Binary blobs associated with this VM
blocked_operations (vm_operations -> string) map RW List of operations which have been explicitly blocked and an error code
children VM ref set RO/runtime List pointing to all the children of this VM
consoles console ref set RO/runtime virtual console devices
crash_dumps crashdump ref set RO/runtime crash dumps associated with this VM
current_operations (string -> vm_operations) map RO/runtime links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
domain_type domain_type RO/constructor The type of domain that will be created when the VM is started
domarch string RO/runtime Domain architecture (if available, null string otherwise)
domid int RO/runtime domain ID (if available, -1 otherwise)
generation_id string RO/constructor Generation ID of the VM
guest_metrics VM_guest_metrics ref RO/runtime metrics associated with the running guest
ha_always_run bool RO/constructor Deprecated. if true then the system will attempt to keep the VM running as much as possible.
ha_restart_priority string RO/constructor has possible values: “best-effort” meaning “try to restart this VM if possible but don’t consider the Pool to be overcommitted if this is not possible”; “restart” meaning “this VM should be restarted”; “” meaning “do not try to restart this VM”
hardware_platform_version int RW The host virtual hardware platform version the VM can run on
has_vendor_device bool RO/constructor When an HVM guest starts, this controls the presence of the emulated C000 PCI device which triggers Windows Update to fetch or update PV drivers.
HVM_boot_params (string -> string) map RW HVM boot params
HVM_boot_policy string RO/constructor Deprecated. HVM boot policy
HVM_shadow_multiplier float RO/constructor multiplier applied to the amount of shadow that will be made available to the guest
is_a_snapshot bool RO/runtime true if this is a snapshot. Snapshotted VMs can never be started, they are used only for cloning other VMs
is_a_template bool RW true if this is a template. Template VMs can never be started, they are used only for cloning other VMs
is_control_domain bool RO/runtime true if this is a control domain (domain 0 or a driver domain)
is_default_template bool RO/runtime true if this is a default template. Default template VMs can never be started or migrated, they are used only for cloning other VMs
is_snapshot_from_vmpp bool RO/constructor Removed. true if this snapshot was created by the protection policy
is_vmss_snapshot bool RO/constructor true if this snapshot was created by the snapshot schedule
last_boot_CPU_flags (string -> string) map RO/constructor describes the CPU flags on which the VM was last booted
last_booted_record string RO/constructor marshalled value containing VM record at time of last boot
memory_dynamic_max int RO/constructor Dynamic maximum (bytes)
memory_dynamic_min int RO/constructor Dynamic minimum (bytes)
memory_overhead int RO/runtime Virtualization memory overhead (bytes).
memory_static_max int RO/constructor Statically-set (i.e. absolute) maximum (bytes). The value of this field at VM start time acts as a hard limit of the amount of memory a guest can use. New values only take effect on reboot.
memory_static_min int RO/constructor Statically-set (i.e. absolute) mininum (bytes). The value of this field indicates the least amount of memory this VM can boot with without crashing.
memory_target int RO/constructor Deprecated. Dynamically-set memory target (bytes). The value of this field indicates the current target for memory available to this VM.
metrics VM_metrics ref RO/runtime metrics associated with this VM
name_description string RW a notes field containing human-readable description
name_label string RW a human-readable name
NVRAM (string -> string) map RO/constructor initial value for guest NVRAM (containing UEFI variables, etc). Cannot be changed while the VM is running
order int RO/constructor The point in the startup or shutdown sequence at which this VM will be started
other_config (string -> string) map RW additional configuration
parent VM ref RO/runtime Ref pointing to the parent of this VM
PCI_bus string RW Deprecated. PCI bus path for pass-through devices
pending_guidances update_guidances set RO/runtime The set of pending mandatory guidances after applying updates, which must be applied, as otherwise there may be e.g. VM failures
pending_guidances_full update_guidances set RO/runtime The set of pending full guidances after applying updates, which a user should follow to make some updates, e.g. specific hardware drivers or CPU features, fully effective, but the ‘average user’ doesn’t need to
pending_guidances_recommended update_guidances set RO/runtime The set of pending recommended guidances after applying updates, which most users should follow to make the updates effective, but if not followed, will not cause a failure
platform (string -> string) map RW platform-specific configuration
power_state vm_power_state RO/constructor Current power state of the machine
protection_policy VMPP ref RO/constructor Deprecated. Ref pointing to a protection policy for this VM
PV_args string RW kernel command-line arguments
PV_bootloader string RW name of or path to bootloader
PV_bootloader_args string RW miscellaneous arguments for the bootloader
PV_kernel string RW path to the kernel
PV_legacy_args string RW to make Zurich guests boot
PV_ramdisk string RW path to the initrd
recommendations string RW An XML specification of recommended values and ranges for properties of this VM
reference_label string RO/constructor Textual reference to the template used to create a VM. This can be used by clients in need of an immutable reference to the template since the latter’s uuid and name_label may change, for example, after a package installation or upgrade.
requires_reboot bool RO/runtime Indicates whether a VM requires a reboot in order to update its configuration, e.g. its memory allocation.
resident_on host ref RO/runtime the host the VM is currently resident on
scheduled_to_be_resident_on host ref RO/runtime the host on which the VM is due to be started/resumed/migrated. This acts as a memory reservation indicator
shutdown_delay int RO/constructor The delay to wait before proceeding to the next order in the shutdown sequence (seconds)
snapshot_info (string -> string) map RO/runtime Human-readable information concerning this snapshot
snapshot_metadata string RO/runtime Encoded information about the VM’s metadata this is a snapshot of
snapshot_of VM ref RO/runtime Ref pointing to the VM this snapshot is of.
snapshot_schedule VMSS ref RO/constructor Ref pointing to a snapshot schedule for this VM
snapshot_time datetime RO/runtime Date/time when this snapshot was created.
snapshots VM ref set RO/runtime List pointing to all the VM snapshots.
start_delay int RO/constructor The delay to wait before proceeding to the next order in the startup sequence (seconds)
suspend_SR SR ref RW The SR on which a suspend image is stored
suspend_VDI VDI ref RO/constructor The VDI that a suspend image is stored on. (Only has meaning if VM is currently suspended)
tags string set RW user-specified tags for categorization purposes
transportable_snapshot_id string RO/runtime Transportable ID of the snapshot VM
user_version int RW Creators of VMs and templates may store version information here.
uuid string RO/runtime Unique identifier/object reference
VBDs VBD ref set RO/runtime virtual block devices
VCPUs_at_startup int RO/constructor Boot number of VCPUs
VCPUs_max int RO/constructor Max number of VCPUs
VCPUs_params (string -> string) map RW configuration parameters for the selected VCPU policy
version int RO/constructor The number of times this VM has been recovered
VGPUs VGPU ref set RO/runtime Virtual GPUs
VIFs VIF ref set RO/runtime virtual network interfaces
VTPMs VTPM ref set RO/runtime virtual TPMs
VUSBs VUSB ref set RO/runtime virtual usb devices
xenstore_data (string -> string) map RW data to be inserted into the xenstore tree (/local/domain//vm-data) after the VM is created.

RPCs associated with class: VM

RPC name: add_tags

Overview:

Add the given value to the tags field of the given VM. If the value is already in that Set, then do nothing.

Signature:

void add_tags (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to add

Minimum Role: vm-operator

Return Type: void

RPC name: add_to_blocked_operations

Overview:

Add the given key-value pair to the blocked_operations field of the given VM.

Signature:

void add_to_blocked_operations (session ref session_ref, VM ref self, vm_operations key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
vm_operations key Key to add
string value Value to add

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_HVM_boot_params

Overview:

Add the given key-value pair to the HVM/boot_params field of the given VM.

Signature:

void add_to_HVM_boot_params (session ref session_ref, VM ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to add
string value Value to add

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_NVRAM

Overview:

Signature:

void add_to_NVRAM (session ref session_ref, VM ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string key The key
string value The value

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_other_config

Overview:

Add the given key-value pair to the other_config field of the given VM.

Signature:

void add_to_other_config (session ref session_ref, VM ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to add
string value Value to add

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_platform

Overview:

Add the given key-value pair to the platform field of the given VM.

Signature:

void add_to_platform (session ref session_ref, VM ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to add
string value Value to add

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_VCPUs_params

Overview:

Add the given key-value pair to the VCPUs/params field of the given VM.

Signature:

void add_to_VCPUs_params (session ref session_ref, VM ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to add
string value Value to add

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_VCPUs_params_live

Overview:

Add the given key-value pair to VM.VCPUs_params, and apply that value on the running VM

Signature:

void add_to_VCPUs_params_live (session ref session_ref, VM ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string key The key
string value The value

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_xenstore_data

Overview:

Add the given key-value pair to the xenstore_data field of the given VM.

Signature:

void add_to_xenstore_data (session ref session_ref, VM ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to add
string value Value to add

Minimum Role: vm-admin

Return Type: void

RPC name: assert_agile

Overview:

Returns an error if the VM is not considered agile e.g. because it is tied to a resource local to a host

Signature:

void assert_agile (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM

Minimum Role: read-only

Return Type: void

RPC name: assert_can_be_recovered

Overview:

Assert whether all SRs required to recover this VM are available.

Signature:

void assert_can_be_recovered (session ref session_ref, VM ref self, session ref session_to)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to recover
session ref session_to The session to which the VM is to be recovered.

Minimum Role: read-only

Return Type: void

Possible Error Codes: VM_IS_PART_OF_AN_APPLIANCE, VM_REQUIRES_SR

RPC name: assert_can_boot_here

Overview:

Returns an error if the VM could not boot on this host for some reason

Signature:

void assert_can_boot_here (session ref session_ref, VM ref self, host ref host)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
host ref host The host

Minimum Role: read-only

Return Type: void

Possible Error Codes: HOST_NOT_ENOUGH_FREE_MEMORY, HOST_NOT_ENOUGH_PCPUS, NETWORK_SRIOV_INSUFFICIENT_CAPACITY, HOST_NOT_LIVE, HOST_DISABLED, HOST_CANNOT_ATTACH_NETWORK, VM_HVM_REQUIRED, VM_REQUIRES_GPU, VM_REQUIRES_IOMMU, VM_REQUIRES_NETWORK, VM_REQUIRES_SR, VM_REQUIRES_VGPU, VM_HOST_INCOMPATIBLE_VERSION, VM_HOST_INCOMPATIBLE_VIRTUAL_HARDWARE_PLATFORM_VERSION, INVALID_VALUE, MEMORY_CONSTRAINT_VIOLATION, OPERATION_NOT_ALLOWED, VALUE_NOT_SUPPORTED, VM_INCOMPATIBLE_WITH_THIS_HOST

RPC name: assert_can_migrate

Overview:

Assert whether a VM can be migrated to the specified destination.

Signature:

void assert_can_migrate (session ref session_ref, VM ref vm, (string -> string) map dest, bool live, (VDI ref -> SR ref) map vdi_map, (VIF ref -> network ref) map vif_map, (string -> string) map options, (VGPU ref -> GPU_group ref) map vgpu_map)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM
(string -> string) map dest The result of a VM.migrate_receive call.
bool live Live migration
(VDI ref -> SR ref) map vdi_map Map of source VDI to destination SR
(VIF ref -> network ref) map vif_map Map of source VIF to destination network
(string -> string) map options Other parameters
(VGPU ref -> GPU_group ref) map vgpu_map Map of source vGPU to destination GPU group

Minimum Role: vm-power-admin

Return Type: void

Possible Error Codes: LICENCE_RESTRICTION

RPC name: assert_operation_valid

Overview:

Check to see whether this operation is acceptable in the current state of the system, raising an error if the operation is invalid for some reason

Signature:

void assert_operation_valid (session ref session_ref, VM ref self, vm_operations op)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
vm_operations op proposed operation

Minimum Role: read-only

Return Type: void

RPC name: call_plugin

Overview:

Call an API plugin on this vm

Signature:

string call_plugin (session ref session_ref, VM ref vm, string plugin, string fn, (string -> string) map args)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The vm
string plugin The name of the plugin
string fn The name of the function within the plugin
(string -> string) map args Arguments for the function

Minimum Role: vm-operator

Return Type: string

Result from the plugin

RPC name: checkpoint

Overview:

Checkpoints the specified VM, making a new VM. Checkpoint automatically exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored (e.g. Copy on Write) and saves the memory image as well.

Signature:

VM ref checkpoint (session ref session_ref, VM ref vm, string new_name)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to be checkpointed
string new_name The name of the checkpointed VM

Minimum Role: vm-power-admin

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED, VM_CHECKPOINT_SUSPEND_FAILED, VM_CHECKPOINT_RESUME_FAILED

RPC name: clean_reboot

Overview:

Attempt to cleanly shutdown the specified VM (Note: this may not be supported---e.g. if a guest agent is not installed). This can only be called when the specified VM is in the Running state.

Signature:

void clean_reboot (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to shutdown

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: clean_shutdown

Overview:

Attempt to cleanly shutdown the specified VM. (Note: this may not be supported---e.g. if a guest agent is not installed). This can only be called when the specified VM is in the Running state.

Signature:

void clean_shutdown (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to shutdown

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: clone

Overview:

Clones the specified VM, making a new VM. Clone automatically exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored (e.g. Copy on Write). This function can only be called when the VM is in the Halted State.

Signature:

VM ref clone (session ref session_ref, VM ref vm, string new_name)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to be cloned
string new_name The name of the cloned VM

Minimum Role: vm-admin

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED, LICENCE_RESTRICTION

RPC name: compute_memory_overhead

Overview:

Computes the virtualization memory overhead of a VM.

Signature:

int compute_memory_overhead (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM for which to compute the memory overhead

Minimum Role: read-only

Return Type: int

the virtualization memory overhead of the VM.

RPC name: copy

Overview:

Copied the specified VM, making a new VM. Unlike clone, copy does not exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored. Instead, copy guarantees that the disk images of the newly created VM will be ‘full disks’ - i.e. not part of a CoW chain. This function can only be called when the VM is in the Halted State.

Signature:

VM ref copy (session ref session_ref, VM ref vm, string new_name, SR ref sr)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to be copied
string new_name The name of the copied VM
SR ref sr An SR to copy all the VM’s disks into (if an invalid reference then it uses the existing SRs)

Minimum Role: vm-admin

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED, LICENCE_RESTRICTION

RPC name: copy_bios_strings

Overview:

Copy the BIOS strings from the given host to this VM

Signature:

void copy_bios_strings (session ref session_ref, VM ref vm, host ref host)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to modify
host ref host The host to copy the BIOS strings from

Minimum Role: vm-admin

Return Type: void

RPC name: create

Overview:

NOT RECOMMENDED! VM.clone or VM.copy (or VM.import) is a better choice in almost all situations. The standard way to obtain a new VM is to call VM.clone on a template VM, then call VM.provision on the new clone. Caution: if VM.create is used and then the new VM is attached to a virtual disc that has an operating system already installed, then there is no guarantee that the operating system will boot and run. Any software that calls VM.create on a future version of this API may fail or give unexpected results. For example this could happen if an additional parameter were added to VM.create. VM.create is intended only for use in the automatic creation of the system VM templates. It creates a new VM instance, and returns its handle.

Signature:

VM ref create (session ref session_ref, VM record args)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM record args All constructor arguments

Minimum Role: vm-admin

Return Type: VM ref

reference to the newly created object

RPC name: create_new_blob

Overview:

Create a placeholder for a named binary blob of data that is associated with this VM

Signature:

blob ref create_new_blob (session ref session_ref, VM ref vm, string name, string mime_type, bool public)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM
string name The name associated with the blob
string mime_type The mime type for the data. Empty string translates to application/octet-stream
bool public True if the blob should be publicly available

Minimum Role: vm-power-admin

Return Type: blob ref

The reference of the blob, needed for populating its data

RPC name: destroy

Overview:

Destroy the specified VM. The VM is completely removed from the system. This function can only be called when the VM is in the Halted State.

Signature:

void destroy (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: vm-admin

Return Type: void

RPC name: forget_data_source_archives

Overview:

Forget the recorded statistics related to the specified data source

Signature:

void forget_data_source_archives (session ref session_ref, VM ref self, string data_source)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string data_source The data source whose archives are to be forgotten

Minimum Role: vm-admin

Return Type: void

RPC name: get_actions_after_crash

Overview:

Get the actions/after_crash field of the given VM.

Signature:

on_crash_behaviour get_actions_after_crash (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: on_crash_behaviour

value of the field

RPC name: get_actions_after_reboot

Overview:

Get the actions/after_reboot field of the given VM.

Signature:

on_normal_exit get_actions_after_reboot (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: on_normal_exit

value of the field

RPC name: get_actions_after_shutdown

Overview:

Get the actions/after_shutdown field of the given VM.

Signature:

on_normal_exit get_actions_after_shutdown (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: on_normal_exit

value of the field

RPC name: get_actions_after_softreboot

Overview:

Get the actions/after_softreboot field of the given VM.

Signature:

on_softreboot_behavior get_actions_after_softreboot (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: on_softreboot_behavior

value of the field

RPC name: get_affinity

Overview:

Get the affinity field of the given VM.

Signature:

host ref get_affinity (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: host ref

value of the field

RPC name: get_all

Overview:

Return a list of all the VMs known to the system.

Signature:

VM ref set get_all (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: read-only

Return Type: VM ref set

references to all objects

RPC name: get_all_records

Overview:

Return a map of VM references to VM records for all VMs known to the system.

Signature:

(VM ref -> VM record) map get_all_records (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: read-only

Return Type: (VM ref -> VM record) map

records of all objects

RPC name: get_allowed_operations

Overview:

Get the allowed_operations field of the given VM.

Signature:

vm_operations set get_allowed_operations (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: vm_operations set

value of the field

RPC name: get_allowed_VBD_devices

Overview:

Returns a list of the allowed values that a VBD device field can take

Signature:

string set get_allowed_VBD_devices (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to query

Minimum Role: read-only

Return Type: string set

The allowed values

RPC name: get_allowed_VIF_devices

Overview:

Returns a list of the allowed values that a VIF device field can take

Signature:

string set get_allowed_VIF_devices (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to query

Minimum Role: read-only

Return Type: string set

The allowed values

RPC name: get_appliance

Overview:

Get the appliance field of the given VM.

Signature:

VM_appliance ref get_appliance (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VM_appliance ref

value of the field

RPC name: get_attached_PCIs

Overview:

Get the attached_PCIs field of the given VM.

Signature:

PCI ref set get_attached_PCIs (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: PCI ref set

value of the field

RPC name: get_bios_strings

Overview:

Get the bios_strings field of the given VM.

Signature:

(string -> string) map get_bios_strings (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_blobs

Overview:

Get the blobs field of the given VM.

Signature:

(string -> blob ref) map get_blobs (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> blob ref) map

value of the field

RPC name: get_blocked_operations

Overview:

Get the blocked_operations field of the given VM.

Signature:

(vm_operations -> string) map get_blocked_operations (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (vm_operations -> string) map

value of the field

RPC name: get_boot_record

This message is deprecated.

Overview:

Returns a record describing the VM’s dynamic state, initialised when the VM boots and updated to reflect runtime configuration changes e.g. CPU hotplug

Signature:

VM record get_boot_record (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM whose boot-time state to return

Minimum Role: read-only

Return Type: VM record

A record describing the VM

RPC name: get_by_name_label

Overview:

Get all the VM instances with the given label.

Signature:

VM ref set get_by_name_label (session ref session_ref, string label)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string label label of object to return

Minimum Role: read-only

Return Type: VM ref set

references to objects with matching names

RPC name: get_by_uuid

Overview:

Get a reference to the VM instance with the specified UUID.

Signature:

VM ref get_by_uuid (session ref session_ref, string uuid)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return

Minimum Role: read-only

Return Type: VM ref

reference to the object

RPC name: get_children

Overview:

Get the children field of the given VM.

Signature:

VM ref set get_children (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VM ref set

value of the field

RPC name: get_consoles

Overview:

Get the consoles field of the given VM.

Signature:

console ref set get_consoles (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: console ref set

value of the field

RPC name: get_cooperative

This message is deprecated.

Overview:

Return true if the VM is currently ‘co-operative’ i.e. is expected to reach a balloon target and actually has done

Signature:

bool get_cooperative (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM

Minimum Role: read-only

Return Type: bool

true if the VM is currently ‘co-operative’; false otherwise

RPC name: get_crash_dumps

Overview:

Get the crash_dumps field of the given VM.

Signature:

crashdump ref set get_crash_dumps (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: crashdump ref set

value of the field

RPC name: get_current_operations

Overview:

Get the current_operations field of the given VM.

Signature:

(string -> vm_operations) map get_current_operations (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> vm_operations) map

value of the field

RPC name: get_data_sources

Overview:

Signature:

data_source record set get_data_sources (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to interrogate

Minimum Role: read-only

Return Type: data_source record set

A set of data sources

RPC name: get_domain_type

Overview:

Get the domain_type field of the given VM.

Signature:

domain_type get_domain_type (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: domain_type

value of the field

RPC name: get_domarch

Overview:

Get the domarch field of the given VM.

Signature:

string get_domarch (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_domid

Overview:

Get the domid field of the given VM.

Signature:

int get_domid (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_generation_id

Overview:

Get the generation_id field of the given VM.

Signature:

string get_generation_id (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_guest_metrics

Overview:

Get the guest_metrics field of the given VM.

Signature:

VM_guest_metrics ref get_guest_metrics (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VM_guest_metrics ref

value of the field

RPC name: get_ha_always_run

This message is deprecated.

Overview:

Get the ha_always_run field of the given VM.

Signature:

bool get_ha_always_run (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_ha_restart_priority

Overview:

Get the ha_restart_priority field of the given VM.

Signature:

string get_ha_restart_priority (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_hardware_platform_version

Overview:

Get the hardware_platform_version field of the given VM.

Signature:

int get_hardware_platform_version (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_has_vendor_device

Overview:

Get the has_vendor_device field of the given VM.

Signature:

bool get_has_vendor_device (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_HVM_boot_params

Overview:

Get the HVM/boot_params field of the given VM.

Signature:

(string -> string) map get_HVM_boot_params (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_HVM_boot_policy

This message is deprecated.

Overview:

Get the HVM/boot_policy field of the given VM.

Signature:

string get_HVM_boot_policy (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_HVM_shadow_multiplier

Overview:

Get the HVM/shadow_multiplier field of the given VM.

Signature:

float get_HVM_shadow_multiplier (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: float

value of the field

RPC name: get_is_a_snapshot

Overview:

Get the is_a_snapshot field of the given VM.

Signature:

bool get_is_a_snapshot (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_a_template

Overview:

Get the is_a_template field of the given VM.

Signature:

bool get_is_a_template (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_control_domain

Overview:

Get the is_control_domain field of the given VM.

Signature:

bool get_is_control_domain (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_default_template

Overview:

Get the is_default_template field of the given VM.

Signature:

bool get_is_default_template (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_snapshot_from_vmpp

This message is removed.

Overview:

Get the is_snapshot_from_vmpp field of the given VM.

Signature:

bool get_is_snapshot_from_vmpp (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_vmss_snapshot

Overview:

Get the is_vmss_snapshot field of the given VM.

Signature:

bool get_is_vmss_snapshot (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_last_boot_CPU_flags

Overview:

Get the last_boot_CPU_flags field of the given VM.

Signature:

(string -> string) map get_last_boot_CPU_flags (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_last_booted_record

Overview:

Get the last_booted_record field of the given VM.

Signature:

string get_last_booted_record (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_memory_dynamic_max

Overview:

Get the memory/dynamic_max field of the given VM.

Signature:

int get_memory_dynamic_max (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_dynamic_min

Overview:

Get the memory/dynamic_min field of the given VM.

Signature:

int get_memory_dynamic_min (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_overhead

Overview:

Get the memory/overhead field of the given VM.

Signature:

int get_memory_overhead (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_static_max

Overview:

Get the memory/static_max field of the given VM.

Signature:

int get_memory_static_max (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_static_min

Overview:

Get the memory/static_min field of the given VM.

Signature:

int get_memory_static_min (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_target

This message is deprecated.

Overview:

Get the memory/target field of the given VM.

Signature:

int get_memory_target (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_metrics

Overview:

Get the metrics field of the given VM.

Signature:

VM_metrics ref get_metrics (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VM_metrics ref

value of the field

RPC name: get_name_description

Overview:

Get the name/description field of the given VM.

Signature:

string get_name_description (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_name_label

Overview:

Get the name/label field of the given VM.

Signature:

string get_name_label (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_NVRAM

Overview:

Get the NVRAM field of the given VM.

Signature:

(string -> string) map get_NVRAM (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_order

Overview:

Get the order field of the given VM.

Signature:

int get_order (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_other_config

Overview:

Get the other_config field of the given VM.

Signature:

(string -> string) map get_other_config (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_parent

Overview:

Get the parent field of the given VM.

Signature:

VM ref get_parent (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VM ref

value of the field

RPC name: get_PCI_bus

This message is deprecated.

Overview:

Get the PCI_bus field of the given VM.

Signature:

string get_PCI_bus (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_pending_guidances

Overview:

Get the pending_guidances field of the given VM.

Signature:

update_guidances set get_pending_guidances (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: update_guidances set

value of the field

RPC name: get_pending_guidances_full

Overview:

Get the pending_guidances_full field of the given VM.

Signature:

update_guidances set get_pending_guidances_full (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: update_guidances set

value of the field

Overview:

Get the pending_guidances_recommended field of the given VM.

Signature:

update_guidances set get_pending_guidances_recommended (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: update_guidances set

value of the field

RPC name: get_platform

Overview:

Get the platform field of the given VM.

Signature:

(string -> string) map get_platform (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_possible_hosts

Overview:

Return the list of hosts on which this VM may run.

Signature:

host ref set get_possible_hosts (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM

Minimum Role: read-only

Return Type: host ref set

The possible hosts

RPC name: get_power_state

Overview:

Get the power_state field of the given VM.

Signature:

vm_power_state get_power_state (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: vm_power_state

value of the field

RPC name: get_protection_policy

This message is deprecated.

Overview:

Get the protection_policy field of the given VM.

Signature:

VMPP ref get_protection_policy (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VMPP ref

value of the field

RPC name: get_PV_args

Overview:

Get the PV/args field of the given VM.

Signature:

string get_PV_args (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_bootloader

Overview:

Get the PV/bootloader field of the given VM.

Signature:

string get_PV_bootloader (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_bootloader_args

Overview:

Get the PV/bootloader_args field of the given VM.

Signature:

string get_PV_bootloader_args (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_kernel

Overview:

Get the PV/kernel field of the given VM.

Signature:

string get_PV_kernel (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_legacy_args

Overview:

Get the PV/legacy_args field of the given VM.

Signature:

string get_PV_legacy_args (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_ramdisk

Overview:

Get the PV/ramdisk field of the given VM.

Signature:

string get_PV_ramdisk (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_recommendations

Overview:

Get the recommendations field of the given VM.

Signature:

string get_recommendations (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_record

Overview:

Get a record containing the current state of the given VM.

Signature:

VM record get_record (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VM record

all fields from the object

RPC name: get_reference_label

Overview:

Get the reference_label field of the given VM.

Signature:

string get_reference_label (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_requires_reboot

Overview:

Get the requires_reboot field of the given VM.

Signature:

bool get_requires_reboot (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_resident_on

Overview:

Get the resident_on field of the given VM.

Signature:

host ref get_resident_on (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: host ref

value of the field

RPC name: get_scheduled_to_be_resident_on

Overview:

Get the scheduled_to_be_resident_on field of the given VM.

Signature:

host ref get_scheduled_to_be_resident_on (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: host ref

value of the field

RPC name: get_secureboot_readiness

Overview:

Return the secureboot readiness of the VM

Signature:

vm_secureboot_readiness get_secureboot_readiness (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM

Minimum Role: pool-admin

Return Type: vm_secureboot_readiness

The secureboot readiness of the VM

RPC name: get_shutdown_delay

Overview:

Get the shutdown_delay field of the given VM.

Signature:

int get_shutdown_delay (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_snapshot_info

Overview:

Get the snapshot_info field of the given VM.

Signature:

(string -> string) map get_snapshot_info (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_snapshot_metadata

Overview:

Get the snapshot_metadata field of the given VM.

Signature:

string get_snapshot_metadata (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_snapshot_of

Overview:

Get the snapshot_of field of the given VM.

Signature:

VM ref get_snapshot_of (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VM ref

value of the field

RPC name: get_snapshot_schedule

Overview:

Get the snapshot_schedule field of the given VM.

Signature:

VMSS ref get_snapshot_schedule (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VMSS ref

value of the field

RPC name: get_snapshot_time

Overview:

Get the snapshot_time field of the given VM.

Signature:

datetime get_snapshot_time (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: datetime

value of the field

RPC name: get_snapshots

Overview:

Get the snapshots field of the given VM.

Signature:

VM ref set get_snapshots (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VM ref set

value of the field

RPC name: get_SRs_required_for_recovery

Overview:

List all the SR’s that are required for the VM to be recovered

Signature:

SR ref set get_SRs_required_for_recovery (session ref session_ref, VM ref self, session ref session_to)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM for which the SRs have to be recovered
session ref session_to The session to which the SRs of the VM have to be recovered.

Minimum Role: read-only

Return Type: SR ref set

refs for SRs required to recover the VM

RPC name: get_start_delay

Overview:

Get the start_delay field of the given VM.

Signature:

int get_start_delay (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_suspend_SR

Overview:

Get the suspend_SR field of the given VM.

Signature:

SR ref get_suspend_SR (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: SR ref

value of the field

RPC name: get_suspend_VDI

Overview:

Get the suspend_VDI field of the given VM.

Signature:

VDI ref get_suspend_VDI (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VDI ref

value of the field

RPC name: get_tags

Overview:

Get the tags field of the given VM.

Signature:

string set get_tags (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string set

value of the field

RPC name: get_transportable_snapshot_id

Overview:

Get the transportable_snapshot_id field of the given VM.

Signature:

string get_transportable_snapshot_id (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_user_version

Overview:

Get the user_version field of the given VM.

Signature:

int get_user_version (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_uuid

Overview:

Get the uuid field of the given VM.

Signature:

string get_uuid (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_VBDs

Overview:

Get the VBDs field of the given VM.

Signature:

VBD ref set get_VBDs (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VBD ref set

value of the field

RPC name: get_VCPUs_at_startup

Overview:

Get the VCPUs/at_startup field of the given VM.

Signature:

int get_VCPUs_at_startup (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_VCPUs_max

Overview:

Get the VCPUs/max field of the given VM.

Signature:

int get_VCPUs_max (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_VCPUs_params

Overview:

Get the VCPUs/params field of the given VM.

Signature:

(string -> string) map get_VCPUs_params (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_version

Overview:

Get the version field of the given VM.

Signature:

int get_version (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_VGPUs

Overview:

Get the VGPUs field of the given VM.

Signature:

VGPU ref set get_VGPUs (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VGPU ref set

value of the field

RPC name: get_VIFs

Overview:

Get the VIFs field of the given VM.

Signature:

VIF ref set get_VIFs (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VIF ref set

value of the field

RPC name: get_VTPMs

Overview:

Get the VTPMs field of the given VM.

Signature:

VTPM ref set get_VTPMs (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VTPM ref set

value of the field

RPC name: get_VUSBs

Overview:

Get the VUSBs field of the given VM.

Signature:

VUSB ref set get_VUSBs (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: VUSB ref set

value of the field

RPC name: get_xenstore_data

Overview:

Get the xenstore_data field of the given VM.

Signature:

(string -> string) map get_xenstore_data (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: hard_reboot

Overview:

Stop executing the specified VM without attempting a clean shutdown and immediately restart the VM.

Signature:

void hard_reboot (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to reboot

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: hard_shutdown

Overview:

Stop executing the specified VM without attempting a clean shutdown.

Signature:

void hard_shutdown (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to destroy

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: import

Overview:

Import an XVA from a URI

Signature:

VM ref set import (session ref session_ref, string url, SR ref sr, bool full_restore, bool force)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string url The URL of the XVA file
SR ref sr The destination SR for the disks
bool full_restore Perform a full restore
bool force Force the import

Minimum Role: pool-operator

Return Type: VM ref set

Imported VM reference

RPC name: import_convert

Overview:

Import using a conversion service.

Signature:

void import_convert (session ref session_ref, string type, string username, string password, SR ref sr, (string -> string) map remote_config)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string type Type of the conversion
string username Admin username on the host
string password Password on the host
SR ref sr The destination SR
(string -> string) map remote_config Remote configuration options

Minimum Role: vm-admin

Return Type: void

RPC name: maximise_memory

Overview:

Returns the maximum amount of guest memory which will fit, together with overheads, in the supplied amount of physical memory. If ‘exact’ is true then an exact calculation is performed using the VM’s current settings. If ‘exact’ is false then a more conservative approximation is used

Signature:

int maximise_memory (session ref session_ref, VM ref self, int total, bool approximate)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int total Total amount of physical RAM to fit within
bool approximate If false the limit is calculated with the guest’s current exact configuration. Otherwise a more approximate calculation is performed

Minimum Role: read-only

Return Type: int

The maximum possible static-max

RPC name: migrate_send

Overview:

Migrate the VM to another host. This can only be called when the specified VM is in the Running state.

Signature:

VM ref migrate_send (session ref session_ref, VM ref vm, (string -> string) map dest, bool live, (VDI ref -> SR ref) map vdi_map, (VIF ref -> network ref) map vif_map, (string -> string) map options, (VGPU ref -> GPU_group ref) map vgpu_map)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM
(string -> string) map dest The result of a Host.migrate_receive call.
bool live Live migration
(VDI ref -> SR ref) map vdi_map Map of source VDI to destination SR
(VIF ref -> network ref) map vif_map Map of source VIF to destination network
(string -> string) map options Other parameters
(VGPU ref -> GPU_group ref) map vgpu_map Map of source vGPU to destination GPU group

Minimum Role: vm-power-admin

Return Type: VM ref

The reference of the newly created VM in the destination pool

Possible Error Codes: VM_BAD_POWER_STATE, LICENCE_RESTRICTION

RPC name: pause

Overview:

Pause the specified VM. This can only be called when the specified VM is in the Running state.

Signature:

void pause (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to pause

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: pool_migrate

Overview:

Migrate a VM to another Host.

Signature:

void pool_migrate (session ref session_ref, VM ref vm, host ref host, (string -> string) map options)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to migrate
host ref host The target host
(string -> string) map options Extra configuration operations: force, live, copy, compress. Each is a boolean option, taking ‘true’ or ‘false’ as a value. Option ‘compress’ controls the use of stream compression during migration.

Minimum Role: client-cert

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, VM_IS_TEMPLATE, OPERATION_NOT_ALLOWED, VM_BAD_POWER_STATE

RPC name: power_state_reset

Overview:

Reset the power-state of the VM to halted in the database only. (Used to recover from slave failures in pooling scenarios by resetting the power-states of VMs running on dead slaves to halted.) This is a potentially dangerous operation; use with care.

Signature:

void power_state_reset (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to reset

Minimum Role: pool-operator

Return Type: void

RPC name: provision

Overview:

Inspects the disk configuration contained within the VM’s other_config, creates VDIs and VBDs and then executes any applicable post-install script.

Signature:

void provision (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to be provisioned

Minimum Role: vm-admin

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED, LICENCE_RESTRICTION

RPC name: query_data_source

Overview:

Query the latest value of the specified data source

Signature:

float query_data_source (session ref session_ref, VM ref self, string data_source)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string data_source The data source to query

Minimum Role: read-only

Return Type: float

The latest value, averaged over the last 5 seconds

RPC name: query_services

Overview:

Query the system services advertised by this VM and register them. This can only be applied to a system domain.

Signature:

(string -> string) map query_services (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM

Minimum Role: pool-admin

Return Type: (string -> string) map

map of service type to name

RPC name: record_data_source

Overview:

Start recording the specified data source

Signature:

void record_data_source (session ref session_ref, VM ref self, string data_source)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string data_source The data source to record

Minimum Role: vm-admin

Return Type: void

RPC name: recover

Overview:

Recover the VM

Signature:

void recover (session ref session_ref, VM ref self, session ref session_to, bool force)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to recover
session ref session_to The session to which the VM is to be recovered.
bool force Whether the VM should replace newer versions of itself.

Minimum Role: read-only

Return Type: void

RPC name: remove_from_blocked_operations

Overview:

Remove the given key and its corresponding value from the blocked_operations field of the given VM. If the key is not in that Map, then do nothing.

Signature:

void remove_from_blocked_operations (session ref session_ref, VM ref self, vm_operations key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
vm_operations key Key to remove

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_HVM_boot_params

Overview:

Remove the given key and its corresponding value from the HVM/boot_params field of the given VM. If the key is not in that Map, then do nothing.

Signature:

void remove_from_HVM_boot_params (session ref session_ref, VM ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to remove

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_NVRAM

Overview:

Signature:

void remove_from_NVRAM (session ref session_ref, VM ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string key The key

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_other_config

Overview:

Remove the given key and its corresponding value from the other_config field of the given VM. If the key is not in that Map, then do nothing.

Signature:

void remove_from_other_config (session ref session_ref, VM ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to remove

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_platform

Overview:

Remove the given key and its corresponding value from the platform field of the given VM. If the key is not in that Map, then do nothing.

Signature:

void remove_from_platform (session ref session_ref, VM ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to remove

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_VCPUs_params

Overview:

Remove the given key and its corresponding value from the VCPUs/params field of the given VM. If the key is not in that Map, then do nothing.

Signature:

void remove_from_VCPUs_params (session ref session_ref, VM ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to remove

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_xenstore_data

Overview:

Remove the given key and its corresponding value from the xenstore_data field of the given VM. If the key is not in that Map, then do nothing.

Signature:

void remove_from_xenstore_data (session ref session_ref, VM ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string key Key to remove

Minimum Role: vm-admin

Return Type: void

RPC name: remove_tags

Overview:

Remove the given value from the tags field of the given VM. If the value is not in that Set, then do nothing.

Signature:

void remove_tags (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value Value to remove

Minimum Role: vm-operator

Return Type: void

RPC name: restart_device_models

Overview:

Restart device models of the VM

Signature:

void restart_device_models (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM

Minimum Role: client-cert

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, VM_IS_TEMPLATE, OPERATION_NOT_ALLOWED, VM_BAD_POWER_STATE

RPC name: resume

Overview:

Awaken the specified VM and resume it. This can only be called when the specified VM is in the Suspended state.

Signature:

void resume (session ref session_ref, VM ref vm, bool start_paused, bool force)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to resume
bool start_paused Resume VM in paused state if set to true.
bool force Attempt to force the VM to resume. If this flag is false then the VM may fail pre-resume safety checks (e.g. if the CPU the VM was running on looks substantially different to the current one)

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: resume_on

Overview:

Awaken the specified VM and resume it on a particular Host. This can only be called when the specified VM is in the Suspended state.

Signature:

void resume_on (session ref session_ref, VM ref vm, host ref host, bool start_paused, bool force)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to resume
host ref host The Host on which to resume the VM
bool start_paused Resume VM in paused state if set to true.
bool force Attempt to force the VM to resume. If this flag is false then the VM may fail pre-resume safety checks (e.g. if the CPU the VM was running on looks substantially different to the current one)

Minimum Role: client-cert

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: retrieve_wlb_recommendations

Overview:

Returns mapping of hosts to ratings, indicating the suitability of starting the VM at that location according to wlb. Rating is replaced with an error if the VM cannot boot there.

Signature:

(host ref -> string set) map retrieve_wlb_recommendations (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM

Minimum Role: read-only

Return Type: (host ref -> string set) map

The potential hosts and their corresponding recommendations or errors

RPC name: revert

Overview:

Reverts the specified VM to a previous state.

Signature:

void revert (session ref session_ref, VM ref snapshot)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref snapshot The snapshotted state that we revert to

Minimum Role: vm-power-admin

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OPERATION_NOT_ALLOWED, SR_FULL, VM_REVERT_FAILED

RPC name: send_sysrq

Overview:

Send the given key as a sysrq to this VM. The key is specified as a single character (a String of length 1). This can only be called when the specified VM is in the Running state.

Signature:

void send_sysrq (session ref session_ref, VM ref vm, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM
string key The key to send

Minimum Role: pool-admin

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE

RPC name: send_trigger

Overview:

Send the named trigger to this VM. This can only be called when the specified VM is in the Running state.

Signature:

void send_trigger (session ref session_ref, VM ref vm, string trigger)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM
string trigger The trigger to send

Minimum Role: pool-admin

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE

RPC name: set_actions_after_crash

Overview:

Sets the actions_after_crash parameter

Signature:

void set_actions_after_crash (session ref session_ref, VM ref self, on_crash_behaviour value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to set
on_crash_behaviour value The new value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_actions_after_reboot

Overview:

Set the actions/after_reboot field of the given VM.

Signature:

void set_actions_after_reboot (session ref session_ref, VM ref self, on_normal_exit value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
on_normal_exit value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_actions_after_shutdown

Overview:

Set the actions/after_shutdown field of the given VM.

Signature:

void set_actions_after_shutdown (session ref session_ref, VM ref self, on_normal_exit value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
on_normal_exit value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_actions_after_softreboot

Overview:

Set the actions/after_softreboot field of the given VM.

Signature:

void set_actions_after_softreboot (session ref session_ref, VM ref self, on_softreboot_behavior value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
on_softreboot_behavior value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_affinity

Overview:

Set the affinity field of the given VM.

Signature:

void set_affinity (session ref session_ref, VM ref self, host ref value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
host ref value New value to set

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_appliance

Overview:

Assign this VM to an appliance.

Signature:

void set_appliance (session ref session_ref, VM ref self, VM_appliance ref value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to assign to an appliance.
VM_appliance ref value The appliance to which this VM should be assigned.

Minimum Role: pool-operator

Return Type: void

RPC name: set_bios_strings

Overview:

Set custom BIOS strings to this VM. VM will be given a default set of BIOS strings, only some of which can be overridden by the supplied values. Allowed keys are: ‘bios-vendor’, ‘bios-version’, ‘system-manufacturer’, ‘system-product-name’, ‘system-version’, ‘system-serial-number’, ‘enclosure-asset-tag’, ‘baseboard-manufacturer’, ‘baseboard-product-name’, ‘baseboard-version’, ‘baseboard-serial-number’, ‘baseboard-asset-tag’, ‘baseboard-location-in-chassis’, ‘enclosure-asset-tag’

Signature:

void set_bios_strings (session ref session_ref, VM ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to modify
(string -> string) map value The custom BIOS strings as a list of key-value pairs

Minimum Role: vm-admin

Return Type: void

Possible Error Codes: VM_BIOS_STRINGS_ALREADY_SET, INVALID_VALUE

RPC name: set_blocked_operations

Overview:

Set the blocked_operations field of the given VM.

Signature:

void set_blocked_operations (session ref session_ref, VM ref self, (vm_operations -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
(vm_operations -> string) map value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_domain_type

Overview:

Set the VM.domain_type field of the given VM, which will take effect when it is next started

Signature:

void set_domain_type (session ref session_ref, VM ref self, domain_type value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
domain_type value The new domain type

Minimum Role: vm-admin

Return Type: void

RPC name: set_ha_always_run

This message is deprecated.

Overview:

Set the value of the ha_always_run

Signature:

void set_ha_always_run (session ref session_ref, VM ref self, bool value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
bool value The value

Minimum Role: pool-operator

Return Type: void

RPC name: set_ha_restart_priority

Overview:

Set the value of the ha_restart_priority field

Signature:

void set_ha_restart_priority (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string value The value

Minimum Role: pool-operator

Return Type: void

RPC name: set_hardware_platform_version

Overview:

Set the hardware_platform_version field of the given VM.

Signature:

void set_hardware_platform_version (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
int value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_has_vendor_device

Overview:

Controls whether, when the VM starts in HVM mode, its virtual hardware will include the emulated PCI device for which drivers may be available through Windows Update. Usually this should never be changed on a VM on which Windows has been installed: changing it on such a VM is likely to lead to a crash on next start.

Signature:

void set_has_vendor_device (session ref session_ref, VM ref self, bool value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM on which to set this flag
bool value True to provide the vendor PCI device.

Minimum Role: vm-admin

Return Type: void

RPC name: set_HVM_boot_params

Overview:

Set the HVM/boot_params field of the given VM.

Signature:

void set_HVM_boot_params (session ref session_ref, VM ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
(string -> string) map value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_HVM_boot_policy

This message is deprecated.

Overview:

Set the VM.HVM_boot_policy field of the given VM, which will take effect when it is next started

Signature:

void set_HVM_boot_policy (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string value The new HVM boot policy

Minimum Role: vm-admin

Return Type: void

RPC name: set_HVM_shadow_multiplier

Overview:

Set the shadow memory multiplier on a halted VM

Signature:

void set_HVM_shadow_multiplier (session ref session_ref, VM ref self, float value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
float value The new shadow memory multiplier to set

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_is_a_template

Overview:

Set the is_a_template field of the given VM.

Signature:

void set_is_a_template (session ref session_ref, VM ref self, bool value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
bool value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_memory

Overview:

Set the memory allocation of this VM. Sets all of memory_static_max, memory_dynamic_min, and memory_dynamic_max to the given value, and leaves memory_static_min untouched.

Signature:

void set_memory (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int value The new memory allocation (bytes).

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_memory_dynamic_max

Overview:

Set the value of the memory_dynamic_max field

Signature:

void set_memory_dynamic_max (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to modify
int value The new value of memory_dynamic_max

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_memory_dynamic_min

Overview:

Set the value of the memory_dynamic_min field

Signature:

void set_memory_dynamic_min (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to modify
int value The new value of memory_dynamic_min

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_memory_dynamic_range

Overview:

Set the minimum and maximum amounts of physical memory the VM is allowed to use.

Signature:

void set_memory_dynamic_range (session ref session_ref, VM ref self, int min, int max)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int min The new minimum value
int max The new maximum value

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_memory_limits

Overview:

Set the memory limits of this VM.

Signature:

void set_memory_limits (session ref session_ref, VM ref self, int static_min, int static_max, int dynamic_min, int dynamic_max)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int static_min The new value of memory_static_min.
int static_max The new value of memory_static_max.
int dynamic_min The new value of memory_dynamic_min.
int dynamic_max The new value of memory_dynamic_max.

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_memory_static_max

Overview:

Set the value of the memory_static_max field

Signature:

void set_memory_static_max (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to modify
int value The new value of memory_static_max

Minimum Role: vm-power-admin

Return Type: void

Possible Error Codes: HA_OPERATION_WOULD_BREAK_FAILOVER_PLAN

RPC name: set_memory_static_min

Overview:

Set the value of the memory_static_min field

Signature:

void set_memory_static_min (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM to modify
int value The new value of memory_static_min

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_memory_static_range

Overview:

Set the static (ie boot-time) range of virtual memory that the VM is allowed to use.

Signature:

void set_memory_static_range (session ref session_ref, VM ref self, int min, int max)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int min The new minimum value
int max The new maximum value

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_memory_target_live

This message is deprecated.

Overview:

Set the memory target for a running VM

Signature:

void set_memory_target_live (session ref session_ref, VM ref self, int target)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int target The target in bytes

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_name_description

Overview:

Set the name/description field of the given VM.

Signature:

void set_name_description (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_name_label

Overview:

Set the name/label field of the given VM.

Signature:

void set_name_label (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_NVRAM

Overview:

Signature:

void set_NVRAM (session ref session_ref, VM ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
(string -> string) map value The value

Minimum Role: vm-admin

Return Type: void

RPC name: set_order

Overview:

Set this VM’s boot order

Signature:

void set_order (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int value This VM’s boot order

Minimum Role: pool-operator

Return Type: void

RPC name: set_other_config

Overview:

Set the other_config field of the given VM.

Signature:

void set_other_config (session ref session_ref, VM ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
(string -> string) map value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_PCI_bus

This message is deprecated.

Overview:

Set the PCI_bus field of the given VM.

Signature:

void set_PCI_bus (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_platform

Overview:

Set the platform field of the given VM.

Signature:

void set_platform (session ref session_ref, VM ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
(string -> string) map value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_protection_policy

This message is removed.

Overview:

Set the value of the protection_policy field

Signature:

void set_protection_policy (session ref session_ref, VM ref self, VMPP ref value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
VMPP ref value The value

Minimum Role: pool-operator

Return Type: void

RPC name: set_PV_args

Overview:

Set the PV/args field of the given VM.

Signature:

void set_PV_args (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_PV_bootloader

Overview:

Set the PV/bootloader field of the given VM.

Signature:

void set_PV_bootloader (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_PV_bootloader_args

Overview:

Set the PV/bootloader_args field of the given VM.

Signature:

void set_PV_bootloader_args (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_PV_kernel

Overview:

Set the PV/kernel field of the given VM.

Signature:

void set_PV_kernel (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_PV_legacy_args

Overview:

Set the PV/legacy_args field of the given VM.

Signature:

void set_PV_legacy_args (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_PV_ramdisk

Overview:

Set the PV/ramdisk field of the given VM.

Signature:

void set_PV_ramdisk (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_recommendations

Overview:

Set the recommendations field of the given VM.

Signature:

void set_recommendations (session ref session_ref, VM ref self, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_shadow_multiplier_live

Overview:

Set the shadow memory multiplier on a running VM

Signature:

void set_shadow_multiplier_live (session ref session_ref, VM ref self, float multiplier)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
float multiplier The new shadow memory multiplier to set

Minimum Role: vm-power-admin

Return Type: void

RPC name: set_shutdown_delay

Overview:

Set this VM’s shutdown delay in seconds

Signature:

void set_shutdown_delay (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int value This VM’s shutdown delay in seconds

Minimum Role: pool-operator

Return Type: void

RPC name: set_snapshot_schedule

Overview:

Set the value of the snapshot schedule field

Signature:

void set_snapshot_schedule (session ref session_ref, VM ref self, VMSS ref value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
VMSS ref value The value

Minimum Role: pool-operator

Return Type: void

RPC name: set_start_delay

Overview:

Set this VM’s start delay in seconds

Signature:

void set_start_delay (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int value This VM’s start delay in seconds

Minimum Role: pool-operator

Return Type: void

RPC name: set_suspend_SR

Overview:

Set the suspend_SR field of the given VM.

Signature:

void set_suspend_SR (session ref session_ref, VM ref self, SR ref value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
SR ref value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_suspend_VDI

Overview:

Set this VM’s suspend VDI, which must be indentical to its current one

Signature:

void set_suspend_VDI (session ref session_ref, VM ref self, VDI ref value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
VDI ref value The suspend VDI uuid

Minimum Role: pool-operator

Return Type: void

RPC name: set_tags

Overview:

Set the tags field of the given VM.

Signature:

void set_tags (session ref session_ref, VM ref self, string set value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
string set value New value to set

Minimum Role: vm-operator

Return Type: void

RPC name: set_uefi_mode

Overview:

Set the UEFI mode of a VM

Signature:

string set_uefi_mode (session ref session_ref, VM ref self, vm_uefi_mode mode)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
vm_uefi_mode mode The UEFI mode to set

Minimum Role: pool-admin

Return Type: string

Result from the varstore-sb-state call

RPC name: set_user_version

Overview:

Set the user_version field of the given VM.

Signature:

void set_user_version (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
int value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_VCPUs_at_startup

Overview:

Set the number of startup VCPUs for a halted VM

Signature:

void set_VCPUs_at_startup (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int value The new maximum number of VCPUs

Minimum Role: vm-admin

Return Type: void

RPC name: set_VCPUs_max

Overview:

Set the maximum number of VCPUs for a halted VM

Signature:

void set_VCPUs_max (session ref session_ref, VM ref self, int value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int value The new maximum number of VCPUs

Minimum Role: vm-admin

Return Type: void

RPC name: set_VCPUs_number_live

Overview:

Set the number of VCPUs for a running VM

Signature:

void set_VCPUs_number_live (session ref session_ref, VM ref self, int nvcpu)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
int nvcpu The number of VCPUs

Minimum Role: vm-admin

Return Type: void

Possible Error Codes: OPERATION_NOT_ALLOWED, LICENCE_RESTRICTION

RPC name: set_VCPUs_params

Overview:

Set the VCPUs/params field of the given VM.

Signature:

void set_VCPUs_params (session ref session_ref, VM ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
(string -> string) map value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: set_xenstore_data

Overview:

Set the xenstore_data field of the given VM.

Signature:

void set_xenstore_data (session ref session_ref, VM ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object
(string -> string) map value New value to set

Minimum Role: vm-admin

Return Type: void

RPC name: shutdown

Overview:

Attempts to first clean shutdown a VM and if it should fail then perform a hard shutdown on it.

Signature:

void shutdown (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to shutdown

Minimum Role: client-cert

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: snapshot

Overview:

Snapshots the specified VM, making a new VM. Snapshot automatically exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored (e.g. Copy on Write).

Signature:

VM ref snapshot (session ref session_ref, VM ref vm, string new_name, VDI ref set ignore_vdis)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to be snapshotted
string new_name The name of the snapshotted VM
VDI ref set ignore_vdis A list of VDIs to ignore for the snapshot

Minimum Role: vm-power-admin

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED

RPC name: snapshot_with_quiesce

This message is removed.

Overview:

Snapshots the specified VM with quiesce, making a new VM. Snapshot automatically exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored (e.g. Copy on Write).

Signature:

VM ref snapshot_with_quiesce (session ref session_ref, VM ref vm, string new_name)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to be snapshotted
string new_name The name of the snapshotted VM

Minimum Role: vm-power-admin

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED, VM_SNAPSHOT_WITH_QUIESCE_FAILED, VM_SNAPSHOT_WITH_QUIESCE_TIMEOUT, VM_SNAPSHOT_WITH_QUIESCE_PLUGIN_DEOS_NOT_RESPOND, VM_SNAPSHOT_WITH_QUIESCE_NOT_SUPPORTED

RPC name: start

Overview:

Start the specified VM. This function can only be called with the VM is in the Halted State.

Signature:

void start (session ref session_ref, VM ref vm, bool start_paused, bool force)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to start
bool start_paused Instantiate VM in paused state if set to true.
bool force Attempt to force the VM to start. If this flag is false then the VM may fail pre-boot safety checks (e.g. if the CPU the VM last booted on looks substantially different to the current one)

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, VM_HVM_REQUIRED, VM_IS_TEMPLATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, BOOTLOADER_FAILED, UNKNOWN_BOOTLOADER, NO_HOSTS_AVAILABLE, LICENCE_RESTRICTION

RPC name: start_on

Overview:

Start the specified VM on a particular host. This function can only be called with the VM is in the Halted State.

Signature:

void start_on (session ref session_ref, VM ref vm, host ref host, bool start_paused, bool force)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to start
host ref host The Host on which to start the VM
bool start_paused Instantiate VM in paused state if set to true.
bool force Attempt to force the VM to start. If this flag is false then the VM may fail pre-boot safety checks (e.g. if the CPU the VM last booted on looks substantially different to the current one)

Minimum Role: client-cert

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, VM_IS_TEMPLATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, BOOTLOADER_FAILED, UNKNOWN_BOOTLOADER

RPC name: suspend

Overview:

Suspend the specified VM to disk. This can only be called when the specified VM is in the Running state.

Signature:

void suspend (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to suspend

Minimum Role: client-cert

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: unpause

Overview:

Resume the specified VM. This can only be called when the specified VM is in the Paused state.

Signature:

void unpause (session ref session_ref, VM ref vm)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref vm The VM to unpause

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: update_allowed_operations

Overview:

Recomputes the list of acceptable operations

Signature:

void update_allowed_operations (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to the object

Minimum Role: pool-admin

Return Type: void

RPC name: wait_memory_target_live

This message is deprecated.

Overview:

Wait for a running VM to reach its current memory target

Signature:

void wait_memory_target_live (session ref session_ref, VM ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM

Minimum Role: read-only

Return Type: void

Class: VM

In this article