Class: VM

Last published : Oct 01, 2026
A virtual machine or 'guest'.
Related information
XenServer 9 Management API

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 RO/constructor 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
groups VM_group ref set RO/runtime VM groups associated with 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 RO/constructor 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, otherwise there may be, for example, 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, for example, 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 RO/constructor 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, for example, 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
secureboot_certificates_state vm_secureboot_certificates_state RO/runtime The state of the Secure Boot certificates, showing whether an update is available, already scheduled, or not needed.
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/<domid>/vm-data) after the VM is created.

RPCs associated with class: VM

RPC name: addtags

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)
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: addtoblockedoperations

Overview:
Update list of operations which have been explicitly blocked and an error code
Signature:
void add_to_blocked_operations (session ref session_ref, VM ref self, vm_operations key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
vm_operations key Blocked operation
string value Error code
Minimum Role: vm-admin
Return Type: void

RPC name: addtoHVMbootparams

Overview:
Add the given keyvalue pair to the HVM/bootparams field of the given VM.
Signature:
void add_to_HVM_boot_params (session ref session_ref, VM ref self, string key, string value)
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: addtoNVRAM

Overview:
Signature:
void add_to_NVRAM (session ref session_ref, VM ref self, string key, string value)
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: addtootherconfig

Overview:
Add the given keyvalue pair to the otherconfig field of the given VM.
Signature:
void add_to_other_config (session ref session_ref, VM ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to object
string key Key to add
string value Value to add
Minimum Role: vm-admin
Return Type: void

RPC name: addtoplatform

Overview:
Add the given keyvalue 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)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to object
string key Key to add
string value Value to add
Minimum Role: vm-admin
Return Type: void

RPC name: addtoVCPUsparams

Overview:
Add the given keyvalue 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)
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: addtoVCPUsparamslive

Overview:
Add the given keyvalue pair to VM.VCPUsparams, 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)
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: addtoxenstoredata

Overview:
Add the given keyvalue pair to the xenstoredata field of the given VM.
Signature:
void add_to_xenstore_data (session ref session_ref, VM ref self, string key, string value)
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: assertagile

Overview:
Returns an error if the VM is not considered agile, for example, because it is tied to a resource local to a host
Signature:
void assert_agile (session ref session_ref, VM ref self)
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: assertcanberecovered

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)
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: assertcanboothere

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)
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: assertcanmigrate

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)
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: void
Possible Error Codes: LICENCE_RESTRICTION

RPC name: assertoperationvalid

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)
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: callhostplugin

Overview:
Call an API plugin on the host where this vm resides
Signature:
string call_host_plugin (session ref session_ref, VM ref vm, string plugin, string fn, (string -> string) map args)
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: callplugin

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)
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 for example, Copy on Write and saves the memory image as well.
Signature:
VM ref checkpoint (session ref session_ref, VM ref vm, string new_name)
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: cleanreboot

Overview:
Attempt to cleanly shutdown the specified VM Note: this may not be supported, for example, 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)
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: cleanshutdown

Overview:
Attempt to cleanly shutdown the specified VM. Note: this may not be supported, for example, 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)
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 for example, 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)
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: computememoryoverhead

Overview:
Computes the virtualization memory overhead of a VM.
Signature:
int compute_memory_overhead (session ref session_ref, VM ref vm)
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)
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: copybiosstrings

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)
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)
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: createnewblob

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)
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)
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: forgetdatasourcearchives

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)
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: getactionsaftercrash

Overview:
Get the actions/aftercrash field of the given VM.
Signature:
on_crash_behaviour get_actions_after_crash (session ref session_ref, VM ref self)
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: getactionsafterreboot

Overview:
Get the actions/afterreboot field of the given VM.
Signature:
on_normal_exit get_actions_after_reboot (session ref session_ref, VM ref self)
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: getactionsaftershutdown

Overview:
Get the actions/aftershutdown field of the given VM.
Signature:
on_normal_exit get_actions_after_shutdown (session ref session_ref, VM ref self)
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: getactionsaftersoftreboot

