Xapi Project Docs

Class: VM

A virtual machine (or 'guest').

Enums

vm_power_state

update_guidances

on_softreboot_behavior

on_normal_exit

on_crash_behaviour

domain_type

vm_uefi_mode

vm_secureboot_readiness

vm_operations

Values:	snapshot	refers to the operation "snapshot"
	clone	refers to the operation "clone"
	copy	refers to the operation "copy"
	create_template	refers to the operation "create_template"
	revert	refers to the operation "revert"
	checkpoint	refers to the operation "checkpoint"
	snapshot_with_quiesce	refers to the operation "snapshot_with_quiesce"
	provision	refers to the operation "provision"
	start	refers to the operation "start"
	start_on	refers to the operation "start_on"
	pause	refers to the operation "pause"
	unpause	refers to the operation "unpause"
	clean_shutdown	refers to the operation "clean_shutdown"
	clean_reboot	refers to the operation "clean_reboot"
	hard_shutdown	refers to the operation "hard_shutdown"
	power_state_reset	refers to the operation "power_state_reset"
	hard_reboot	refers to the operation "hard_reboot"
	suspend	refers to the operation "suspend"
	csvm	refers to the operation "csvm"
	resume	refers to the operation "resume"
	resume_on	refers to the operation "resume_on"
	pool_migrate	refers to the operation "pool_migrate"
	migrate_send	refers to the operation "migrate_send"
	get_boot_record	refers to the operation "get_boot_record"
	send_sysrq	refers to the operation "send_sysrq"
	send_trigger	refers to the operation "send_trigger"
	query_services	refers to the operation "query_services"
	shutdown	refers to the operation "shutdown"
	call_plugin	refers to the operation "call_plugin"
	changing_memory_live	Changing the memory settings
	awaiting_memory_live	Waiting for the memory settings to change
	changing_dynamic_range	Changing the memory dynamic range
	changing_static_range	Changing the memory static range
	changing_memory_limits	Changing the memory limits
	changing_shadow_memory	Changing the shadow memory for a halted VM.
	changing_shadow_memory_live	Changing the shadow memory for a running VM.
	changing_VCPUs	Changing VCPU settings for a halted VM.
	changing_VCPUs_live	Changing VCPU settings for a running VM.
	changing_NVRAM	Changing NVRAM for a halted VM.
	assert_operation_valid
	data_source_op	Add, remove, query or list data sources
	update_allowed_operations
	make_into_template	Turning this VM into a template
	import	importing a VM from a network stream
	export	exporting a VM to a network stream
	metadata_export	exporting VM metadata to a network stream
	reverting	Reverting the VM to a previous snapshotted state
	destroy	refers to the act of uninstalling the VM
	create_vtpm	Creating and adding a VTPM to this VM
	sysprep	Performing a Windows sysprep on this VM

Fields

(string → string) map HVM_boot_params [RW]

Deprecated

string HVM_boot_policy [RO/constructor]

float HVM_shadow_multiplier [RO/constructor]

(string → string) map NVRAM [RO/constructor]

Deprecated

string PCI_bus [RW]

string PV_args [RW]

string PV_bootloader [RW]

string PV_bootloader_args [RW]

string PV_kernel [RW]

string PV_legacy_args [RW]

string PV_ramdisk [RW]

VBD ref set VBDs [RO/runtime]

int VCPUs_at_startup [RO/constructor]

int VCPUs_max [RO/constructor]

(string → string) map VCPUs_params [RW]

VGPU ref set VGPUs [RO/runtime]

VIF ref set VIFs [RO/runtime]

VTPM ref set VTPMs [RO/runtime]

VUSB ref set VUSBs [RO/runtime]

enum on_crash_behaviour actions_after_crash [RO/constructor]

enum on_normal_exit actions_after_reboot [RW]

enum on_normal_exit actions_after_shutdown [RW]

Prototype

enum on_softreboot_behavior actions_after_softreboot [RW]

host ref affinity [RW]

enum vm_operations set allowed_operations [RO/runtime]

VM_appliance ref appliance [RO/constructor]

PCI ref set attached_PCIs [RO/runtime]

(string → string) map bios_strings [RO/runtime]

(string → blob ref) map blobs [RO/runtime]

(enum vm_operations → string) map blocked_operations [RO/constructor]

VM ref set children [RO/runtime]

console ref set consoles [RO/runtime]

crashdump ref set crash_dumps [RO/runtime]

(string → enum vm_operations) map current_operations [RO/runtime]

enum domain_type domain_type [RO/constructor]

string domarch [RO/runtime]

int domid [RO/runtime]

string generation_id [RO/constructor]

Prototype

VM_group ref set groups [RO/runtime]

VM_guest_metrics ref guest_metrics [RO/runtime]

Deprecated

bool ha_always_run [RO/constructor]

string ha_restart_priority [RO/constructor]

int hardware_platform_version [RW]

bool has_vendor_device [RO/constructor]

bool is_a_snapshot [RO/runtime]

bool is_a_template [RW]

bool is_control_domain [RO/runtime]

bool is_default_template [RO/runtime]

Removed

bool is_snapshot_from_vmpp [RO/constructor]

bool is_vmss_snapshot [RO/constructor]

(string → string) map last_boot_CPU_flags [RO/constructor]

string last_booted_record [RO/constructor]

int memory_dynamic_max [RO/constructor]

int memory_dynamic_min [RO/constructor]

int memory_overhead [RO/runtime]

int memory_static_max [RO/constructor]

int memory_static_min [RO/constructor]

Deprecated

int memory_target [RO/constructor]

VM_metrics ref metrics [RO/runtime]

string name_description [RW]

string name_label [RW]

int order [RO/constructor]

(string → string) map other_config [RW]

VM ref parent [RO/runtime]

enum update_guidances set pending_guidances [RO/runtime]

Prototype

enum update_guidances set pending_guidances_full [RO/runtime]

Prototype

enum update_guidances set pending_guidances_recommended [RO/runtime]

(string → string) map platform [RW]

enum vm_power_state power_state [RO/constructor]

Deprecated

VMPP ref protection_policy [RO/constructor]

string recommendations [RW]

string reference_label [RO/constructor]

bool requires_reboot [RO/runtime]

host ref resident_on [RO/runtime]

host ref scheduled_to_be_resident_on [RO/runtime]

int shutdown_delay [RO/constructor]

(string → string) map snapshot_info [RO/runtime]

string snapshot_metadata [RO/runtime]

VM ref snapshot_of [RO/runtime]

VMSS ref snapshot_schedule [RO/constructor]

datetime snapshot_time [RO/runtime]

VM ref set snapshots [RO/runtime]

int start_delay [RO/constructor]

SR ref suspend_SR [RW]

VDI ref suspend_VDI [RO/constructor]

string set tags [RW]

string transportable_snapshot_id [RO/runtime]

int user_version [RW]

string uuid [RO/runtime]

int version [RO/constructor]

(string → string) map xenstore_data [RW]

Messages

void add_tags (session ref, VM ref, string)

void add_to_HVM_boot_params (session ref, VM ref, string, string)

void add_to_NVRAM (session ref, VM ref, string, string)

void add_to_VCPUs_params (session ref, VM ref, string, string)

void add_to_VCPUs_params_live (session ref, VM ref, string, string)

void add_to_blocked_operations (session ref, VM ref, enum vm_operations, string)

void add_to_other_config (session ref, VM ref, string, string)

void add_to_platform (session ref, VM ref, string, string)

void add_to_xenstore_data (session ref, VM ref, string, string)

void assert_agile (session ref, VM ref)

void assert_can_be_recovered (session ref, VM ref, session ref)

void assert_can_boot_here (session ref, VM ref, host ref)

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

Parameters:	session ref session_id	Reference to a valid session
	VM ref self	The VM
	host ref host	The host
Minimum role:	read-only
Errors:	HOST_NOT_ENOUGH_FREE_MEMORY	Not enough server memory is available to perform this operation.
	HOST_NOT_ENOUGH_PCPUS	The host does not have enough pCPUs to run the VM. It needs at least as many as the VM has vCPUs.
	NETWORK_SRIOV_INSUFFICIENT_CAPACITY	There is insufficient capacity for VF reservation
	HOST_NOT_LIVE	This operation cannot be completed as the server is not live.
	HOST_DISABLED	The specified server is disabled.
	HOST_CANNOT_ATTACH_NETWORK	Server cannot attach network (in the case of NIC bonding, this may be because attaching the network on this server would require other networks - that are currently active - to be taken down).
	VM_HVM_REQUIRED	HVM is required for this operation
	VM_REQUIRES_GPU	You attempted to run a VM on a host which doesn't have a pGPU available in the GPU group needed by the VM. The VM has a vGPU attached to this GPU group.
	VM_REQUIRES_IOMMU	You attempted to run a VM on a host which doesn't have I/O virtualization (IOMMU/VT-d) enabled, which is needed by the VM.
	VM_REQUIRES_NETWORK	You attempted to run a VM on a host which doesn't have a PIF on a Network needed by the VM. The VM has at least one VIF attached to the Network.
	VM_REQUIRES_SR	You attempted to run a VM on a host which doesn't have access to an SR needed by the VM. The VM has at least one VBD attached to a VDI in the SR.
	VM_REQUIRES_VGPU	You attempted to run a VM on a host on which the vGPU required by the VM cannot be allocated on any pGPUs in the GPU_group needed by the VM.
	VM_HOST_INCOMPATIBLE_VERSION	This VM operation cannot be performed on an older-versioned host during an upgrade.
	VM_HOST_INCOMPATIBLE_VIRTUAL_HARDWARE_PLATFORM_VERSION	You attempted to run a VM on a host that cannot provide the VM's required Virtual Hardware Platform version.
	INVALID_VALUE	The value given is invalid
	MEMORY_CONSTRAINT_VIOLATION	The dynamic memory range does not satisfy the following constraint.
	OPERATION_NOT_ALLOWED	You attempted an operation that was not allowed.
	VALUE_NOT_SUPPORTED	You attempted to set a value that is not supported by this implementation. The fully-qualified field name and the value that you tried to set are returned. Also returned is a developer-only diagnostic reason.
	VM_INCOMPATIBLE_WITH_THIS_HOST	The VM is incompatible with the CPU features of this host.
Published in:	XenServer 4.0 (rio)
Changed in:	Citrix Hypervisor 8.1 (quebec)	Does additional compatibility checks when VM powerstate is not halted (e.g. CPUID). Use this before calling VM.resume or VM.pool_migrate.

void assert_can_migrate (session ref, VM ref, (string → string) map, bool, (VDI ref → SR ref) map, (VIF ref → network ref) map, (string → string) map, (VGPU ref → GPU_group ref) map)

void assert_operation_valid (session ref, VM ref, enum vm_operations)

Prototype

string call_host_plugin (session ref, VM ref, string, string, (string → string) map)

string call_plugin (session ref, VM ref, string, string, (string → string) map)

VM ref checkpoint (session ref, VM ref, string)

void clean_reboot (session ref, VM ref)

void clean_shutdown (session ref, VM ref)

VM ref clone (session ref, VM ref, string)

int compute_memory_overhead (session ref, VM ref)

VM ref copy (session ref, VM ref, string, SR ref)

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.

Parameters:	session ref session_id	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
Result:	The reference of the newly created VM.
Errors:	VM_BAD_POWER_STATE	You attempted an operation on a VM that was not in an appropriate power state at the time; for example, you attempted to start a VM that was already running. The parameters returned are the VM's handle, and the expected and actual VM state at the time of the call.
	SR_FULL	The SR is full. Requested new size exceeds the maximum size
	OPERATION_NOT_ALLOWED	You attempted an operation that was not allowed.
	LICENCE_RESTRICTION	This operation is not allowed because your license lacks a needed feature. Please contact your support representative.
Published in:	XenServer 4.0 (rio)	Copies a VM to an SR. There must be a host that can see both the source and destination SRs simultaneously
Extended in:	XenServer 5.6 FP1 (cowley)	The copy can now be performed between any two SRs.

void copy_bios_strings (session ref, VM ref, host ref)

VM ref create (session ref, VM record)

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. The constructor args are: name_label, name_description, power_state, user_version*, is_a_template*, suspend_VDI, affinity*, memory_target, memory_static_max*, memory_dynamic_max*, memory_dynamic_min*, memory_static_min*, VCPUs_params*, VCPUs_max*, VCPUs_at_startup*, actions_after_softreboot, actions_after_shutdown*, actions_after_reboot*, actions_after_crash*, PV_bootloader*, PV_kernel*, PV_ramdisk*, PV_args*, PV_bootloader_args*, PV_legacy_args*, HVM_boot_policy*, HVM_boot_params*, HVM_shadow_multiplier, platform*, PCI_bus*, other_config*, last_boot_CPU_flags, last_booted_record, recommendations*, xenstore_data, ha_always_run, ha_restart_priority, tags, blocked_operations, protection_policy, is_snapshot_from_vmpp, snapshot_schedule, is_vmss_snapshot, appliance, start_delay, shutdown_delay, order, suspend_SR, version, generation_id, hardware_platform_version, has_vendor_device, reference_label, domain_type, NVRAM (* = non-optional).

Parameters:	session ref session_id	Reference to a valid session
	VM record args	All constructor arguments
Minimum role:	vm-admin
Result:	reference to the newly created object
Published in:	XenServer 4.0 (rio)
Changed in:	XAPI 1.257.0 (1.257.0)	possibility to create a VM in suspended mode with a suspend_VDI set

blob ref create_new_blob (session ref, VM ref, string, string, bool)

void destroy (session ref, VM ref)

void forget_data_source_archives (session ref, VM ref, string)

(string → string) map get_HVM_boot_params (session ref, VM ref)

Deprecated

string get_HVM_boot_policy (session ref, VM ref)

float get_HVM_shadow_multiplier (session ref, VM ref)

(string → string) map get_NVRAM (session ref, VM ref)

Deprecated

string get_PCI_bus (session ref, VM ref)

string get_PV_args (session ref, VM ref)

string get_PV_bootloader (session ref, VM ref)

string get_PV_bootloader_args (session ref, VM ref)

string get_PV_kernel (session ref, VM ref)

string get_PV_legacy_args (session ref, VM ref)

string get_PV_ramdisk (session ref, VM ref)

SR ref set get_SRs_required_for_recovery (session ref, VM ref, session ref)

VBD ref set get_VBDs (session ref, VM ref)

int get_VCPUs_at_startup (session ref, VM ref)

int get_VCPUs_max (session ref, VM ref)

(string → string) map get_VCPUs_params (session ref, VM ref)

VGPU ref set get_VGPUs (session ref, VM ref)

VIF ref set get_VIFs (session ref, VM ref)

VTPM ref set get_VTPMs (session ref, VM ref)

VUSB ref set get_VUSBs (session ref, VM ref)

enum on_crash_behaviour get_actions_after_crash (session ref, VM ref)

enum on_normal_exit get_actions_after_reboot (session ref, VM ref)

enum on_normal_exit get_actions_after_shutdown (session ref, VM ref)

Prototype

enum on_softreboot_behavior get_actions_after_softreboot (session ref, VM ref)

host ref get_affinity (session ref, VM ref)

VM ref set get_all (session ref)

(VM ref → VM record) map get_all_records (session ref)

string set get_allowed_VBD_devices (session ref, VM ref)

string set get_allowed_VIF_devices (session ref, VM ref)

enum vm_operations set get_allowed_operations (session ref, VM ref)

VM_appliance ref get_appliance (session ref, VM ref)

PCI ref set get_attached_PCIs (session ref, VM ref)

(string → string) map get_bios_strings (session ref, VM ref)

(string → blob ref) map get_blobs (session ref, VM ref)

(enum vm_operations → string) map get_blocked_operations (session ref, VM ref)

Deprecated

VM record get_boot_record (session ref, VM ref)

VM ref set get_by_name_label (session ref, string)

VM ref get_by_uuid (session ref, string)

VM ref set get_children (session ref, VM ref)

console ref set get_consoles (session ref, VM ref)

Deprecated

bool get_cooperative (session ref, VM ref)

crashdump ref set get_crash_dumps (session ref, VM ref)

(string → enum vm_operations) map get_current_operations (session ref, VM ref)

data_source record set get_data_sources (session ref, VM ref)

enum domain_type get_domain_type (session ref, VM ref)

string get_domarch (session ref, VM ref)

int get_domid (session ref, VM ref)

string get_generation_id (session ref, VM ref)

Prototype

VM_group ref set get_groups (session ref, VM ref)

VM_guest_metrics ref get_guest_metrics (session ref, VM ref)

Deprecated

bool get_ha_always_run (session ref, VM ref)

string get_ha_restart_priority (session ref, VM ref)

int get_hardware_platform_version (session ref, VM ref)

bool get_has_vendor_device (session ref, VM ref)

bool get_is_a_snapshot (session ref, VM ref)

bool get_is_a_template (session ref, VM ref)

bool get_is_control_domain (session ref, VM ref)

bool get_is_default_template (session ref, VM ref)

Removed

bool get_is_snapshot_from_vmpp (session ref, VM ref)

bool get_is_vmss_snapshot (session ref, VM ref)

(string → string) map get_last_boot_CPU_flags (session ref, VM ref)

string get_last_booted_record (session ref, VM ref)

int get_memory_dynamic_max (session ref, VM ref)

int get_memory_dynamic_min (session ref, VM ref)

int get_memory_overhead (session ref, VM ref)

int get_memory_static_max (session ref, VM ref)

int get_memory_static_min (session ref, VM ref)

Deprecated

int get_memory_target (session ref, VM ref)

VM_metrics ref get_metrics (session ref, VM ref)

string get_name_description (session ref, VM ref)

string get_name_label (session ref, VM ref)

int get_order (session ref, VM ref)

(string → string) map get_other_config (session ref, VM ref)

VM ref get_parent (session ref, VM ref)

enum update_guidances set get_pending_guidances (session ref, VM ref)

Prototype

enum update_guidances set get_pending_guidances_full (session ref, VM ref)

Prototype

enum update_guidances set get_pending_guidances_recommended (session ref, VM ref)

(string → string) map get_platform (session ref, VM ref)

host ref set get_possible_hosts (session ref, VM ref)

enum vm_power_state get_power_state (session ref, VM ref)

Deprecated

VMPP ref get_protection_policy (session ref, VM ref)

string get_recommendations (session ref, VM ref)

VM record get_record (session ref, VM ref)

string get_reference_label (session ref, VM ref)

bool get_requires_reboot (session ref, VM ref)

host ref get_resident_on (session ref, VM ref)

host ref get_scheduled_to_be_resident_on (session ref, VM ref)

Prototype

enum vm_secureboot_readiness get_secureboot_readiness (session ref, VM ref)

int get_shutdown_delay (session ref, VM ref)

(string → string) map get_snapshot_info (session ref, VM ref)

string get_snapshot_metadata (session ref, VM ref)

VM ref get_snapshot_of (session ref, VM ref)

VMSS ref get_snapshot_schedule (session ref, VM ref)

datetime get_snapshot_time (session ref, VM ref)

VM ref set get_snapshots (session ref, VM ref)

int get_start_delay (session ref, VM ref)

SR ref get_suspend_SR (session ref, VM ref)

VDI ref get_suspend_VDI (session ref, VM ref)

string set get_tags (session ref, VM ref)

string get_transportable_snapshot_id (session ref, VM ref)

int get_user_version (session ref, VM ref)

string get_uuid (session ref, VM ref)

int get_version (session ref, VM ref)

(string → string) map get_xenstore_data (session ref, VM ref)

void hard_reboot (session ref, VM ref)

void hard_shutdown (session ref, VM ref)

VM ref set import (session ref, string, SR ref, bool, bool)

void import_convert (session ref, string, string, string, SR ref, (string → string) map)

int maximise_memory (session ref, VM ref, int, bool)

VM ref migrate_send (session ref, VM ref, (string → string) map, bool, (VDI ref → SR ref) map, (VIF ref → network ref) map, (string → string) map, (VGPU ref → GPU_group ref) map)

