/Classes/VM

Classes / VM / index.html

A virtual machine (or 'guest').

Fields

string uuid
Unique identifier/object reference
Set[enum vm_operations] allowed_operations
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.
Map[string,enum vm_operations] current_operations
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
enum vm_power_state power_state
Current power state of the machine
string name_label
a human-readable name
string name_description
a notes field containg human-readable description
int user_version
a user version number for this machine
bool is_a_template
true if this is a template. Template VMs can never be started, they are used only for cloning other VMs
VDI suspend_VDI
The VDI that a suspend image is stored on. (Only has meaning if VM is currently suspended)
host resident_on
the host the VM is currently resident on
host scheduled_to_be_resident_on
the host on which the VM is due to be started/resumed/migrated. This acts as a memory reservation indicator
host affinity
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. Implementations are free to ignore this field.
int memory_overhead
Virtualization memory overhead (bytes).
int memory_target
[deprecated]Dynamically-set memory target (bytes). The value of this field indicates the current target for memory available to this VM.
int memory_static_max
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.
int memory_dynamic_max
Dynamic maximum (bytes)
int memory_dynamic_min
Dynamic minimum (bytes)
int memory_static_min
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.
Map[string,string] VCPUs_params
configuration parameters for the selected VCPU policy
int VCPUs_max
Max number of VCPUs
int VCPUs_at_startup
Boot number of VCPUs
enum on_normal_exit actions_after_shutdown
action to take after the guest has shutdown itself
enum on_normal_exit actions_after_reboot
action to take after the guest has rebooted itself
enum on_crash_behaviour actions_after_crash
action to take if the guest crashes
Set[console] consoles
virtual console devices
Set[VIF] VIFs
virtual network interfaces
Set[VBD] VBDs
virtual block devices
Set[crashdump] crash_dumps
crash dumps associated with this VM
Set[VTPM] VTPMs
virtual TPMs
string PV_bootloader
name of or path to bootloader
string PV_kernel
path to the kernel
string PV_ramdisk
path to the initrd
string PV_args
kernel command-line arguments
string PV_bootloader_args
miscellaneous arguments for the bootloader
string PV_legacy_args
to make Zurich guests boot
string HVM_boot_policy
HVM boot policy
Map[string,string] HVM_boot_params
HVM boot params
float HVM_shadow_multiplier
multiplier applied to the amount of shadow that will be made available to the guest
Map[string,string] platform
platform-specific configuration
string PCI_bus
PCI bus path for pass-through devices
Map[string,string] other_config
additional configuration
int domid
domain ID (if available, -1 otherwise)
string domarch
Domain architecture (if available, null string otherwise)
Map[string,string] last_boot_CPU_flags
describes the CPU flags on which the VM was last booted
bool is_control_domain
true if this is a control domain (domain 0 or a driver domain)
VM_metrics metrics
metrics associated with this VM
VM_guest_metrics guest_metrics
metrics associated with the running guest
string last_booted_record
marshalled value containing VM record at time of last boot, updated dynamically to reflect the runtime state of the domain
string recommendations
An XML specification of recommended values and ranges for properties of this VM
Map[string,string] xenstore_data
data to be inserted into the xenstore tree (/local/domain/<domid>/vm-data) after the VM is created.
bool ha_always_run
if true then the system will attempt to keep the VM running as much as possible.
string ha_restart_priority
Only defined if ha_always_run is set 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"; and a numerical restart priority (e.g. 1, 2, 3,...)
bool is_a_snapshot
true if this is a snapshot. Snapshotted VMs can never be started, they are used only for cloning other VMs
VM snapshot_of
Ref pointing to the VM this snapshot is of.
Set[VM] snapshots
List pointing to all the VM snapshots.
datetime snapshot_time
Date/time when this snapshot was created.
string transportable_snapshot_id
Transportable ID of the snapshot VM
Map[string,blob] blobs
Binary blobs associated with this VM
Set[string] tags
user-specified tags for categorization purposes
Map[enum vm_operations,string] blocked_operations
List of operations which have been explicitly blocked and an error code
Map[string,string] snapshot_info
Human-readable information concerning this snapshot
string snapshot_metadata
Encoded information about the VM's metadata this is a snapshot of
VM parent
Ref pointing to the parent of this VM
Set[VM] children
List pointing to all the children of this VM
Map[string,string] bios_strings
BIOS strings
VMPP protection_policy
Ref pointing to a protection policy for this VM
bool is_snapshot_from_vmpp
true if this snapshot was created by the protection policy