Overview:
Get the actions/aftersoftreboot field of the given VM.
Signature:
on_softreboot_behavior get_actions_after_softreboot (session ref session_ref, VM ref self)
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: getaffinity

Overview:
Get the affinity field of the given VM.
Signature:
host ref get_affinity (session ref session_ref, VM ref self)
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: getall

Overview:
Return a list of all the VMs known to the system.
Signature:
VM ref set get_all (session ref session_ref)
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: getallrecords

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)
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: getallowedoperations

Overview:
Get the allowedoperations field of the given VM.
Signature:
vm_operations set get_allowed_operations (session ref session_ref, VM ref self)
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: getallowedVBDdevices

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)
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: getallowedVIFdevices

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)
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: getappliance

Overview:
Get the appliance field of the given VM.
Signature:
VM_appliance ref get_appliance (session ref session_ref, VM ref self)
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: getattachedPCIs

Overview:
Get the attachedPCIs field of the given VM.
Signature:
PCI ref set get_attached_PCIs (session ref session_ref, VM ref self)
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: getbiosstrings

Overview:
Get the biosstrings field of the given VM.
Signature:
(string -> string) map get_bios_strings (session ref session_ref, VM ref self)
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: getblobs

Overview:
Get the blobs field of the given VM.
Signature:
(string -> blob ref) map get_blobs (session ref session_ref, VM ref self)
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: getblockedoperations

Overview:
Get the blockedoperations field of the given VM.
Signature:
(vm_operations -> string) map get_blocked_operations (session ref session_ref, VM ref self)
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: getbootrecord

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, for example CPU hotplug
Signature:
VM record get_boot_record (session ref session_ref, VM ref self)
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: getbynamelabel

Overview:
Get all the VM instances with the given label.
Signature:
VM ref set get_by_name_label (session ref session_ref, string label)
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: getbyuuid

Overview:
Get a reference to the VM instance with the specified UUID.
Signature:
VM ref get_by_uuid (session ref session_ref, string uuid)
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: getchildren

Overview:
Get the children field of the given VM.
Signature:
VM ref set get_children (session ref session_ref, VM ref self)
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: getconsoles

Overview:
Get the consoles field of the given VM.
Signature:
console ref set get_consoles (session ref session_ref, VM ref self)
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: getcooperative

This message is deprecated.
Overview:
Return true if the VM is currently 'cooperative' i.e. is expected to reach a balloon target and actually has done
Signature:
bool get_cooperative (session ref session_ref, VM ref self)
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 'cooperative'; false otherwise

RPC name: getcrashdumps

Overview:
Get the crashdumps field of the given VM.
Signature:
crashdump ref set get_crash_dumps (session ref session_ref, VM ref self)
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: getcurrentoperations

Overview:
Get the currentoperations field of the given VM.
Signature:
(string -> vm_operations) map get_current_operations (session ref session_ref, VM ref self)
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: getdatasources

Overview:
Signature:
data_source record set get_data_sources (session ref session_ref, VM ref self)
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: getdomaintype

Overview:
Get the domaintype field of the given VM.
Signature:
domain_type get_domain_type (session ref session_ref, VM ref self)
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: getdomarch

Overview:
Get the domarch field of the given VM.
Signature:
string get_domarch (session ref session_ref, VM ref self)
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: getdomid

Overview:
Get the domid field of the given VM.
Signature:
int get_domid (session ref session_ref, VM ref self)
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: getgenerationid

Overview:
Get the generationid field of the given VM.
Signature:
string get_generation_id (session ref session_ref, VM ref self)
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: getgroups

Overview:
Get the groups field of the given VM.
Signature:
VM_group ref set get_groups (session ref session_ref, VM ref self)
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_group ref set
value of the field

RPC name: getguestmetrics

Overview:
Get the guestmetrics field of the given VM.
Signature:
VM_guest_metrics ref get_guest_metrics (session ref session_ref, VM ref self)
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: gethaalwaysrun