void pause (session ref, VM ref)

void pool_migrate (session ref, VM ref, host ref, (string → string) map)

void power_state_reset (session ref, VM ref)

void provision (session ref, VM ref)

float query_data_source (session ref, VM ref, string)

(string → string) map query_services (session ref, VM ref)

void record_data_source (session ref, VM ref, string)

void recover (session ref, VM ref, session ref, bool)

void remove_from_HVM_boot_params (session ref, VM ref, string)

void remove_from_NVRAM (session ref, VM ref, string)

void remove_from_VCPUs_params (session ref, VM ref, string)

void remove_from_blocked_operations (session ref, VM ref, enum vm_operations)

void remove_from_other_config (session ref, VM ref, string)

void remove_from_platform (session ref, VM ref, string)

void remove_from_xenstore_data (session ref, VM ref, string)

void remove_tags (session ref, VM ref, string)

Prototype

void restart_device_models (session ref, VM ref)

void resume (session ref, VM ref, bool, bool)

void resume_on (session ref, VM ref, host ref, bool, bool)

(host ref → string set) map retrieve_wlb_recommendations (session ref, VM ref)

void revert (session ref, VM ref)

void send_sysrq (session ref, VM ref, string)

void send_trigger (session ref, VM ref, string)

void set_HVM_boot_params (session ref, VM ref, (string → string) map)

Deprecated

void set_HVM_boot_policy (session ref, VM ref, string)

void set_HVM_shadow_multiplier (session ref, VM ref, float)

void set_NVRAM (session ref, VM ref, (string → string) map)

Deprecated

void set_PCI_bus (session ref, VM ref, string)

void set_PV_args (session ref, VM ref, string)

void set_PV_bootloader (session ref, VM ref, string)

void set_PV_bootloader_args (session ref, VM ref, string)

void set_PV_kernel (session ref, VM ref, string)

void set_PV_legacy_args (session ref, VM ref, string)

void set_PV_ramdisk (session ref, VM ref, string)

void set_VCPUs_at_startup (session ref, VM ref, int)

void set_VCPUs_max (session ref, VM ref, int)

void set_VCPUs_number_live (session ref, VM ref, int)

void set_VCPUs_params (session ref, VM ref, (string → string) map)

void set_actions_after_crash (session ref, VM ref, enum on_crash_behaviour)

void set_actions_after_reboot (session ref, VM ref, enum on_normal_exit)

void set_actions_after_shutdown (session ref, VM ref, enum on_normal_exit)

Prototype

void set_actions_after_softreboot (session ref, VM ref, enum on_softreboot_behavior)

void set_affinity (session ref, VM ref, host ref)

void set_appliance (session ref, VM ref, VM_appliance ref)

void set_bios_strings (session ref, VM ref, (string → string) map)

void set_blocked_operations (session ref, VM ref, (enum vm_operations → string) map)

void set_domain_type (session ref, VM ref, enum domain_type)

Prototype

void set_groups (session ref, VM ref, VM_group ref set)

Deprecated

void set_ha_always_run (session ref, VM ref, bool)

void set_ha_restart_priority (session ref, VM ref, string)

void set_hardware_platform_version (session ref, VM ref, int)

void set_has_vendor_device (session ref, VM ref, bool)

void set_is_a_template (session ref, VM ref, bool)

void set_memory (session ref, VM ref, int)

void set_memory_dynamic_max (session ref, VM ref, int)

void set_memory_dynamic_min (session ref, VM ref, int)

void set_memory_dynamic_range (session ref, VM ref, int, int)

void set_memory_limits (session ref, VM ref, int, int, int, int)

void set_memory_static_max (session ref, VM ref, int)

void set_memory_static_min (session ref, VM ref, int)

void set_memory_static_range (session ref, VM ref, int, int)

Deprecated

void set_memory_target_live (session ref, VM ref, int)

void set_name_description (session ref, VM ref, string)

void set_name_label (session ref, VM ref, string)

void set_order (session ref, VM ref, int)

void set_other_config (session ref, VM ref, (string → string) map)

void set_platform (session ref, VM ref, (string → string) map)

