Class: VMappliance

Last published : Oct 01, 2026
VM appliance
Related information
XenServer 8.4 Management API

Fields for class: VMappliance

Field Type Qualifier Description
allowed_operations vm_appliance_operation set RO/runtime list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client.
current_operations (string -> vm_appliance_operation) map RO/runtime links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
name_description string RW a notes field containing human-readable description
name_label string RW a human-readable name
uuid string RO/runtime Unique identifier/object reference
VMs VM ref set RO/runtime all VMs in this appliance

RPCs associated with class: VMappliance

RPC name: assertcanberecovered

Overview:
Assert whether all SRs required to recover this VM appliance are available.
Signature:
void assert_can_be_recovered (session ref session_ref, VM_appliance ref self, session ref session_to)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self The VM appliance to recover
session ref session_to The session to which the VM appliance is to be recovered.
Minimum Role: read-only
Return Type: void
Possible Error Codes: VM_REQUIRES_SR

RPC name: cleanshutdown

Overview:
Perform a clean shutdown of all the VMs in the appliance
Signature:
void clean_shutdown (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self The VM appliance
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: OPERATION_PARTIALLY_FAILED

RPC name: create

Overview:
Create a new VMappliance instance, and return its handle.
Signature:
VM_appliance ref create (session ref session_ref, VM_appliance record args)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance record args All constructor arguments
Minimum Role: pool-operator
Return Type: VM_appliance ref
reference to the newly created object

RPC name: destroy

Overview:
Destroy the specified VMappliance instance.
Signature:
void destroy (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
Minimum Role: pool-operator
Return Type: void

RPC name: getall

Overview:
Return a list of all the VMappliances known to the system.
Signature:
VM_appliance ref set get_all (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: VM_appliance ref set
references to all objects

RPC name: getallrecords

Overview:
Return a map of VMappliance references to VMappliance records for all VMappliances known to the system.
Signature:
(VM_appliance ref -> VM_appliance record) map get_all_records (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: (VM_appliance ref -> VM_appliance record) map
records of all objects

RPC name: getallowedoperations

Overview:
Get the allowedoperations field of the given VMappliance.
Signature:
vm_appliance_operation set get_allowed_operations (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
Minimum Role: read-only
Return Type: vm_appliance_operation set
value of the field

RPC name: getbynamelabel

Overview:
Get all the VMappliance instances with the given label.
Signature:
VM_appliance ref set get_by_name_label (session ref session_ref, string label)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string label label of object to return
Minimum Role: read-only
Return Type: VM_appliance ref set
references to objects with matching names

RPC name: getbyuuid

Overview:
Get a reference to the VMappliance instance with the specified UUID.
Signature:
VM_appliance ref get_by_uuid (session ref session_ref, string uuid)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return
Minimum Role: read-only
Return Type: VM_appliance ref
reference to the object

RPC name: getcurrentoperations

Overview:
Get the currentoperations field of the given VMappliance.
Signature:
(string -> vm_appliance_operation) map get_current_operations (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
Minimum Role: read-only
Return Type: (string -> vm_appliance_operation) map
value of the field

RPC name: getnamedescription

Overview:
Get the name/description field of the given VMappliance.
Signature:
string get_name_description (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getnamelabel

Overview:
Get the name/label field of the given VMappliance.
Signature:
string get_name_label (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getrecord

Overview:
Get a record containing the current state of the given VMappliance.
Signature:
VM_appliance record get_record (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
Minimum Role: read-only
Return Type: VM_appliance record
all fields from the object

RPC name: getSRsrequiredforrecovery

Overview:
Get the list of SRs required by the VM appliance to recover.
Signature:
SR ref set get_SRs_required_for_recovery (session ref session_ref, VM_appliance ref self, session ref session_to)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self The VM appliance for which the required list of SRs has to be recovered.
session ref session_to The session to which the list of SRs have to be recovered .
Minimum Role: read-only
Return Type: SR ref set
refs for SRs required to recover the VM

RPC name: getuuid

Overview:
Get the uuid field of the given VMappliance.
Signature:
string get_uuid (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getVMs

Overview:
Get the VMs field of the given VMappliance.
Signature:
VM ref set get_VMs (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
Minimum Role: read-only
Return Type: VM ref set
value of the field

RPC name: hardshutdown

Overview:
Perform a hard shutdown of all the VMs in the appliance
Signature:
void hard_shutdown (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self The VM appliance
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: OPERATION_PARTIALLY_FAILED

RPC name: recover

Overview:
Recover the VM appliance
Signature:
void recover (session ref session_ref, VM_appliance ref self, session ref session_to, bool force)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self The VM appliance to recover
session ref session_to The session to which the VM appliance is to be recovered.
bool force Whether the VMs should replace newer versions of themselves.
Minimum Role: read-only
Return Type: void
Possible Error Codes: VM_REQUIRES_SR

RPC name: setnamedescription

Overview:
Set the name/description field of the given VMappliance.
Signature:
void set_name_description (session ref session_ref, VM_appliance ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
string value New value to set
Minimum Role: pool-operator
Return Type: void

RPC name: setnamelabel

Overview:
Set the name/label field of the given VMappliance.
Signature:
void set_name_label (session ref session_ref, VM_appliance ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self reference to the object
string value New value to set
Minimum Role: pool-operator
Return Type: void

RPC name: shutdown

Overview:
For each VM in the appliance, try to shut it down cleanly. If this fails, perform a hard shutdown of the VM.
Signature:
void shutdown (session ref session_ref, VM_appliance ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self The VM appliance
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: OPERATION_PARTIALLY_FAILED

RPC name: start

Overview:
Start all VMs in the appliance
Signature:
void start (session ref session_ref, VM_appliance ref self, bool paused)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VM_appliance ref self The VM appliance
bool paused Instantiate all VMs belonging to this appliance in paused state if set to true.
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: OPERATION_PARTIALLY_FAILED