This message is deprecated.
Overview:
Get the haalwaysrun field of the given VM.
Signature:
bool get_ha_always_run (session ref session_ref, VM ref self)
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: getharestartpriority

Overview:
Get the harestartpriority field of the given VM.
Signature:
string get_ha_restart_priority (session ref session_ref, VM ref self)
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: gethardwareplatformversion

Overview:
Get the hardwareplatformversion field of the given VM.
Signature:
int get_hardware_platform_version (session ref session_ref, VM ref self)
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: gethasvendordevice

Overview:
Get the hasvendordevice field of the given VM.
Signature:
bool get_has_vendor_device (session ref session_ref, VM ref self)
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: getHVMbootparams

Overview:
Get the HVM/bootparams field of the given VM.
Signature:
(string -> string) map get_HVM_boot_params (session ref session_ref, VM ref self)
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: getHVMbootpolicy

This message is deprecated.
Overview:
Get the HVM/bootpolicy field of the given VM.
Signature:
string get_HVM_boot_policy (session ref session_ref, VM ref self)
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: getHVMshadowmultiplier

Overview:
Get the HVM/shadowmultiplier field of the given VM.
Signature:
float get_HVM_shadow_multiplier (session ref session_ref, VM ref self)
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: getisasnapshot

Overview:
Get the isasnapshot field of the given VM.
Signature:
bool get_is_a_snapshot (session ref session_ref, VM ref self)
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: getisatemplate

Overview:
Get the isatemplate field of the given VM.
Signature:
bool get_is_a_template (session ref session_ref, VM ref self)
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: getiscontroldomain

Overview:
Get the iscontroldomain field of the given VM.
Signature:
bool get_is_control_domain (session ref session_ref, VM ref self)
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: getisdefaulttemplate

Overview:
Get the isdefaulttemplate field of the given VM.
Signature:
bool get_is_default_template (session ref session_ref, VM ref self)
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: getissnapshotfromvmpp

This message is removed.
Overview:
Get the issnapshotfromvmpp field of the given VM.
Signature:
bool get_is_snapshot_from_vmpp (session ref session_ref, VM ref self)
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: getisvmsssnapshot

Overview:
Get the isvmsssnapshot field of the given VM.
Signature:
bool get_is_vmss_snapshot (session ref session_ref, VM ref self)
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: getlastbootCPUflags

Overview:
Get the lastbootCPUflags field of the given VM.
Signature:
(string -> string) map get_last_boot_CPU_flags (session ref session_ref, VM ref self)
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: getlastbootedrecord

Overview:
Get the lastbootedrecord field of the given VM.
Signature:
string get_last_booted_record (session ref session_ref, VM ref self)
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: getmemorydynamicmax

Overview:
Get the memory/dynamicmax field of the given VM.
Signature:
int get_memory_dynamic_max (session ref session_ref, VM ref self)
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: getmemorydynamicmin

Overview:
Get the memory/dynamicmin field of the given VM.
Signature:
int get_memory_dynamic_min (session ref session_ref, VM ref self)
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: getmemoryoverhead

Overview:
Get the memory/overhead field of the given VM.
Signature:
int get_memory_overhead (session ref session_ref, VM ref self)
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: getmemorystaticmax

Overview:
Get the memory/staticmax field of the given VM.
Signature:
int get_memory_static_max (session ref session_ref, VM ref self)
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: getmemorystaticmin

Overview:
Get the memory/staticmin field of the given VM.
Signature:
int get_memory_static_min (session ref session_ref, VM ref self)
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: getmemorytarget

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)
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: getmetrics

Overview:
Get the metrics field of the given VM.
Signature:
VM_metrics ref get_metrics (session ref session_ref, VM ref self)
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: getnamedescription

Overview:
Get the name/description field of the given VM.
Signature:
string get_name_description (session ref session_ref, VM ref self)
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: getnamelabel

Overview:
Get the name/label field of the given VM.
Signature:
string get_name_label (session ref session_ref, VM ref self)
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: getNVRAM

Overview:
Get the NVRAM field of the given VM.
Signature:
(string -> string) map get_NVRAM (session ref session_ref, VM ref self)
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: getorder

Overview:
Get the order field of the given VM.
Signature:
int get_order (session ref session_ref, VM ref self)
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: getotherconfig

Overview:
Get the otherconfig field of the given VM.
Signature:
(string -> string) map get_other_config (session ref session_ref, VM ref self)
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: getparent

Overview:
Get the parent field of the given VM.
Signature:
VM ref get_parent (session ref session_ref, VM ref self)
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: getPCIbus

This message is deprecated.
Overview:
Get the PCIbus field of the given VM.
Signature:
string get_PCI_bus (session ref session_ref, VM ref self)
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: getpendingguidances

Overview:
Get the pendingguidances field of the given VM.
Signature:
update_guidances set get_pending_guidances (session ref session_ref, VM ref self)
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: getpendingguidancesfull

Overview:
Get the pendingguidancesfull field of the given VM.
Signature:
update_guidances set get_pending_guidances_full (session ref session_ref, VM ref self)
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: getplatform

Overview:
Get the platform field of the given VM.
Signature:
(string -> string) map get_platform (session ref session_ref, VM ref self)
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: getpossiblehosts

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)
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: getpowerstate

Overview:
Get the powerstate field of the given VM.
Signature:
vm_power_state get_power_state (session ref session_ref, VM ref self)
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: getprotectionpolicy

This message is deprecated.
Overview:
Get the protectionpolicy field of the given VM.
Signature:
VMPP ref get_protection_policy (session ref session_ref, VM ref self)
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: getPVargs

Overview:
Get the PV/args field of the given VM.
Signature:
string get_PV_args (session ref session_ref, VM ref self)
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: getPVbootloader

Overview:
Get the PV/bootloader field of the given VM.
Signature:
string get_PV_bootloader (session ref session_ref, VM ref self)
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: getPVbootloaderargs

Overview:
Get the PV/bootloaderargs field of the given VM.
Signature:
string get_PV_bootloader_args (session ref session_ref, VM ref self)
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: getPVkernel

Overview:
Get the PV/kernel field of the given VM.
Signature:
string get_PV_kernel (session ref session_ref, VM ref self)
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: getPVlegacyargs

Overview:
Get the PV/legacyargs field of the given VM.
Signature:
string get_PV_legacy_args (session ref session_ref, VM ref self)
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: getPVramdisk

Overview:
Get the PV/ramdisk field of the given VM.
Signature:
string get_PV_ramdisk (session ref session_ref, VM ref self)
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: getrecommendations

Overview:
Get the recommendations field of the given VM.
Signature:
string get_recommendations (session ref session_ref, VM ref self)
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: getrecord

Overview:
Get a record containing the current state of the given VM.
Signature:
VM record get_record (session ref session_ref, VM ref self)
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: getreferencelabel

Overview:
Get the referencelabel field of the given VM.
Signature:
string get_reference_label (session ref session_ref, VM ref self)
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: getrequiresreboot

Overview:
Get the requiresreboot field of the given VM.
Signature:
bool get_requires_reboot (session ref session_ref, VM ref self)
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: getresidenton

Overview:
Get the residenton field of the given VM.
Signature:
host ref get_resident_on (session ref session_ref, VM ref self)
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: getscheduledtoberesidenton

Overview:
Get the scheduledtoberesidenton field of the given VM.
Signature:
host ref get_scheduled_to_be_resident_on (session ref session_ref, VM ref self)
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: getsecurebootcertificatesstate

Overview:
Get the securebootcertificatesstate field of the given VM.
Signature:
vm_secureboot_certificates_state get_secureboot_certificates_state (session ref session_ref, VM ref self)
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_secureboot_certificates_state
value of the field

RPC name: getsecurebootreadiness

Overview:
Return the secureboot readiness of the VM
Signature:
vm_secureboot_readiness get_secureboot_readiness (session ref session_ref, VM ref self)
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: getshutdowndelay