Removed

void set_protection_policy (session ref, VM ref, VMPP ref)

void set_recommendations (session ref, VM ref, string)

void set_shadow_multiplier_live (session ref, VM ref, float)

void set_shutdown_delay (session ref, VM ref, int)

void set_snapshot_schedule (session ref, VM ref, VMSS ref)

void set_start_delay (session ref, VM ref, int)

void set_suspend_SR (session ref, VM ref, SR ref)

void set_suspend_VDI (session ref, VM ref, VDI ref)

void set_tags (session ref, VM ref, string set)

Prototype

string set_uefi_mode (session ref, VM ref, enum vm_uefi_mode)

void set_user_version (session ref, VM ref, int)

void set_xenstore_data (session ref, VM ref, (string → string) map)

void shutdown (session ref, VM ref)

VM ref snapshot (session ref, VM ref, string, VDI ref set)

Removed

VM ref snapshot_with_quiesce (session ref, VM ref, string)

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

Parameters:	session ref session_id	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
Result:	The reference of the newly created VM.
Errors:	VM_BAD_POWER_STATE	You attempted an operation on a VM that was not in an appropriate power state at the time; for example, you attempted to start a VM that was already running. The parameters returned are the VM's handle, and the expected and actual VM state at the time of the call.
	SR_FULL	The SR is full. Requested new size exceeds the maximum size
	OPERATION_NOT_ALLOWED	You attempted an operation that was not allowed.
	VM_SNAPSHOT_WITH_QUIESCE_FAILED	The quiesced-snapshot operation failed for an unexpected reason
	VM_SNAPSHOT_WITH_QUIESCE_TIMEOUT	The VSS plug-in has timed out
	VM_SNAPSHOT_WITH_QUIESCE_PLUGIN_DEOS_NOT_RESPOND	The VSS plug-in cannot be contacted
	VM_SNAPSHOT_WITH_QUIESCE_NOT_SUPPORTED	The VSS plug-in is not installed on this virtual machine
Published in:	XenServer 5.0 (orlando)
Deprecated in:	Citrix Hypervisor 8.1 (quebec)	Dummy transition
Removed in:	Citrix Hypervisor 8.1 (quebec)	VSS support has been removed

void start (session ref, VM ref, bool, bool)

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

Parameters:	session ref session_id	Reference to a valid session
	VM ref vm	The VM to start
	bool start_paused	Instantiate VM in paused state if set to true.
	bool force	Attempt to force the VM to start. If this flag is false then the VM may fail pre-boot safety checks (e.g. if the CPU the VM last booted on looks substantially different to the current one)
Minimum role:	vm-operator
Errors:	VM_BAD_POWER_STATE	You attempted an operation on a VM that was not in an appropriate power state at the time; for example, you attempted to start a VM that was already running. The parameters returned are the VM's handle, and the expected and actual VM state at the time of the call.
	VM_HVM_REQUIRED	HVM is required for this operation
	VM_IS_TEMPLATE	The operation attempted is not valid for a template VM
	OTHER_OPERATION_IN_PROGRESS	Another operation involving the object is currently in progress
	OPERATION_NOT_ALLOWED	You attempted an operation that was not allowed.
	BOOTLOADER_FAILED	The bootloader returned an error
	UNKNOWN_BOOTLOADER	The requested bootloader is unknown
	NO_HOSTS_AVAILABLE	There were no servers available to complete the specified operation.
	LICENCE_RESTRICTION	This operation is not allowed because your license lacks a needed feature. Please contact your support representative.
Published in:	XenServer 4.0 (rio)	Start the specified VM. This function can only be called with the VM is in the Halted State.

void start_on (session ref, VM ref, host ref, bool, bool)

void suspend (session ref, VM ref)

Prototype

void sysprep (session ref, VM ref, string)

void unpause (session ref, VM ref)

void update_allowed_operations (session ref, VM ref)

Deprecated

void wait_memory_target_live (session ref, VM ref)

Values:	Halted	VM is offline and not using any resources
	Paused	All resources have been allocated but the VM itself is paused and its vCPUs are not running
	Running	Running
	Suspended	VM state has been saved to disk and it is nolonger running. Note that disks remain in-use while the VM is suspended.

