/Classes/VM

Classes / VM / index.html

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 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_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
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 recommendations
An XML specification of recommended values and ranges for properties of this VM

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_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, Map[string,string] platform, string PCI_bus, Map[string,string] other_config, string recommendations)
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 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 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 this VM's VCPUs/at_startup value, and set the same value on the VM, if running
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_memory_dynamic_max_live (session session_id, VM self, int max)
Set memory_dynamic_max in database and on running VM
void set_memory_dynamic_min_live (session session_id, VM self, int min)
Set memory_dynamic_min in database and on running 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.
Record[VM] get_boot_record (session session_id, VM self)
Returns a record describing the VM's state when it last booted
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