Overview:
Get the shutdowndelay field of the given VM.
Signature:
int get_shutdown_delay (session ref session_ref, VM ref self)
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: getsnapshotinfo

Overview:
Get the snapshotinfo field of the given VM.
Signature:
(string -> string) map get_snapshot_info (session ref session_ref, VM ref self)
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: getsnapshotmetadata

Overview:
Get the snapshotmetadata field of the given VM.
Signature:
string get_snapshot_metadata (session ref session_ref, VM ref self)
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: getsnapshotof

Overview:
Get the snapshotof field of the given VM.
Signature:
VM ref get_snapshot_of (session ref session_ref, VM ref self)
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: getsnapshotschedule

Overview:
Get the snapshotschedule field of the given VM.
Signature:
VMSS ref get_snapshot_schedule (session ref session_ref, VM ref self)
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: getsnapshottime

Overview:
Get the snapshottime field of the given VM.
Signature:
datetime get_snapshot_time (session ref session_ref, VM ref self)
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: getsnapshots

Overview:
Get the snapshots field of the given VM.
Signature:
VM ref set get_snapshots (session ref session_ref, VM ref self)
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: getSRsrequiredforrecovery

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)
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: getstartdelay

Overview:
Get the startdelay field of the given VM.
Signature:
int get_start_delay (session ref session_ref, VM ref self)
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: getsuspendSR

Overview:
Get the suspendSR field of the given VM.
Signature:
SR ref get_suspend_SR (session ref session_ref, VM ref self)
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: getsuspendVDI

Overview:
Get the suspendVDI field of the given VM.
Signature:
VDI ref get_suspend_VDI (session ref session_ref, VM ref self)
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: gettags

Overview:
Get the tags field of the given VM.
Signature:
string set get_tags (session ref session_ref, VM ref self)
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: gettransportablesnapshotid

Overview:
Get the transportablesnapshotid field of the given VM.
Signature:
string get_transportable_snapshot_id (session ref session_ref, VM ref self)
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: getuserversion

Overview:
Get the userversion field of the given VM.
Signature:
int get_user_version (session ref session_ref, VM ref self)
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: getuuid

Overview:
Get the uuid field of the given VM.
Signature:
string get_uuid (session ref session_ref, VM ref self)
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: getVBDs

Overview:
Get the VBDs field of the given VM.
Signature:
VBD ref set get_VBDs (session ref session_ref, VM ref self)
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: getVCPUsatstartup

Overview:
Get the VCPUs/atstartup field of the given VM.
Signature:
int get_VCPUs_at_startup (session ref session_ref, VM ref self)
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: getVCPUsmax

Overview:
Get the VCPUs/max field of the given VM.
Signature:
int get_VCPUs_max (session ref session_ref, VM ref self)
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: getVCPUsparams

Overview:
Get the VCPUs/params field of the given VM.
Signature:
(string -> string) map get_VCPUs_params (session ref session_ref, VM ref self)
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: getversion

Overview:
Get the version field of the given VM.
Signature:
int get_version (session ref session_ref, VM ref self)
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: getVGPUs

Overview:
Get the VGPUs field of the given VM.
Signature:
VGPU ref set get_VGPUs (session ref session_ref, VM ref self)
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: getVIFs

Overview:
Get the VIFs field of the given VM.
Signature:
VIF ref set get_VIFs (session ref session_ref, VM ref self)
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: getVTPMs

Overview:
Get the VTPMs field of the given VM.
Signature:
VTPM ref set get_VTPMs (session ref session_ref, VM ref self)
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: getVUSBs

Overview:
Get the VUSBs field of the given VM.
Signature:
VUSB ref set get_VUSBs (session ref session_ref, VM ref self)
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: getxenstoredata

Overview:
Get the xenstoredata field of the given VM.
Signature:
(string -> string) map get_xenstore_data (session ref session_ref, VM ref self)
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: hardreboot

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)
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: hardshutdown