Values:	reboot_host	Indicates the updated host should reboot as soon as possible
	reboot_host_on_livepatch_failure	Indicates the updated host should reboot as soon as possible since one or more livepatch(es) failed to be applied.
	reboot_host_on_kernel_livepatch_failure	Indicates the updated host should reboot as soon as possible since one or more kernel livepatch(es) failed to be applied.
	reboot_host_on_xen_livepatch_failure	Indicates the updated host should reboot as soon as possible since one or more xen livepatch(es) failed to be applied.
	restart_toolstack	Indicates the Toolstack running on the updated host should restart as soon as possible
	restart_device_model	Indicates the device model of a running VM should restart as soon as possible
	restart_vm	Indicates the VM should restart as soon as possible

Values:	soft_reboot	perform soft-reboot
	destroy	destroy the VM state
	restart	restart the VM
	preserve	leave the VM paused

Values:	destroy	destroy the VM state
	coredump_and_destroy	record a coredump and then destroy the VM state
	restart	restart the VM
	coredump_and_restart	record a coredump and then restart the VM
	preserve	leave the crashed VM paused
	rename_restart	rename the crashed VM and start a new copy

Values:	hvm	HVM; Fully Virtualised
	pv	PV: Paravirtualised
	pv_in_pvh	PV inside a PVH container
	pvh	PVH
	unspecified	Not specified or unknown domain type

Values:	setup	clears a VM's EFI variables related to Secure Boot and places it into Setup Mode
	user	resets a VM's EFI variables related to Secure Boot to the defaults, placing it into User Mode

Values:	not_supported	VM's firmware is not UEFI
	disabled	Secureboot is disabled on this VM
	first_boot	Secured boot is enabled on this VM and its NVRAM.EFI-variables are empty
	ready	Secured boot is enabled on this VM and PK, KEK, db and dbx are defined in its EFI variables
	ready_no_dbx	Secured boot is enabled on this VM and PK, KEK, db but not dbx are defined in its EFI variables
	setup_mode	Secured boot is enabled on this VM and PK is not defined in its EFI variables
	certs_incomplete	Secured boot is enabled on this VM and the certificates defined in its EFI variables are incomplete

Default value:	1.
Published in:	XenServer 4.1 (miami)	multiplier applied to the amount of shadow that will be made available to the guest

Published in:	XenServer 4.0 (rio)	PCI bus path for pass-through devices
Deprecated in:	XenServer 6.0 (boston)	Field was never used

Default value:	OpaqueRef:NULL
Published in:	XenServer 4.0 (rio)	the appliance to which this VM belongs

Default value:	{}
Published in:	XenServer 5.6 (midnight-ride)	BIOS strings

Default value:	unspecified
Prototyped in:	XenServer 7.4 (jura)	Internal-only field; not yet in the public API
Published in:	XenServer 7.5 (kolkata)	The field is now valid

Default value:	"0:0"
Published in:	XenServer 6.2 (clearwater)	Generation ID of the VM

Default value:	false
Published in:	XenServer 5.0 (orlando)	if true then the system will attempt to keep the VM running as much as possible.
Deprecated in:	XenServer 6.0 (boston)

Default value:	0
Published in:	XenServer 6.5 SP1 (cream)	The host virtual hardware platform version the VM can run on

Default value:	true
Published in:	XenServer 7.0 (dundee)
Changed in:	XAPI 24.14.0 (24.14.0)	New default and not consulting Pool.policy_no_vendor_device

Default value:	Null
Published in:	XenServer 5.6 (midnight-ride)	Ref pointing to the parent of this VM

Default value:	{}
Published in:	XAPI 1.303.0 (1.303.0)	The set of pending mandatory guidances after applying updates, which must be applied, as otherwise there may be e.g. VM failures

Default value:	""
Published in:	XenServer 7.1 (ely)	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.

Default value:	19700101T00:00:00Z
Published in:	XenServer 5.0 (orlando)	Date/time when this snapshot was created.

Class: VM

Enums

Fields

Messages Hide implicit

Classes

Messages