Class: VM

A virtual machine (or ‘guest’).

Fields for class: VM

RPCs associated with class: VM

RPC name: add_tags

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: void

RPC name: add_to_blocked_operations

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_HVM_boot_params

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_NVRAM

Overview:

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_other_config

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_platform

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_VCPUs_params

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_VCPUs_params_live

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: add_to_xenstore_data

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: assert_agile

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: void

RPC name: assert_can_be_recovered

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: void

Possible Error Codes: VM_IS_PART_OF_AN_APPLIANCE, VM_REQUIRES_SR

RPC name: assert_can_boot_here

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: void

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

RPC name: assert_can_migrate

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-power-admin

Return Type: void

Possible Error Codes: LICENCE_RESTRICTION

RPC name: assert_operation_valid

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: void

RPC name: call_plugin

Overview:

Call an API plugin on this vm

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: string

Result from the plugin

RPC name: checkpoint

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-power-admin

Return Type: VM ref

The reference of the newly created VM.

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

RPC name: clean_reboot

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: clean_shutdown

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: clone

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED, LICENCE_RESTRICTION

RPC name: compute_memory_overhead

Overview:

Computes the virtualization memory overhead of a VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

the virtualization memory overhead of the VM.

RPC name: copy

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED, LICENCE_RESTRICTION

RPC name: copy_bios_strings

Overview:

Copy the BIOS strings from the given host to this VM

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: create

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: VM ref

reference to the newly created object

RPC name: create_new_blob

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-power-admin

Return Type: blob ref

The reference of the blob, needed for populating its data

RPC name: destroy

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: forget_data_source_archives

Overview:

Forget the recorded statistics related to the specified data source

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: get_actions_after_crash

Overview:

Get the actions/after_crash field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: on_crash_behaviour

value of the field

RPC name: get_actions_after_reboot

Overview:

Get the actions/after_reboot field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: on_normal_exit

value of the field

RPC name: get_actions_after_shutdown

Overview:

Get the actions/after_shutdown field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: on_normal_exit

value of the field

RPC name: get_actions_after_softreboot

Overview:

Get the actions/after_softreboot field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: on_softreboot_behavior

value of the field

RPC name: get_affinity

Overview:

Get the affinity field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: host ref

value of the field

RPC name: get_all

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM ref set

references to all objects

RPC name: get_all_records

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

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

records of all objects

RPC name: get_allowed_operations

Overview:

Get the allowed_operations field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: vm_operations set

value of the field

RPC name: get_allowed_VBD_devices

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string set

The allowed values

RPC name: get_allowed_VIF_devices

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string set

The allowed values

RPC name: get_appliance

Overview:

Get the appliance field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM_appliance ref

value of the field

RPC name: get_attached_PCIs

Overview:

Get the attached_PCIs field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: PCI ref set

value of the field

RPC name: get_bios_strings

Overview:

Get the bios_strings field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_blobs

Overview:

Get the blobs field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> blob ref) map

value of the field

RPC name: get_blocked_operations

Overview:

Get the blocked_operations field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (vm_operations -> string) map

value of the field

RPC name: get_boot_record

This message is deprecated.

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM record

A record describing the VM

RPC name: get_by_name_label

Overview:

Get all the VM instances with the given label.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM ref set

references to objects with matching names

RPC name: get_by_uuid

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM ref

reference to the object

RPC name: get_children

Overview:

Get the children field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM ref set

value of the field

RPC name: get_consoles

Overview:

Get the consoles field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: console ref set

value of the field

RPC name: get_cooperative

This message is deprecated.

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

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

RPC name: get_crash_dumps

Overview:

Get the crash_dumps field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: crashdump ref set

value of the field

RPC name: get_current_operations

Overview:

Get the current_operations field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> vm_operations) map

value of the field

RPC name: get_data_sources

Overview:

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: data_source record set

A set of data sources

RPC name: get_domain_type

Overview:

Get the domain_type field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: domain_type

value of the field

RPC name: get_domarch

Overview:

Get the domarch field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_domid

Overview:

Get the domid field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_generation_id