Overview:
Stop executing the specified VM without attempting a clean shutdown.
Signature:
void hard_shutdown (session ref session_ref, VM ref vm)
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)
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: importconvert

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)
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: maximisememory

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)
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 staticmax

RPC name: migratesend

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, (VDI ref -> string) map vdi_format_map)
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
(VDI ref -> string) map vdi_format_map Map of source VDI to it's expected type on destination
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)
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: poolmigrate

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)
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: powerstatereset

Overview:
Reset the powerstate of the VM to halted in the database only. Used to recover from slave failures in pooling scenarios by resetting the powerstates 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)
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 otherconfig, creates VDIs and VBDs and then executes any applicable postinstall script.
Signature:
void provision (session ref session_ref, VM ref vm)
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: querydatasource

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)
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: queryservices

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)
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: recorddatasource

Overview:
Start recording the specified data source
Signature:
void record_data_source (session ref session_ref, VM ref self, string data_source)
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)
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: removefromblockedoperations

Overview:
Update list of operations which have been explicitly blocked and an error code
Signature:
void remove_from_blocked_operations (session ref session_ref, VM ref self, vm_operations key)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
vm_operations key Blocked operation
Minimum Role: vm-admin
Return Type: void

RPC name: removefromHVMbootparams

Overview:
Remove the given key and its corresponding value from the HVM/bootparams 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)
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: removefromNVRAM

Overview:
Signature:
void remove_from_NVRAM (session ref session_ref, VM ref self, string key)
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: removefromotherconfig

Overview:
Remove the given key and its corresponding value from the otherconfig 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)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to object
string key Key of entry to remove
Minimum Role: vm-admin
Return Type: void

RPC name: removefromplatform

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)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to object
string key Key of entry to remove
Minimum Role: vm-admin
Return Type: void

RPC name: removefromVCPUsparams

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)
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: removefromxenstoredata

Overview:
Remove the given key and its corresponding value from the xenstoredata 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)
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: removetags

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)
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: restartdevicemodels

Overview:
Restart device models of the VM
Signature:
void restart_device_models (session ref session_ref, VM ref self)
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)
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 (for example, 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: resumeon

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)
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 (for example, 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: retrievewlbrecommendations

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)
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)
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: sendsysrq

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)
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: sendtrigger

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)
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: setactionsaftercrash

Overview:
Sets the actionsaftercrash parameter
Signature:
void set_actions_after_crash (session ref session_ref, VM ref self, on_crash_behaviour value)
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: setactionsafterreboot

Overview:
Set the actions/afterreboot field of the given VM.
Signature:
void set_actions_after_reboot (session ref session_ref, VM ref self, on_normal_exit value)
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: setactionsaftershutdown

Overview:
Set the actions/aftershutdown field of the given VM.
Signature:
void set_actions_after_shutdown (session ref session_ref, VM ref self, on_normal_exit value)
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: setactionsaftersoftreboot

Overview:
Set the actions/aftersoftreboot field of the given VM.
Signature:
void set_actions_after_softreboot (session ref session_ref, VM ref self, on_softreboot_behavior value)
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: setaffinity

Overview:
Set the affinity field of the given VM.
Signature:
void set_affinity (session ref session_ref, VM ref self, host ref value)
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: setappliance

Overview:
Assign this VM to an appliance.
Signature:
void set_appliance (session ref session_ref, VM ref self, VM_appliance ref value)
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: setbiosstrings

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: 'biosvendor', 'biosversion', 'systemmanufacturer', 'systemproductname', 'systemversion', 'systemserialnumber', 'enclosureassettag', 'baseboardmanufacturer', 'baseboardproductname', 'baseboardversion', 'baseboardserialnumber', 'baseboardassettag', 'baseboardlocationinchassis', 'enclosureassettag'
Signature:
void set_bios_strings (session ref session_ref, VM ref self, (string -> string) map value)
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: setblockedoperations

Overview:
Update list of operations which have been explicitly blocked and an error code
Signature:
void set_blocked_operations (session ref session_ref, VM ref self, (vm_operations -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
(vm_operations -> string) map value Blocked operations
Minimum Role: vm-admin
Return Type: void

RPC name: setdomaintype

Overview:
Set the VM.domaintype 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)
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: setgroups

Overview:
Associate this VM with VM groups.
Signature:
void set_groups (session ref session_ref, VM ref self, VM_group ref set value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
VM_group ref set value The VM groups to set
Minimum Role: vm-admin
Return Type: void
Possible Error Codes: OPERATION_NOT_ALLOWED

RPC name: sethaalwaysrun

This message is deprecated.
Overview:
Set the value of the haalwaysrun
Signature:
void set_ha_always_run (session ref session_ref, VM ref self, bool value)
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: setharestartpriority

Overview:
Set the value of the harestartpriority field
Signature:
void set_ha_restart_priority (session ref session_ref, VM ref self, string value)
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: sethardwareplatformversion

Overview:
Set the hardwareplatformversion field of the given VM.
Signature:
void set_hardware_platform_version (session ref session_ref, VM ref self, int value)
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: sethasvendordevice

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)
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: setHVMbootparams

Overview:
Set the HVM/bootparams field of the given VM.
Signature:
void set_HVM_boot_params (session ref session_ref, VM ref self, (string -> string) map value)
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: setHVMbootpolicy

This message is deprecated.
Overview:
Set the VM.HVMbootpolicy 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)
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: setHVMshadowmultiplier

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)
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: setisatemplate

Overview:
Set the isatemplate field of the given VM.
Signature:
void set_is_a_template (session ref session_ref, VM ref self, bool value)
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: setmemory

Overview:
Set the memory allocation of this VM. Sets all of memorystaticmax, memorydynamicmin, and memorydynamicmax to the given value, and leaves memorystaticmin untouched.
Signature:
void set_memory (session ref session_ref, VM ref self, int value)
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: setmemorydynamicmax

Overview:
Set the value of the memorydynamicmax field
Signature:
void set_memory_dynamic_max (session ref session_ref, VM ref self, int value)
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: setmemorydynamicmin

Overview:
Set the value of the memorydynamicmin field
Signature:
void set_memory_dynamic_min (session ref session_ref, VM ref self, int value)
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: setmemorydynamicrange

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)
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: setmemorylimits

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)
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: setmemorystaticmax

Overview:
Set the value of the memorystaticmax field
Signature:
void set_memory_static_max (session ref session_ref, VM ref self, int value)
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: setmemorystaticmin

Overview:
Set the value of the memorystaticmin field
Signature:
void set_memory_static_min (session ref session_ref, VM ref self, int value)
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: setmemorystaticrange

Overview:
Set the static ie boottime 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)
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: setmemorytargetlive

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)
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: setnamedescription

Overview:
Set the name/description field of the given VM.
Signature:
void set_name_description (session ref session_ref, VM ref self, string value)
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: setnamelabel

Overview:
Set the name/label field of the given VM.
Signature:
void set_name_label (session ref session_ref, VM ref self, string value)
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: setNVRAM

Overview:
Signature:
void set_NVRAM (session ref session_ref, VM ref self, (string -> string) map value)
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: setorder

Overview:
Set this VM's boot order
Signature:
void set_order (session ref session_ref, VM ref self, int value)
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: setotherconfig

