Class: Cluster

Last published : Oct 01, 2026
Clusterwide Cluster metadata
Related information
XenServer 8.4 Management API

Fields for class: Cluster

Field Type Qualifier Description
allowed_operations cluster_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.
cluster_config (string -> string) map RO/constructor Contains read-only settings for the cluster, such as timeouts and other options. It can only be set at cluster create time
cluster_hosts Cluster_host ref set RO/runtime A list of the cluster_host objects associated with the Cluster
cluster_stack string RO/constructor Simply the string 'corosync'. No other cluster stacks are currently supported
cluster_stack_version int RO/constructor Version of cluster stack, not writable via the API. Defaulting to 2 for backwards compatibility when upgrading from a cluster without this field, which means it is necessarily running version 2 of corosync, the only cluster stack supported so far.
cluster_token string RO/constructor The secret key used by xapi-clusterd when it talks to itself on other hosts
current_operations (string -> cluster_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.
expected_hosts int RO/runtime Total number of hosts expected by the cluster stack
is_quorate bool RO/runtime Whether the cluster stack thinks the cluster is quorate
live_hosts int RO/runtime Current number of live hosts, according to the cluster stack
other_config (string -> string) map RW Additional configuration
pending_forget string set RO/runtime Internal field used by Host.destroy to store the IP of cluster members marked as permanently dead but not yet removed
pool_auto_join bool RO/constructor True if automatically joining new pool members to the cluster. This will be true in the first release
quorum int RO/runtime Number of live hosts in order to be quorate
token_timeout float RO/constructor The corosync token timeout in seconds
token_timeout_coefficient float RO/constructor The corosync token timeout coefficient in seconds
uuid string RO/runtime Unique identifier/object reference

RPCs associated with class: Cluster

RPC name: addtootherconfig

Overview:
Add the given keyvalue pair to the otherconfig field of the given Cluster.
Signature:
void add_to_other_config (session ref session_ref, Cluster ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
string key Key to add
string value Value to add
Minimum Role: pool-operator
Return Type: void

RPC name: create

Overview:
Creates a Cluster object and one Clusterhost object as its first member
Signature:
Cluster ref create (session ref session_ref, PIF ref PIF, string cluster_stack, bool pool_auto_join, float token_timeout, float token_timeout_coefficient)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref PIF The PIF to connect the cluster's first cluster_host to
string cluster_stack simply the string 'corosync'. No other cluster stacks are currently supported
bool pool_auto_join true if xapi is automatically joining new pool members to the cluster
float token_timeout Corosync token timeout in seconds
float token_timeout_coefficient Corosync token timeout coefficient in seconds
Minimum Role: pool-operator
Return Type: Cluster ref
the new Cluster
Possible Error Codes: INVALID_CLUSTER_STACK, INVALID_VALUE, PIF_ALLOWS_UNPLUG, REQUIRED_PIF_IS_UNPLUGGED

RPC name: destroy

Overview:
Destroys a Cluster object and the one remaining Clusterhost member
Signature:
void destroy (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self the Cluster to destroy
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: CLUSTER_DOES_NOT_HAVE_ONE_NODE, CLUSTER_STACK_IN_USE

RPC name: getall

Overview:
Return a list of all the Clusters known to the system.
Signature:
Cluster 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: Cluster ref set
references to all objects

RPC name: getallrecords

Overview:
Return a map of Cluster references to Cluster records for all Clusters known to the system.
Signature:
(Cluster ref -> Cluster 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: (Cluster ref -> Cluster record) map
records of all objects

RPC name: getallowedoperations

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

RPC name: getbyuuid

Overview:
Get a reference to the Cluster instance with the specified UUID.
Signature:
Cluster 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: Cluster ref
reference to the object

RPC name: getclusterconfig

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

RPC name: getclusterhosts

Overview:
Get the clusterhosts field of the given Cluster.
Signature:
Cluster_host ref set get_cluster_hosts (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: Cluster_host ref set
value of the field

RPC name: getclusterstack

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

RPC name: getclusterstackversion

Overview:
Get the clusterstackversion field of the given Cluster.
Signature:
int get_cluster_stack_version (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: int
value of the field

RPC name: getclustertoken

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

RPC name: getcurrentoperations

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

RPC name: getexpectedhosts

Overview:
Get the expectedhosts field of the given Cluster.
Signature:
int get_expected_hosts (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: int
value of the field

RPC name: getisquorate

Overview:
Get the isquorate field of the given Cluster.
Signature:
bool get_is_quorate (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getlivehosts

Overview:
Get the livehosts field of the given Cluster.
Signature:
int get_live_hosts (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: int
value of the field

RPC name: getnetwork

Overview:
Returns the network used by the cluster for interhost communication, i.e. the network shared by all cluster host PIFs
Signature:
network ref get_network (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self the Cluster with the network
Minimum Role: read-only
Return Type: network ref
network of cluster

RPC name: getotherconfig

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

RPC name: getpendingforget

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

RPC name: getpoolautojoin

Overview:
Get the poolautojoin field of the given Cluster.
Signature:
bool get_pool_auto_join (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getquorum

Overview:
Get the quorum field of the given Cluster.
Signature:
int get_quorum (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: int
value of the field

RPC name: getrecord

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

RPC name: gettokentimeout

Overview:
Get the tokentimeout field of the given Cluster.
Signature:
float get_token_timeout (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: float
value of the field

RPC name: gettokentimeoutcoefficient

Overview:
Get the tokentimeoutcoefficient field of the given Cluster.
Signature:
float get_token_timeout_coefficient (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
Minimum Role: read-only
Return Type: float
value of the field

RPC name: getuuid

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

RPC name: poolcreate

Overview:
Attempt to create a Cluster from the entire pool
Signature:
Cluster ref pool_create (session ref session_ref, network ref network, string cluster_stack, float token_timeout, float token_timeout_coefficient)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
network ref network the single network on which corosync carries out its inter-host communications
string cluster_stack simply the string 'corosync'. No other cluster stacks are currently supported
float token_timeout Corosync token timeout in seconds
float token_timeout_coefficient Corosync token timeout coefficient in seconds
Minimum Role: pool-operator
Return Type: Cluster ref
the new Cluster

RPC name: pooldestroy

Overview:
Attempt to destroy the Clusterhost objects for all hosts in the pool and then destroy the Cluster.
Signature:
void pool_destroy (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self The cluster to destroy.
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: CLUSTER_STACK_IN_USE, CLUSTERING_DISABLED, CLUSTER_HOST_IS_LAST

RPC name: poolforcedestroy

Overview:
Attempt to force destroy the Clusterhost objects, and then destroy the Cluster.
Signature:
void pool_force_destroy (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self The cluster to force destroy.
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: CLUSTER_FORCE_DESTROY_FAILED

RPC name: poolresync

Overview:
Resynchronise the clusterhost objects across the pool. Creates them where they need creating and then plugs them
Signature:
void pool_resync (session ref session_ref, Cluster ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self The cluster to resync
Minimum Role: pool-operator
Return Type: void

RPC name: removefromotherconfig

Overview:
Remove the given key and its corresponding value from the otherconfig field of the given Cluster. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session ref session_ref, Cluster ref self, string key)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
string key Key to remove
Minimum Role: pool-operator
Return Type: void

RPC name: setotherconfig

Overview:
Set the otherconfig field of the given Cluster.
Signature:
void set_other_config (session ref session_ref, Cluster ref self, (string -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
(string -> string) map value New value to set
Minimum Role: pool-operator
Return Type: void