Implicit messages

Record[VM] get_record (session session_id, VM self)
Get a record containing the current state of the given VM.
VM get_by_uuid (session session_id, string uuid)
Get a reference to the VM instance with the specified UUID.
VM create (session session_id, string name_label, string name_description, int user_version, bool is_a_template, host affinity, int memory_target, int memory_static_max, int memory_dynamic_max, int memory_dynamic_min, int memory_static_min, Map[string,string] VCPUs_params, int VCPUs_max, int VCPUs_at_startup, enum on_normal_exit actions_after_shutdown, enum on_normal_exit actions_after_reboot, enum on_crash_behaviour actions_after_crash, string PV_bootloader, string PV_kernel, string PV_ramdisk, string PV_args, string PV_bootloader_args, string PV_legacy_args, string HVM_boot_policy, Map[string,string] HVM_boot_params, float HVM_shadow_multiplier, Map[string,string] platform, string PCI_bus, Map[string,string] other_config, string recommendations, Map[string,string] xenstore_data, bool ha_always_run, string ha_restart_priority, Set[string] tags, Map[enum vm_operations,string] blocked_operations, VMPP protection_policy, bool is_snapshot_from_vmpp)
Create a new VM instance, and return its handle.
void destroy (session session_id, VM self)
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.
Set[VM] get_by_name_label (session session_id, string label)
Get all the VM instances with the given label.
Set[VM] get_all (session session_id)
Return a list of all the VMs known to the system.
Map[VM,Record[VM]] get_all_records (session session_id)
Return a map of VM references to VM records for all VMs known to the system.

Explicit messages

VM snapshot (session session_id, VM vm, string new_name)
Snapshots the specified VM, making a new VM. Snapshot automatically exploits the capabilities of the underlying storage repository in which the VM's disk images are stored (e.g. Copy on Write).
VM snapshot_with_quiesce (session session_id, VM vm, string new_name)
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).
VM clone (session session_id, VM vm, string new_name)
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.
VM copy (session session_id, VM vm, string new_name, SR sr)
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.
void revert (session session_id, VM snapshot)
Reverts the specified VM to a previous state.
VM checkpoint (session session_id, VM vm, string new_name)
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.
void provision (session session_id, VM vm)
Inspects the disk configuration contained within the VM's other_config, creates VDIs and VBDs and then executes any applicable post-install script.
void start (session session_id, VM vm, bool start_paused, bool force)
Start the specified VM. This function can only be called with the VM is in the Halted State.
void start_on (session session_id, VM vm, host host, bool start_paused, bool force)
Start the specified VM on a particular host. This function can only be called with the VM is in the Halted State.
void pause (session session_id, VM vm)
Pause the specified VM. This can only be called when the specified VM is in the Running state.
void unpause (session session_id, VM vm)
Resume the specified VM. This can only be called when the specified VM is in the Paused state.
void clean_shutdown (session session_id, VM vm)
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.
void clean_reboot (session session_id, VM vm)
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.
void hard_shutdown (session session_id, VM vm)
Stop executing the specified VM without attempting a clean shutdown.
void power_state_reset (session session_id, VM vm)
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.
void hard_reboot (session session_id, VM vm)
Stop executing the specified VM without attempting a clean shutdown and immediately restart the VM.
void suspend (session session_id, VM vm)
Suspend the specified VM to disk. This can only be called when the specified VM is in the Running state.
void resume (session session_id, VM vm, bool start_paused, bool force)
Awaken the specified VM and resume it. This can only be called when the specified VM is in the Suspended state.
void resume_on (session session_id, VM vm, host host, bool start_paused, bool force)
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.
void pool_migrate (session session_id, VM vm, host host, Map[string,string] options)
Migrate a VM to another Host. This can only be called when the specified VM is in the Running state.
void set_VCPUs_number_live (session session_id, VM self, int nvcpu)
Set the number of VCPUs for a running VM
void add_to_VCPUs_params_live (session session_id, VM self, string key, string value)
Add the given key-value pair to VM.VCPUs_params, and apply that value on the running VM
void set_ha_restart_priority (session session_id, VM self, string value)
Set the value of the ha_restart_priority field
void set_ha_always_run (session session_id, VM self, bool value)
Set the value of the ha_always_run
int compute_memory_overhead (session session_id, VM vm)
Computes the virtualization memory overhead of a VM.
void set_memory_dynamic_max (session session_id, VM self, int value)
Set the value of the memory_dynamic_max field
void set_memory_dynamic_min (session session_id, VM self, int value)
Set the value of the memory_dynamic_min field
void set_memory_dynamic_range (session session_id, VM self, int min, int max)
Set the minimum and maximum amounts of physical memory the VM is allowed to use.
void set_memory_static_max (session session_id, VM self, int value)
Set the value of the memory_static_max field
void set_memory_static_min (session session_id, VM self, int value)
Set the value of the memory_static_min field
void set_memory_static_range (session session_id, VM self, int min, int max)
Set the static (ie boot-time) range of virtual memory that the VM is allowed to use.
void set_memory_limits (session session_id, VM self, int static_min, int static_max, int dynamic_min, int dynamic_max)
Set the memory limits of this VM.
void set_memory_target_live (session session_id, VM self, int target)
[deprecated]Set the memory target for a running VM
void wait_memory_target_live (session session_id, VM self)
[deprecated]Wait for a running VM to reach its current memory target
bool get_cooperative (session session_id, VM self)
Return true if the VM is currently 'co-operative' i.e. is expected to reach a balloon target and actually has done
void set_HVM_shadow_multiplier (session session_id, VM self, float value)
Set the shadow memory multiplier on a halted VM
void set_shadow_multiplier_live (session session_id, VM self, float multiplier)
Set the shadow memory multiplier on a running VM
void set_VCPUs_max (session session_id, VM self, int value)
Set the maximum number of VCPUs for a halted VM
void set_VCPUs_at_startup (session session_id, VM self, int value)
Set the number of startup VCPUs for a halted VM
void send_sysrq (session session_id, VM vm, string key)
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.
void send_trigger (session session_id, VM vm, string trigger)
Send the named trigger to this VM. This can only be called when the specified VM is in the Running state.
int maximise_memory (session session_id, VM self, int total, bool approximate)
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
Record[VM] get_boot_record (session session_id, VM self)
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
Set[Record[data_source]] get_data_sources (session session_id, VM self)
void record_data_source (session session_id, VM self, string data_source)
Start recording the specified data source
float query_data_source (session session_id, VM self, string data_source)
Query the latest value of the specified data source
void forget_data_source_archives (session session_id, VM self, string data_source)
Forget the recorded statistics related to the specified data source
void assert_operation_valid (session session_id, VM self, enum vm_operations op)
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
void update_allowed_operations (session session_id, VM self)
Recomputes the list of acceptable operations
Set[string] get_allowed_VBD_devices (session session_id, VM vm)
Returns a list of the allowed values that a VBD device field can take
Set[string] get_allowed_VIF_devices (session session_id, VM vm)
Returns a list of the allowed values that a VIF device field can take
Set[host] get_possible_hosts (session session_id, VM vm)
Return the list of hosts on which this VM may run.
void assert_can_boot_here (session session_id, VM self, host host)
Returns an error if the VM could not boot on this host for some reason
blob create_new_blob (session session_id, VM vm, string name, string mime_type)
Create a placeholder for a named binary blob of data that is associated with this VM
void assert_agile (session session_id, VM self)
Returns an error if the VM is not considered agile e.g. because it is tied to a resource local to a host
Map[host,Set[string]] retrieve_wlb_recommendations (session session_id, VM vm)
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.
void copy_bios_strings (session session_id, VM vm, host host)
Copy the BIOS strings from the given host to this VM
void set_protection_policy (session session_id, VM self, VMPP value)
Set the value of the protection_policy field