Overview:
Set the otherconfig field of the given VM.
Signature:
void set_other_config (session ref session_ref, VM ref self, (string -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to object
(string -> string) map value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setPCIbus

This message is deprecated.
Overview:
Set the PCIbus field of the given VM.
Signature:
void set_PCI_bus (session ref session_ref, VM ref self, string value)
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: setplatform

Overview:
Set the platform field of the given VM.
Signature:
void set_platform (session ref session_ref, VM ref self, (string -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self reference to object
(string -> string) map value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setprotectionpolicy

This message is removed.
Overview:
Set the value of the protectionpolicy field
Signature:
void set_protection_policy (session ref session_ref, VM ref self, VMPP ref value)
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: setPVargs

Overview:
Set the PV/args field of the given VM.
Signature:
void set_PV_args (session ref session_ref, VM ref self, string value)
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: setPVbootloader

Overview:
Set the PV/bootloader field of the given VM.
Signature:
void set_PV_bootloader (session ref session_ref, VM ref self, string value)
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: setPVbootloaderargs

Overview:
Set the PV/bootloaderargs field of the given VM.
Signature:
void set_PV_bootloader_args (session ref session_ref, VM ref self, string value)
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: setPVkernel

Overview:
Set the PV/kernel field of the given VM.
Signature:
void set_PV_kernel (session ref session_ref, VM ref self, string value)
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: setPVlegacyargs

Overview:
Set the PV/legacyargs field of the given VM.
Signature:
void set_PV_legacy_args (session ref session_ref, VM ref self, string value)
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: setPVramdisk

Overview:
Set the PV/ramdisk field of the given VM.
Signature:
void set_PV_ramdisk (session ref session_ref, VM ref self, string value)
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: setrecommendations

Overview:
Set the recommendations field of the given VM.
Signature:
void set_recommendations (session ref session_ref, VM ref self, string value)
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: setshadowmultiplierlive

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)
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: setshutdowndelay

Overview:
Set this VM's shutdown delay in seconds
Signature:
void set_shutdown_delay (session ref session_ref, VM ref self, int value)
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: setsnapshotschedule

Overview:
Set the value of the snapshot schedule field
Signature:
void set_snapshot_schedule (session ref session_ref, VM ref self, VMSS ref value)
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: setstartdelay

Overview:
Set this VM's start delay in seconds
Signature:
void set_start_delay (session ref session_ref, VM ref self, int value)
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: setsuspendSR

Overview:
Set the suspendSR field of the given VM.
Signature:
void set_suspend_SR (session ref session_ref, VM ref self, SR ref value)
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: setsuspendVDI

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)
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: settags

Overview:
Set the tags field of the given VM.
Signature:
void set_tags (session ref session_ref, VM ref self, string set value)
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: setuefimode

Overview:
Set the UEFI mode of a VM
Signature:
string set_uefi_mode (session ref session_ref, VM ref self, vm_uefi_mode mode)
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 varstoresbstate call

RPC name: setuserversion

Overview:
Set the userversion field of the given VM.
Signature:
void set_user_version (session ref session_ref, VM ref self, int value)
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: setVCPUsatstartup

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)
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: setVCPUsmax

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)
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: setVCPUsnumberlive

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)
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: setVCPUsparams

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)
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: setxenstoredata

Overview:
Set the xenstoredata field of the given VM.
Signature:
void set_xenstore_data (session ref session_ref, VM ref self, (string -> string) map value)
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)
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 for example, Copy on Write.
Signature:
VM ref snapshot (session ref session_ref, VM ref vm, string new_name, VDI ref set ignore_vdis)
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: snapshotwithquiesce

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 for example, Copy on Write.
Signature:
VM ref snapshot_with_quiesce (session ref session_ref, VM ref vm, string new_name)
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)
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 (for example, 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: starton

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)
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 (for example, 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)
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: sysprep

Overview:
Pass unattend.xml to Windows sysprep and wait for the VM to shut down as part of a reboot.
Signature:
void sysprep (session ref session_ref, VM ref self, string unattend, float timeout)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
string unattend XML content passed to sysprep
float timeout timeout in seconds for expected reboot
Minimum Role: vm-admin
Return Type: void

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)
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: updateallowedoperations

Overview:
Recomputes the list of acceptable operations
Signature:
void update_allowed_operations (session ref session_ref, VM ref self)
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: updatesecurebootcertificatesonboot

Overview:
Mark or unmark secure boot certificate update on VM boot
Signature:
void update_secureboot_certificates_on_boot (session ref session_ref, VM ref self, bool mark)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM ref self The VM
bool mark If true: mark certificates for update on next boot. If false: remove the mark
Minimum Role: vm-admin
Return Type: void

RPC name: waitmemorytargetlive

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)
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