Overview:

Get the generation_id field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_guest_metrics

Overview:

Get the guest_metrics field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM_guest_metrics ref

value of the field

RPC name: get_ha_always_run

This message is deprecated.

Overview:

Get the ha_always_run field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_ha_restart_priority

Overview:

Get the ha_restart_priority field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_hardware_platform_version

Overview:

Get the hardware_platform_version field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_has_vendor_device

Overview:

Get the has_vendor_device field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_HVM_boot_params

Overview:

Get the HVM/boot_params field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_HVM_boot_policy

This message is deprecated.

Overview:

Get the HVM/boot_policy field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_HVM_shadow_multiplier

Overview:

Get the HVM/shadow_multiplier field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: float

value of the field

RPC name: get_is_a_snapshot

Overview:

Get the is_a_snapshot field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_a_template

Overview:

Get the is_a_template field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_control_domain

Overview:

Get the is_control_domain field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_default_template

Overview:

Get the is_default_template field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_snapshot_from_vmpp

This message is removed.

Overview:

Get the is_snapshot_from_vmpp field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_vmss_snapshot

Overview:

Get the is_vmss_snapshot field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_last_boot_CPU_flags

Overview:

Get the last_boot_CPU_flags field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_last_booted_record

Overview:

Get the last_booted_record field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_memory_dynamic_max

Overview:

Get the memory/dynamic_max field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_dynamic_min

Overview:

Get the memory/dynamic_min field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_overhead

Overview:

Get the memory/overhead field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_static_max

Overview:

Get the memory/static_max field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_static_min

Overview:

Get the memory/static_min field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_memory_target

This message is deprecated.

Overview:

Get the memory/target field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_metrics

Overview:

Get the metrics field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM_metrics ref

value of the field

RPC name: get_name_description

Overview:

Get the name/description field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_name_label

Overview:

Get the name/label field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_NVRAM

Overview:

Get the NVRAM field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_order

Overview:

Get the order field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_other_config

Overview:

Get the other_config field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_parent

Overview:

Get the parent field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM ref

value of the field

RPC name: get_PCI_bus

This message is deprecated.

Overview:

Get the PCI_bus field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_pending_guidances

Overview:

Get the pending_guidances field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: update_guidances set

value of the field

RPC name: get_pending_guidances_full

Overview:

Get the pending_guidances_full field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: update_guidances set

value of the field

RPC name: get_pending_guidances_recommended

Overview:

Get the pending_guidances_recommended field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: update_guidances set

value of the field

RPC name: get_platform

Overview:

Get the platform field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_possible_hosts

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: host ref set

The possible hosts

RPC name: get_power_state

Overview:

Get the power_state field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: vm_power_state

value of the field

RPC name: get_protection_policy

This message is deprecated.

Overview:

Get the protection_policy field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VMPP ref

value of the field

RPC name: get_PV_args

Overview:

Get the PV/args field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_bootloader

Overview:

Get the PV/bootloader field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_bootloader_args

Overview:

Get the PV/bootloader_args field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_kernel

Overview:

Get the PV/kernel field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_legacy_args

Overview:

Get the PV/legacy_args field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_PV_ramdisk

Overview:

Get the PV/ramdisk field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_recommendations

Overview:

Get the recommendations field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_record

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM record

all fields from the object

RPC name: get_reference_label

Overview:

Get the reference_label field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_requires_reboot

Overview:

Get the requires_reboot field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_resident_on

Overview:

Get the resident_on field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: host ref

value of the field

RPC name: get_scheduled_to_be_resident_on

Overview:

Get the scheduled_to_be_resident_on field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: host ref

value of the field

RPC name: get_shutdown_delay

Overview:

Get the shutdown_delay field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_snapshot_info

Overview:

Get the snapshot_info field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_snapshot_metadata

Overview:

Get the snapshot_metadata field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_snapshot_of

Overview:

Get the snapshot_of field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM ref

value of the field

RPC name: get_snapshot_schedule

Overview:

Get the snapshot_schedule field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VMSS ref

value of the field

RPC name: get_snapshot_time

Overview:

Get the snapshot_time field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: datetime

value of the field

RPC name: get_snapshots

Overview:

Get the snapshots field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VM ref set

value of the field

RPC name: get_SRs_required_for_recovery

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: SR ref set

refs for SRs required to recover the VM

RPC name: get_start_delay

Overview:

Get the start_delay field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_suspend_SR

Overview:

Get the suspend_SR field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: SR ref

value of the field

RPC name: get_suspend_VDI

Overview:

Get the suspend_VDI field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VDI ref

value of the field

RPC name: get_tags

Overview:

Get the tags field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string set

value of the field

RPC name: get_transportable_snapshot_id

Overview:

Get the transportable_snapshot_id field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_user_version

Overview:

Get the user_version field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_uuid

Overview:

Get the uuid field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_VBDs

Overview:

Get the VBDs field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VBD ref set

value of the field

RPC name: get_VCPUs_at_startup

Overview:

Get the VCPUs/at_startup field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_VCPUs_max

Overview:

Get the VCPUs/max field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_VCPUs_params

Overview:

Get the VCPUs/params field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_version

Overview:

Get the version field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_VGPUs

Overview:

Get the VGPUs field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VGPU ref set

value of the field

RPC name: get_VIFs

Overview:

Get the VIFs field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VIF ref set

value of the field

RPC name: get_VTPMs

Overview:

Get the VTPMs field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VTPM ref set

value of the field

RPC name: get_VUSBs

Overview:

Get the VUSBs field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: VUSB ref set

value of the field

RPC name: get_xenstore_data

Overview:

Get the xenstore_data field of the given VM.

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: hard_reboot

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: hard_shutdown

Overview:

Stop executing the specified VM without attempting a clean shutdown.

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: import

Overview:

Import an XVA from a URI

Signature:

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

Arguments:

Minimum Role: pool-operator

Return Type: VM ref set

Imported VM reference

RPC name: import_convert

Overview:

Import using a conversion service.

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: maximise_memory

Overview:

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

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: int

The maximum possible static-max

RPC name: migrate_send

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-power-admin

Return Type: VM ref

The reference of the newly created VM in the destination pool

Possible Error Codes: VM_BAD_POWER_STATE, LICENCE_RESTRICTION

RPC name: pause

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OTHER_OPERATION_IN_PROGRESS, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: pool_migrate

Overview:

Migrate a VM to another Host.

Signature:

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

Arguments:

Minimum Role: client-cert

Return Type: void

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

RPC name: power_state_reset

Overview:

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

Signature:

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

Arguments:

Minimum Role: pool-operator

Return Type: void

RPC name: provision

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, SR_FULL, OPERATION_NOT_ALLOWED, LICENCE_RESTRICTION

RPC name: query_data_source

Overview:

Query the latest value of the specified data source

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: float

The latest value, averaged over the last 5 seconds

RPC name: query_services

Overview:

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

Signature:

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

Arguments:

Minimum Role: pool-admin

Return Type: (string -> string) map

map of service type to name

RPC name: record_data_source

Overview:

Start recording the specified data source

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: recover

Overview:

Recover the VM

Signature:

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

Arguments:

Minimum Role: read-only

Return Type: void

RPC name: remove_from_blocked_operations

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_HVM_boot_params

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_NVRAM

Overview:

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_other_config

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_platform

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_VCPUs_params

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: remove_from_xenstore_data

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-admin

Return Type: void

RPC name: remove_tags

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: void

RPC name: restart_device_models

Overview:

Restart device models of the VM

Signature:

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

Arguments:

Minimum Role: client-cert

Return Type: void

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

RPC name: resume

Overview:

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

Signature:

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

Arguments:

Minimum Role: vm-operator

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: resume_on

Overview:

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

Signature:

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

Arguments:

Minimum Role: client-cert

Return Type: void

Possible Error Codes: VM_BAD_POWER_STATE, OPERATION_NOT_ALLOWED, VM_IS_TEMPLATE

RPC name: retrieve_wlb_recommendations

Overview:

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

Signature:

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

Arguments: