Click on a class to view the associated fields and messages.
Classes, Fields and Messages
Classes have both fields and messages. Messages are either implicit or explicit where an implicit message is one of:
a constructor (usually called "create");
a destructor (usually called "destroy");
"get_by_name_label";
"get_by_uuid";
"get_record";
"get_all"; and
"get_all_records".
Explicit messages include all the rest, more class-specific messages (e.g. "VM.start", "VM.clone")
Every field has at least one accessor depending both on its type and whether it is read-only or read-write. Accessors for a field named "X" would be a proper subset of:
set_X: change the value of field X (only if it is read-write);
get_X: retrieve the value of field X;
add_X: add a key/value pair (for fields of type set);
remove_X: remove a key (for fields of type set);
add_to_X: add a key/value pair (for fields of type map); and
remove_from_X: remove a key (for fields of type map).
This calls queries the external directory service to obtain the transitively-closed set of groups that the the subject_identifier is member of.
Parameters:
session ref session_id
Reference to a valid session
string subject_identifier
A string containing the subject_identifier, unique in the external directory service
Minimum role:
read-only
Result:
set of subject_identifiers that provides the group membership of subject_identifier passed as argument, it contains, recursively, all groups a subject_identifier is member of.
Published in:
XenServer 5.5 (george)
This calls queries the external directory service to obtain the transitively-closed set of groups that the the subject_identifier is member of.
stringget_subject_identifier(session ref, string)
This call queries the external directory service to obtain the subject_identifier as a string from the human-readable subject_name
Parameters:
session ref session_id
Reference to a valid session
string subject_name
The human-readable subject_name, such as a username or a groupname
Minimum role:
read-only
Result:
the subject_identifier obtained from the external directory service
Published in:
XenServer 5.5 (george)
This call queries the external directory service to obtain the subject_identifier as a string from the human-readable subject_name
This call queries the external directory service to obtain the user information (e.g. username, organization etc) from the specified subject_identifier
Parameters:
session ref session_id
Reference to a valid session
string subject_identifier
A string containing the subject_identifier, unique in the external directory service
Minimum role:
read-only
Result:
key-value pairs containing at least a key called subject_name
Published in:
XenServer 5.5 (george)
This call queries the external directory service to obtain the user information (e.g. username, organization etc) from the specified subject_identifier
blob
Class: blob
A placeholder for a binary blob
Published in:
XenServer 5.0 (orlando)
A placeholder for a binary blob
Fields
datetimelast_updated[RO/constructor]
Time at which the data in the blob was last updated
Published in:
XenServer 4.0 (rio)
Time at which the data in the blob was last updated
stringmime_type[RO/constructor]
The mime type associated with this object. Defaults to 'application/octet-stream' if the empty string is supplied
Published in:
XenServer 4.0 (rio)
The mime type associated with this object. Defaults to 'application/octet-stream' if the empty string is supplied
stringname_description[RW]
a notes field containing human-readable description
Default value:
""
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringname_label[RW]
a human-readable name
Default value:
""
Published in:
XenServer 4.0 (rio)
a human-readable name
boolpublic[RW]
True if the blob is publicly accessible
Default value:
false
Published in:
XenServer 6.1 (tampa)
True if the blob is publicly accessible
intsize[RO/runtime]
Size of the binary data, in bytes
Published in:
XenServer 4.0 (rio)
Size of the binary data, in bytes
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
Messages
blob refcreate(session ref, string, bool)
Create a placeholder for a binary blob
Parameters:
session ref session_id
Reference to a valid session
string mime_type
The mime-type of the blob. Defaults to 'application/octet-stream' if the empty string is supplied
bool public
True if the blob should be publicly available
Minimum role:
pool-operator
Result:
The reference of the created blob
Published in:
XenServer 5.0 (orlando)
Create a placeholder for a binary blob
voiddestroy(session ref, blob ref)
Parameters:
session ref session_id
Reference to a valid session
blob ref self
The reference of the blob to destroy
Minimum role:
pool-operator
Published in:
XenServer 5.0 (orlando)
blob ref setget_all(session ref)
Return a list of all the blobs known to the system.
a notes field containing human-readable description
voidset_name_label(session ref, blob ref, string)
Set the name/label field of the given blob.
Parameters:
session ref session_id
Reference to a valid session
blob ref self
reference to the object
string value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
a human-readable name
voidset_public(session ref, blob ref, bool)
Set the public field of the given blob.
Parameters:
session ref session_id
Reference to a valid session
blob ref self
reference to the object
bool value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 6.1 (tampa)
True if the blob is publicly accessible
Bond
Class: Bond
A Network bond that combines physical network interfaces, also known as link aggregation
Published in:
XenServer 4.1 (miami)
A Network bond that combines physical network interfaces, also known as link aggregation
Enums
bond_mode
Values:
balance-slb
Source-level balancing
active-backup
Active/passive bonding: only one NIC is carrying traffic
lacp
Link aggregation control protocol
Fields
boolauto_update_mac[RO/runtime]
true if the MAC was taken from the primary slave when the bond was created, and false if the client specified the MAC
Default value:
true
Published in:
Citrix Hypervisor 8.1 (quebec)
intlinks_up[RO/runtime]
Number of links up in this bond
Default value:
0
Published in:
XenServer 6.1 (tampa)
Number of links up in this bond
PIF refmaster[RO/constructor]
The bonded interface
Default value:
Null
Published in:
XenServer 4.1 (miami)
The bonded interface
enum bond_modemode[RO/runtime]
The algorithm used to distribute traffic among the bonded NICs
Default value:
balance-slb
Published in:
XenServer 6.0 (boston)
(string → string) mapother_config[RW]
additional configuration
Default value:
{}
Published in:
XenServer 4.1 (miami)
additional configuration
PIF refprimary_slave[RO/runtime]
The PIF of which the IP configuration and MAC were copied to the bond, and which will receive all configuration/VLANs/VIFs on the bond if the bond is destroyed
Default value:
OpaqueRef:NULL
Published in:
XenServer 6.0 (boston)
(string → string) mapproperties[RO/runtime]
Additional configuration properties specific to the bond mode.
Default value:
{}
Published in:
XenServer 6.1 (tampa)
Additional configuration properties specific to the bond mode.
PIF ref setslaves[RO/runtime]
The interfaces which are part of this bond
Published in:
XenServer 4.1 (miami)
The interfaces which are part of this bond
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
Messages
voidadd_to_other_config(session ref, Bond ref, string, string)
Add the given key-value pair to the other_config field of the given Bond.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
Get the allowed_operations field of the given Cluster.
Parameters:
session ref session_id
Reference to a valid session
Cluster ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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 refget_by_uuid(session ref, string)
Get a reference to the Cluster instance with the specified UUID.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
Default value:
{}
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
boolenabled[RO/runtime]
Whether the cluster host believes that clustering should be enabled on this host. This field can be altered by calling the enable/disable message on a cluster host. Only enabled members run the underlying cluster stack. Disabled members are still considered a member of the cluster (see joined), and can be re-enabled by the user.
Default value:
false
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
host refhost[RO/constructor]
Reference to the Host object
Default value:
OpaqueRef:NULL
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
booljoined[RO/runtime]
Whether the cluster host has joined the cluster. Contrary to enabled, a host that is not joined is not considered a member of the cluster, and hence enable and disable operations cannot be performed on this host.
Default value:
true
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
Prototype
datetimelast_update_live[RO/runtime]
Time when the live field was last updated based on information from the cluster stack
Default value:
19700101T00:00:00Z
Prototyped in:
XAPI 24.3.0 (24.3.0)
Prototype
boollive[RO/runtime]
Whether the underlying cluster stack thinks we are live. This field is set automatically based on updates from the cluster stack and cannot be altered by the user.
Get the allowed_operations field of the given Cluster_host.
Parameters:
session ref session_id
Reference to a valid session
Cluster_host ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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_host refget_by_uuid(session ref, string)
Get a reference to the Cluster_host instance with the specified UUID.
Get a record containing the current state of the given DR_task.
Parameters:
session ref session_id
Reference to a valid session
DR_task ref self
reference to the object
Minimum role:
read-only
Result:
all fields from the object
Published in:
XenServer 6.0 (boston)
DR task
stringget_uuid(session ref, DR_task ref)
Get the uuid field of the given DR_task.
Parameters:
session ref session_id
Reference to a valid session
DR_task ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
event
Class: event
Asynchronous event registration and handling
Published in:
XenServer 4.0 (rio)
Enums
event_operation
Values:
add
An object has been created
del
An object has been deleted
mod
An object has been modified
Fields
stringclass[RO/constructor]
The name of the class of the object that changed
Published in:
XenServer 4.0 (rio)
The name of the class of the object that changed
intid[RO/constructor]
An ID, monotonically increasing, and local to the current session
Published in:
XenServer 4.0 (rio)
An ID, monotonically increasing, and local to the current session
Deprecated
stringobj_uuid[RO/constructor]
The uuid of the object that changed
Published in:
XenServer 4.0 (rio)
The uuid of the object that changed
Deprecated in:
XenServer 6.0 (boston)
enum event_operationoperation[RO/constructor]
The operation that was performed
Published in:
XenServer 4.0 (rio)
The operation that was performed
stringref[RO/constructor]
A reference to the object that changed
Published in:
XenServer 4.0 (rio)
A reference to the object that changed
<class> recordsnapshot[RO/runtime]
The record of the database object that was added, changed or deleted
Published in:
XenServer 6.0 (boston)
Deprecated
datetimetimestamp[RO/constructor]
The time at which the event occurred
Published in:
XenServer 4.0 (rio)
The time at which the event occurred
Deprecated in:
XenServer 6.0 (boston)
Messages
an event batchfrom(session ref, string set, string, float)
Blocking call which returns a new token and a (possibly empty) batch of events. The returned token can be used in subsequent calls to this function.
Parameters:
session ref session_id
Reference to a valid session
string set classes
register for events for the indicated classes
string token
A token representing the point from which to generate database events. The empty string represents the beginning.
float timeout
Return after this many seconds if no events match
Minimum role:
read-only
Result:
a structure consisting of a token ('token'), a map of valid references per object type ('valid_ref_counts'), and a set of event records ('events').
Errors:
SESSION_NOT_REGISTERED
This session is not registered to receive events. You must call event.register before event.next. The session handle you are using is echoed.
EVENTS_LOST
Some events have been lost from the queue and cannot be retrieved.
Published in:
XenServer 6.0 (boston)
Blocking call which returns a new token and a (possibly empty) batch of events. The returned token can be used in subsequent calls to this function.
intget_current_id(session ref)
Return the ID of the next event to be generated by the system
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
the event ID
Published in:
XenServer 4.0 (rio)
Return the ID of the next event to be generated by the system
stringinject(session ref, string, string)
Injects an artificial event on the given object and returns the corresponding ID in the form of a token, which can be used as a point of reference for database events. For example, to check whether an object has reached the right state before attempting an operation, one can inject an artificial event on the object and wait until the token returned by consecutive event.from calls is lexicographically greater than the one returned by event.inject.
Parameters:
session ref session_id
Reference to a valid session
string class
class of the object
string ref
A reference to the object that will be changed.
Minimum role:
read-only
Result:
the event ID in the form of a token
Published in:
XenServer 6.1 (tampa)
Injects an artificial event on the given object and returns the corresponding ID in the form of a token, which can be used as a point of reference for database events. For example, to check whether an object has reached the right state before attempting an operation, one can inject an artificial event on the object and wait until the token returned by consecutive event.from calls is lexicographically greater than the one returned by event.inject.
Deprecated
event record setnext(session ref)
Blocking call which returns a (possibly empty) batch of events. This method is only recommended for legacy use. New development should use event.from which supercedes this method.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
A set of events
Errors:
SESSION_NOT_REGISTERED
This session is not registered to receive events. You must call event.register before event.next. The session handle you are using is echoed.
EVENTS_LOST
Some events have been lost from the queue and cannot be retrieved.
Published in:
XenServer 4.0 (rio)
Blocking call which returns a (possibly empty) batch of events. This method is only recommended for legacy use. New development should use event.from which supercedes this method.
Deprecated in:
XenServer 6.0 (boston)
Deprecated
voidregister(session ref, string set)
Registers this session with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next.
Parameters:
session ref session_id
Reference to a valid session
string set classes
the classes for which the session will register with the event system; specifying * as the desired class will register for all classes
Minimum role:
read-only
Published in:
XenServer 4.0 (rio)
Registers this session with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next.
Deprecated in:
XenServer 6.0 (boston)
Deprecated
voidunregister(session ref, string set)
Removes this session's registration with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next.
Parameters:
session ref session_id
Reference to a valid session
string set classes
the classes for which the session's registration with the event system will be removed
Minimum role:
read-only
Published in:
XenServer 4.0 (rio)
Removes this session's registration with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next.
Deprecated in:
XenServer 6.0 (boston)
Feature
Class: Feature
A new piece of functionality
Published in:
XenServer 7.2 (falcon)
Fields
boolenabled[RO/runtime]
Indicates whether the feature is enabled
Default value:
false
Published in:
XenServer 7.2 (falcon)
boolexperimental[RO/constructor]
Indicates whether the feature is experimental (as opposed to stable and fully supported)
Default value:
false
Published in:
XenServer 7.2 (falcon)
host refhost[RO/runtime]
The host where this feature is available
Published in:
XenServer 7.2 (falcon)
stringname_description[RO/constructor]
a notes field containing human-readable description
Default value:
""
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringname_label[RO/constructor]
a human-readable name
Default value:
""
Published in:
XenServer 4.0 (rio)
a human-readable name
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 7.2 (falcon)
stringversion[RO/constructor]
The version of this feature
Default value:
"1.0"
Published in:
XenServer 7.2 (falcon)
Messages
Feature ref setget_all(session ref)
Return a list of all the Features known to the system.
Set the other_config field of the given GPU_group.
Parameters:
session ref session_id
Reference to a valid session
GPU_group ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
host
Class: host
A physical host
Published in:
XenServer 4.0 (rio)
A physical host
Enums
host_allowed_operations
Values:
provision
Indicates this host is able to provision another VM
evacuate
Indicates this host is evacuating
shutdown
Indicates this host is in the process of shutting itself down
reboot
Indicates this host is in the process of rebooting
power_on
Indicates this host is in the process of being powered on
vm_start
This host is starting a VM
vm_resume
This host is resuming a VM
vm_migrate
This host is the migration target of a VM
apply_updates
Indicates this host is being updated
enable
Indicates this host is in the process of enabling
latest_synced_updates_applied_state
Values:
yes
The host is up to date with the latest updates synced from remote CDN
no
The host is outdated with the latest updates synced from remote CDN
unknown
If the host is up to date with the latest updates synced from remote CDN is unknown
update_guidances
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
host_display
Values:
enabled
This host is outputting its console to a physical display device
disable_on_reboot
The host will stop outputting its console to a physical display device on next boot
disabled
This host is not outputting its console to a physical display device
enable_on_reboot
The host will start outputting its console to a physical display device on next boot
host_sched_gran
Values:
core
core scheduling
cpu
CPU scheduling
socket
socket scheduling
host_numa_affinity_policy
Values:
any
VMs are spread across all available NUMA nodes
best_effort
VMs are placed on the smallest number of NUMA nodes that they fit using soft-pinning, but the policy doesn't guarantee a balanced placement, falling back to the 'any' policy.
default_policy
Use the NUMA affinity policy that is the default for the current version
Fields
stringaddress[RW]
The address by which this host can be contacted from any other host in the pool
Published in:
XenServer 4.0 (rio)
The address by which this host can be contacted from any other host in the pool
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
The CPU configuration on this host. May contain keys such as "nr_nodes", "sockets_per_node", "cores_per_socket", or "threads_per_core"
Published in:
XenServer 4.0 (rio)
The CPU configuration on this host. May contain keys such as "nr_nodes", "sockets_per_node", "cores_per_socket", or "threads_per_core"
The set of pending full guidances after applying updates, which a user should follow to make some updates, e.g. specific hardware drivers or CPU features, fully effective, but the 'average user' doesn't need to
The set of pending recommended guidances after applying updates, which most users should follow to make the updates effective, but if not followed, will not cause a failure
Allow SSLv3 protocol and ciphersuites as used by older server versions. This controls both incoming and outgoing connections. When this is set to a different value, the host immediately restarts its SSL/TLS listening service; typically this takes less than a second but existing connections to it will be broken. API login sessions will remain valid.
Default value:
true
Published in:
XenServer 7.0 (dundee)
Deprecated in:
Citrix Hypervisor 8.2 (stockholm)
Legacy SSL no longer supported
string setsupported_bootloaders[RO/runtime]
a list of the bootloaders installed on the machine
Published in:
XenServer 4.0 (rio)
a list of the bootloaders installed on the machine
SR refsuspend_image_sr[RW]
The SR in which VDIs for suspend images are created
Published in:
XenServer 4.0 (rio)
The SR in which VDIs for suspend images are created
Change to another edition, or reactivate the current edition after a license has expired. This may be subject to the successful checkout of an appropriate license.
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host
string edition
The requested edition
bool force
Update the license params even if the apply call fails
Minimum role:
pool-operator
Published in:
XenServer 5.6 (midnight-ride)
Change to another edition, or reactivate the current edition after a license has expired. This may be subject to the successful checkout of an appropriate license.
Create a placeholder for a named binary blob of data that is associated with this host
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host
string name
The name associated with the blob
string mime_type
The mime type for the data. Empty string translates to application/octet-stream
bool public
True if the blob should be publicly available
Minimum role:
pool-operator
Result:
The reference of the blob, needed for populating its data
Published in:
XenServer 5.0 (orlando)
Create a placeholder for a named binary blob of data that is associated with this host
voiddeclare_dead(session ref, host ref)
Declare that a host is dead. This is a dangerous operation, and should only be called if the administrator is absolutely sure the host is definitely dead
Parameters:
session ref session_id
Reference to a valid session
host ref host
The Host to declare is dead
Minimum role:
pool-operator
Published in:
XenServer 6.2 (clearwater)
Declare that a host is dead. This is a dangerous operation, and should only be called if the administrator is absolutely sure the host is definitely dead
voiddestroy(session ref, host ref)
Destroy specified host record in database
Parameters:
session ref session_id
Reference to a valid session
host ref self
The host record to remove
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Destroy specified host record in database
voiddisable(session ref, host ref)
Puts the host into a state in which no new VMs can be started. Currently active VMs on the host continue to execute.
Parameters:
session ref session_id
Reference to a valid session
host ref host
The Host to disable
Minimum role:
client-cert
Published in:
XenServer 4.0 (rio)
Puts the host into a state in which no new VMs can be started. Currently active VMs on the host continue to execute.
Get the allowed_operations field of the given host.
Parameters:
session ref session_id
Reference to a valid session
host ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
intget_API_version_major(session ref, host ref)
Get the API_version/major field of the given host.
Parameters:
session ref session_id
Reference to a valid session
host ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
major version number
intget_API_version_minor(session ref, host ref)
Get the API_version/minor field of the given host.
Get the cpu_configuration field of the given host.
Parameters:
session ref session_id
Reference to a valid session
host ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
The CPU configuration on this host. May contain keys such as "nr_nodes", "sockets_per_node", "cores_per_socket", or "threads_per_core"
Reconfigure the management network interface. Should only be used if Host.management_reconfigure is impossible because the network configuration is broken.
Parameters:
session ref session_id
Reference to a valid session
string interface
name of the interface to use as a management interface
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
Reconfigure the management network interface. Should only be used if Host.management_reconfigure is impossible because the network configuration is broken.
voidmanagement_disable(session ref)
Disable the management network interface
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
Disable the management network interface
voidmanagement_reconfigure(session ref, PIF ref)
Reconfigure the management network interface
Parameters:
session ref session_id
Reference to a valid session
PIF ref pif
reference to a PIF object corresponding to the management interface
Delete the current TLS server certificate and replace by a new, self-signed one. This should only be used with extreme care.
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host
Minimum role:
pool-admin
Published in:
XAPI 1.290.0 (1.290.0)
voidrestart_agent(session ref, host ref)
Restarts the agent after a 10 second pause. WARNING: this is a dangerous operation. Any operations in progress will be aborted, and unrecoverable data loss may occur. The caller is responsible for ensuring that there are no operations in progress when this method is called.
Parameters:
session ref session_id
Reference to a valid session
host ref host
The Host on which you want to restart the agent
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Restarts the agent after a 10 second pause. WARNING: this is a dangerous operation. Any operations in progress will be aborted, and unrecoverable data loss may occur. The caller is responsible for ensuring that there are no operations in progress when this method is called.
Retrieves recommended host migrations to perform when evacuating the host from the wlb server. If a VM cannot be migrated from the host the reason is listed instead of a recommendation.
Parameters:
session ref session_id
Reference to a valid session
host ref self
The host to query
Minimum role:
read-only
Result:
VMs and the reasons why they would block evacuation, or their target host recommended by the wlb server
Published in:
XenServer 5.5 (george)
Retrieves recommended host migrations to perform when evacuating the host from the wlb server. If a VM cannot be migrated from the host the reason is listed instead of a recommendation.
Sets xen's sched-gran on a host. See: https://xenbits.xen.org/docs/unstable/misc/xen-command-line.html#sched-gran-x86
Parameters:
session ref session_id
Reference to a valid session
host ref self
The host
enum host_sched_gran value
The sched-gran to apply to a host
Minimum role:
Published in:
XAPI 1.271.0 (1.271.0)
voidset_ssl_legacy(session ref, host ref, bool)
Enable/disable SSLv3 for interoperability with older server versions. When this is set to a different value, the host immediately restarts its SSL/TLS listening service; typically this takes less than a second but existing connections to it will be broken. API login sessions will remain valid.
Parameters:
session ref session_id
Reference to a valid session
host ref self
The host
bool value
True to allow SSLv3 and ciphersuites as used in old XenServer versions
Minimum role:
pool-operator
Published in:
XenServer 7.0 (dundee)
Changed in:
Citrix Hypervisor 8.2 (stockholm)
Legacy SSL no longer supported
voidset_suspend_image_sr(session ref, host ref, SR ref)
Set the suspend_image_sr field of the given host.
Parameters:
session ref session_id
Reference to a valid session
host ref self
reference to the object
SR ref value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
The SR in which VDIs for suspend images are created
Shutdown the host. (This function can only be called if there are no currently running VMs on the host and it is disabled.)
Parameters:
session ref session_id
Reference to a valid session
host ref host
The Host to shutdown
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Shutdown the host. (This function can only be called if there are no currently running VMs on the host and it is disabled.)
voidshutdown_agent(session ref)
Shuts the agent down after a 10 second pause. WARNING: this is a dangerous operation. Any operations in progress will be aborted, and unrecoverable data loss may occur. The caller is responsible for ensuring that there are no operations in progress when this method is called.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Published in:
XenServer 5.0 (orlando)
Shuts the agent down after a 10 second pause. WARNING: this is a dangerous operation. Any operations in progress will be aborted, and unrecoverable data loss may occur. The caller is responsible for ensuring that there are no operations in progress when this method is called.
voidsync_data(session ref, host ref)
This causes the synchronisation of the non-database data (messages, RRDs and so on) stored on the master to be synchronised with the host
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host to whom the data should be sent
Minimum role:
pool-admin
Published in:
XenServer 5.0 (orlando)
This causes the synchronisation of the non-database data (messages, RRDs and so on) stored on the master to be synchronised with the host
voidsyslog_reconfigure(session ref, host ref)
Re-configure syslog logging
Parameters:
session ref session_id
Reference to a valid session
host ref host
Tell the host to reread its Host.logging parameters and reconfigure itself accordingly
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
Re-configure syslog logging
host_cpu
Deprecated
Class: host_cpu
A physical CPU
Published in:
XenServer 4.0 (rio)
A physical CPU
Deprecated in:
XenServer 5.6 (midnight-ride)
Deprecated in favour of the Host.cpu_info field
Fields
intfamily[RO/runtime]
the family (number) of the physical CPU
Published in:
XenServer 4.0 (rio)
the family (number) of the physical CPU
stringfeatures[RO/runtime]
the physical CPU feature bitmap
Published in:
XenServer 4.0 (rio)
the physical CPU feature bitmap
stringflags[RO/runtime]
the flags of the physical CPU (a decoded version of the features field)
Published in:
XenServer 4.0 (rio)
the flags of the physical CPU (a decoded version of the features field)
Remove the given key and its corresponding value from the other_config field of the given host_crashdump. If the key is not in that Map, then do nothing.
Remove the given key and its corresponding value from the other_config field of the given host_metrics. If the key is not in that Map, then do nothing.
Set the other_config field of the given host_patch.
Parameters:
session ref session_id
Reference to a valid session
host_patch ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
additional configuration
LVHD
Class: LVHD
LVHD SR specific operations
Published in:
XenServer 7.0 (dundee)
LVHD SR specific operations
Fields
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
Messages
stringenable_thin_provisioning(session ref, host ref, SR ref, int, int)
Upgrades an LVHD SR to enable thin-provisioning. Future VDIs created in this SR will be thinly-provisioned, although existing VDIs will be left alone. Note that the SR must be attached to the SRmaster for upgrade to work.
Parameters:
session ref session_id
Reference to a valid session
host ref host
The LVHD Host to upgrade to being thin-provisioned.
SR ref SR
The LVHD SR to upgrade to being thin-provisioned.
int initial_allocation
The initial amount of space to allocate to a newly-created VDI in bytes
int allocation_quantum
The amount of space to allocate to a VDI when it needs to be enlarged in bytes
Minimum role:
pool-admin
Result:
Message from LVHD.enable_thin_provisioning extension
Published in:
XenServer 7.0 (dundee)
Upgrades an LVHD SR to enable thin-provisioning. Future VDIs created in this SR will be thinly-provisioned, although existing VDIs will be left alone. Note that the SR must be attached to the SRmaster for upgrade to work.
LVHD refget_by_uuid(session ref, string)
Get a reference to the LVHD instance with the specified UUID.
Parameters:
session ref session_id
Reference to a valid session
string uuid
UUID of object to return
Minimum role:
read-only
Result:
reference to the object
Published in:
XenServer 7.0 (dundee)
LVHD SR specific operations
LVHD recordget_record(session ref, LVHD ref)
Get a record containing the current state of the given LVHD.
Parameters:
session ref session_id
Reference to a valid session
LVHD ref self
reference to the object
Minimum role:
read-only
Result:
all fields from the object
Published in:
XenServer 7.0 (dundee)
LVHD SR specific operations
stringget_uuid(session ref, LVHD ref)
Get the uuid field of the given LVHD.
Parameters:
session ref session_id
Reference to a valid session
LVHD ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
message
Class: message
An message for the attention of the administrator
Published in:
XenServer 5.0 (orlando)
An message for the attention of the administrator
Enums
cls
Values:
VM
VM
Host
Host
SR
SR
Pool
Pool
VMPP
VMPP
VMSS
VMSS
PVS_proxy
PVS_proxy
VDI
VDI
Certificate
Certificate
Fields
stringbody[RO/runtime]
The body of the message
Published in:
XenServer 4.0 (rio)
The body of the message
enum clscls[RO/runtime]
The class of the object this message is associated with
Published in:
XenServer 5.0 (orlando)
Extended in:
XAPI 1.313.0 (1.313.0)
Added Certificate class
stringname[RO/runtime]
The name of the message
Published in:
XenServer 4.0 (rio)
The name of the message
stringobj_uuid[RO/runtime]
The uuid of the object this message is associated with
Published in:
XenServer 4.0 (rio)
The uuid of the object this message is associated with
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
(VIF ref → string) mapassigned_ips[RO/runtime]
The IP addresses assigned to VIFs on networks that have active xapi-managed DHCP
Default value:
{}
Published in:
XenServer 6.5 (creedence)
The IP addresses assigned to VIFs on networks that have active xapi-managed DHCP
(string → blob ref) mapblobs[RO/runtime]
Binary blobs associated with this network
Default value:
{}
Published in:
XenServer 5.0 (orlando)
Binary blobs associated with this network
stringbridge[RO/constructor]
name of the bridge corresponding to this network on the local host
Add the given key-value pair to the other_config field of the given network.
Parameters:
session ref session_id
Reference to a valid session
network ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
additional configuration
network refcreate(session ref, network record)
Create a new network instance, and return its handle.
The constructor args are: name_label, name_description, MTU, other_config*, bridge, managed, tags (* = non-optional).
Get the allowed_operations field of the given network.
Parameters:
session ref session_id
Reference to a valid session
network ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
Enable SR-IOV on the specific PIF. It will create a network-sriov based on the specific PIF and automatically create a logical PIF to connect the specific network.
Parameters:
session ref session_id
Reference to a valid session
PIF ref pif
PIF on which to enable SR-IOV
network ref network
Network to connect SR-IOV virtual functions with VM VIFs
Minimum role:
pool-operator
Result:
The reference of the created network_sriov object
Published in:
XenServer 7.5 (kolkata)
voiddestroy(session ref, network_sriov ref)
Disable SR-IOV on the specific PIF. It will destroy the network-sriov and the logical PIF accordingly.
Parameters:
session ref session_id
Reference to a valid session
network_sriov ref self
SRIOV to destroy
Minimum role:
pool-operator
Published in:
XenServer 7.5 (kolkata)
network_sriov ref setget_all(session ref)
Return a list of all the network_sriovs known to the system.
Get the requires_reboot field of the given network_sriov.
Parameters:
session ref session_id
Reference to a valid session
network_sriov ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.5 (kolkata)
stringget_uuid(session ref, network_sriov ref)
Get the uuid field of the given network_sriov.
Parameters:
session ref session_id
Reference to a valid session
network_sriov ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
Observer
Prototype
Class: Observer
Describes a observer which will control observability activity in the Toolstack
Prototyped in:
XAPI 23.14.0 (23.14.0)
Fields
Prototype
(string → string) mapattributes[RO/constructor]
Attributes that observer will add to the data they produce
Default value:
{}
Prototyped in:
XAPI 23.14.0 (23.14.0)
Prototype
string setcomponents[RO/constructor]
The list of xenserver components the observer will broadcast. An empty list means all components
Default value:
{}
Prototyped in:
XAPI 23.14.0 (23.14.0)
Prototype
boolenabled[RO/constructor]
This denotes if the observer is enabled. true if it is enabled and false if it is disabled
Default value:
false
Prototyped in:
XAPI 23.14.0 (23.14.0)
Prototype
string setendpoints[RO/constructor]
The list of endpoints where data is exported to. Each endpoint is a URL or the string 'bugtool' refering to the internal logs
Default value:
{}
Prototyped in:
XAPI 23.14.0 (23.14.0)
Prototype
host ref sethosts[RO/constructor]
The list of hosts the observer is active on. An empty list means all hosts
Default value:
{}
Prototyped in:
XAPI 23.14.0 (23.14.0)
stringname_description[RW]
a notes field containing human-readable description
Default value:
""
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringname_label[RW]
a human-readable name
Default value:
""
Published in:
XenServer 4.0 (rio)
a human-readable name
Prototype
stringuuid[RO/runtime]
Unique identifier/object reference
Prototyped in:
XAPI 23.14.0 (23.14.0)
Messages
Prototype
Observer refcreate(session ref, Observer record)
Create a new Observer instance, and return its handle.
The constructor args are: name_label, name_description, hosts, attributes, endpoints, components, enabled (* = non-optional).
Parameters:
session ref session_id
Reference to a valid session
Observer record args
All constructor arguments
Minimum role:
pool-admin
Result:
reference to the newly created object
Prototyped in:
XAPI 23.14.0 (23.14.0)
Prototype
voiddestroy(session ref, Observer ref)
Destroy the specified Observer instance.
Parameters:
session ref session_id
Reference to a valid session
Observer ref self
reference to the object
Minimum role:
pool-admin
Prototyped in:
XAPI 23.14.0 (23.14.0)
Prototype
Observer ref setget_all(session ref)
Return a list of all the Observers known to the system.
A physical network interface (note separate VLANs are represented as several PIFs)
Published in:
XenServer 4.0 (rio)
A physical network interface (note separate VLANs are represented as several PIFs)
Enums
pif_igmp_status
Values:
enabled
IGMP Snooping is enabled in the corresponding backend bridge.'
disabled
IGMP Snooping is disabled in the corresponding backend bridge.'
unknown
IGMP snooping status is unknown. If this is a VLAN master, then please consult the underlying VLAN slave PIF.
ip_configuration_mode
Values:
None
Do not acquire an IP address
DHCP
Acquire an IP address by DHCP
Static
Static IP address configuration
ipv6_configuration_mode
Values:
None
Do not acquire an IPv6 address
DHCP
Acquire an IPv6 address by DHCP
Static
Static IPv6 address configuration
Autoconf
Router assigned prefix delegation IPv6 allocation
primary_address_type
Values:
IPv4
Primary address is the IPv4 address
IPv6
Primary address is the IPv6 address
Fields
Bond ref setbond_master_of[RO/runtime]
Indicates this PIF represents the results of a bond
Published in:
XenServer 4.1 (miami)
Indicates this PIF represents the results of a bond
Bond refbond_slave_of[RO/runtime]
Indicates which bond this interface is part of
Default value:
Null
Published in:
XenServer 4.1 (miami)
Indicates which bond this interface is part of
string setcapabilities[RO/runtime]
Additional capabilities on the interface.
Default value:
{}
Published in:
XenServer 7.0 (dundee)
boolcurrently_attached[RO/runtime]
true if this interface is online
Default value:
true
Published in:
XenServer 4.1 (miami)
true if this interface is online
stringdevice[RO/constructor]
machine-readable name of the interface (e.g. eth0)
Published in:
XenServer 4.0 (rio)
machine-readable name of the interface (e.g. eth0)
booldisallow_unplug[RO/runtime]
Prevent this PIF from being unplugged; set this to notify the management tool-stack that the PIF has a special use and should not be unplugged under any circumstances (e.g. because you're running storage traffic over it)
Default value:
false
Published in:
XenServer 5.0 (orlando)
Prevent this PIF from being unplugged; set this to notify the management tool-stack that the PIF has a special use and should not be unplugged under any circumstances (e.g. because you're running storage traffic over it)
stringDNS[RO/runtime]
Comma separated list of the IP addresses of the DNS servers to use
Default value:
""
Published in:
XenServer 4.1 (miami)
Comma separated list of the IP addresses of the DNS servers to use
Sets if and how this interface gets an IPv6 address
Default value:
None
Published in:
XenServer 6.1 (tampa)
stringipv6_gateway[RO/runtime]
IPv6 gateway
Default value:
""
Published in:
XenServer 6.1 (tampa)
stringMAC[RO/constructor]
ethernet MAC address of physical interface
Published in:
XenServer 4.0 (rio)
ethernet MAC address of physical interface
boolmanaged[RO/constructor]
Indicates whether the interface is managed by xapi. If it is not, then xapi will not configure the interface, the commands PIF.plug/unplug/reconfigure_ip(v6) cannot be used, nor can the interface be bonded or have VLANs based on top through xapi.
Default value:
true
Published in:
XenServer 6.2 SP1 (vgpu-productisation)
boolmanagement[RO/runtime]
Indicates whether the control software is listening for connections on this interface
Default value:
false
Published in:
XenServer 4.1 (miami)
Indicates whether the control software is listening for connections on this interface
PIF_metrics refmetrics[RO/runtime]
metrics associated with this PIF
Published in:
XenServer 4.0 (rio)
metrics associated with this PIF
intMTU[RO/constructor]
MTU in octets
Published in:
XenServer 4.0 (rio)
MTU in octets
stringnetmask[RO/runtime]
IP netmask
Default value:
""
Published in:
XenServer 4.1 (miami)
IP netmask
network refnetwork[RO/constructor]
virtual network to which this pif is connected
Published in:
XenServer 4.0 (rio)
virtual network to which this pif is connected
(string → string) mapother_config[RW]
Additional configuration
Default value:
{}
Published in:
XenServer 4.1 (miami)
Additional configuration
PCI refPCI[RO/runtime]
Link to underlying PCI device
Default value:
OpaqueRef:NULL
Published in:
XenServer 7.5 (kolkata)
boolphysical[RO/runtime]
true if this represents a physical network interface
Default value:
false
Published in:
XenServer 4.1 (miami)
true if this represents a physical network interface
Destroy the PIF object (provided it is a VLAN interface). This call is deprecated: use VLAN.destroy or Bond.destroy instead
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
the PIF object to destroy
Minimum role:
pool-operator
Errors:
PIF_IS_PHYSICAL
You tried to destroy a PIF, but it represents an aspect of the physical host configuration, and so cannot be destroyed. The parameter echoes the PIF handle you gave.
Published in:
XenServer 4.0 (rio)
Destroy the PIF object (provided it is a VLAN interface)
Deprecated in:
XenServer 4.1 (miami)
Replaced by VLAN.destroy and Bond.destroy
voidforget(session ref, PIF ref)
Destroy the PIF object matching a particular network interface
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
The PIF object to destroy
Minimum role:
pool-operator
Errors:
PIF_TUNNEL_STILL_EXISTS
Operation cannot proceed while a tunnel exists on this interface.
CLUSTERING_ENABLED
An operation was attempted while clustering was enabled on the cluster_host.
Published in:
XenServer 4.1 (miami)
Destroy the PIF object matching a particular network interface
PIF ref setget_all(session ref)
Return a list of all the PIFs known to the system.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
references to all objects
Published in:
XenServer 4.0 (rio)
A physical network interface (note separate VLANs are represented as several PIFs)
Return a map of PIF references to PIF records for all PIFs known to the system.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
records of all objects
Published in:
XenServer 4.0 (rio)
A physical network interface (note separate VLANs are represented as several PIFs)
Bond ref setget_bond_master_of(session ref, PIF ref)
Get the bond_master_of field of the given PIF.
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
Indicates this PIF represents the results of a bond
Bond refget_bond_slave_of(session ref, PIF ref)
Get the bond_slave_of field of the given PIF.
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
Indicates which bond this interface is part of
PIF refget_by_uuid(session ref, string)
Get a reference to the PIF instance with the specified UUID.
Parameters:
session ref session_id
Reference to a valid session
string uuid
UUID of object to return
Minimum role:
read-only
Result:
reference to the object
Published in:
XenServer 4.0 (rio)
A physical network interface (note separate VLANs are represented as several PIFs)
string setget_capabilities(session ref, PIF ref)
Get the capabilities field of the given PIF.
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
boolget_currently_attached(session ref, PIF ref)
Get the currently_attached field of the given PIF.
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
true if this interface is online
stringget_device(session ref, PIF ref)
Get the device field of the given PIF.
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
machine-readable name of the interface (e.g. eth0)
boolget_disallow_unplug(session ref, PIF ref)
Get the disallow_unplug field of the given PIF.
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Prevent this PIF from being unplugged; set this to notify the management tool-stack that the PIF has a special use and should not be unplugged under any circumstances (e.g. because you're running storage traffic over it)
stringget_DNS(session ref, PIF ref)
Get the DNS field of the given PIF.
Parameters:
session ref session_id
Reference to a valid session
PIF ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
Comma separated list of the IP addresses of the DNS servers to use
This operation cannot be performed because it would invalidate VM failover planning such that the system would be unable to guarantee to restart protected VMs after a Host failure.
VIF_IN_USE
Network has active VIFs
PIF_DOES_NOT_ALLOW_UNPLUG
The operation you requested cannot be performed because the specified PIF does not allow unplug.
PIF_HAS_FCOE_SR_IN_USE
The operation you requested cannot be performed because the specified PIF has FCoE SR in use.
Published in:
XenServer 4.1 (miami)
Attempt to bring down a physical interface
PIF_metrics
Class: PIF_metrics
The metrics associated with a physical network interface
Published in:
XenServer 4.0 (rio)
The metrics associated with a physical network interface
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
(string → blob ref) mapblobs[RO/runtime]
Binary blobs associated with this pool
Default value:
{}
Published in:
XenServer 5.0 (orlando)
Binary blobs associated with this pool
boolclient_certificate_auth_enabled[RO/runtime]
True if authentication by TLS client certificates is enabled
Default value:
false
Published in:
XAPI 1.318.0 (1.318.0)
stringclient_certificate_auth_name[RO/runtime]
The name (CN/SAN) that an incoming client certificate must have to allow authentication
Default value:
""
Published in:
XAPI 1.318.0 (1.318.0)
boolcoordinator_bias[RW]
true if bias against pool master when scheduling vms is enabled, false otherwise
Default value:
true
Prototyped in:
XAPI 22.37.0 (22.37.0)
Published in:
XenServer 4.0 (rio)
true if bias against pool master when scheduling vms is enabled, false otherwise
If set to false then operations which would cause the Pool to become overcommitted will be blocked.
Default value:
false
Published in:
XenServer 5.0 (orlando)
If set to false then operations which would cause the Pool to become overcommitted will be blocked.
stringha_cluster_stack[RO/runtime]
The HA cluster stack that is currently in use. Only valid when HA is enabled.
Default value:
""
Published in:
XenServer 7.0 (dundee)
The HA cluster stack that is currently in use. Only valid when HA is enabled.
(string → string) mapha_configuration[RO/runtime]
The current HA configuration
Default value:
{}
Published in:
XenServer 5.0 (orlando)
The current HA configuration
boolha_enabled[RO/runtime]
true if HA is enabled on the pool, false otherwise
Default value:
false
Published in:
XenServer 5.0 (orlando)
true if HA is enabled on the pool, false otherwise
intha_host_failures_to_tolerate[RO/runtime]
Number of host failures to tolerate before the Pool is declared to be overcommitted
Default value:
0
Published in:
XenServer 5.0 (orlando)
Number of host failures to tolerate before the Pool is declared to be overcommitted
boolha_overcommitted[RO/runtime]
True if the Pool is considered to be overcommitted i.e. if there exist insufficient physical resources to tolerate the configured number of host failures
Default value:
false
Published in:
XenServer 5.0 (orlando)
True if the Pool is considered to be overcommitted i.e. if there exist insufficient physical resources to tolerate the configured number of host failures
intha_plan_exists_for[RO/runtime]
Number of future host failures we have managed to find a plan for. Once this reaches zero any future host failures will cause the failure of protected VMs.
Default value:
0
Published in:
XenServer 5.0 (orlando)
Number of future host failures we have managed to find a plan for. Once this reaches zero any future host failures will cause the failure of protected VMs.
string setha_statefiles[RO/runtime]
HA statefile VDIs in use
Default value:
{}
Published in:
XenServer 5.0 (orlando)
HA statefile VDIs in use
(string → string) maphealth_check_config[RW]
Configuration for the automatic health check feature
Default value:
{}
Published in:
XenServer 7.0 (dundee)
Configuration for the automatic health check feature
booligmp_snooping_enabled[RO/runtime]
true if IGMP snooping is enabled in the pool, false otherwise.
Default value:
false
Published in:
XenServer 7.3 (inverness)
true if IGMP snooping is enabled in the pool, false otherwise.
boolis_psr_pending[RW]
True if either a PSR is running or we are waiting for a PSR to be re-run
Default value:
false
Published in:
Citrix Hypervisor 8.2 Hotfix 2 (stockholm_psr)
True if either a PSR is running or we are waiting for a PSR to be re-run
Prototype
datetimelast_update_sync[RO/runtime]
time of the last update sychronization
Default value:
19700101T00:00:00Z
Prototyped in:
XAPI 23.18.0 (23.18.0)
boollive_patching_disabled[RW]
The pool-wide flag to show if the live patching feauture is disabled or not.
Default value:
false
Published in:
XenServer 7.1 (ely)
The pool-wide flag to show if the live patching feauture is disabled or not.
Prototype
intlocal_auth_max_threads[RO/constructor]
Maximum number of threads to use for PAM authentication
Default value:
8
Prototyped in:
XAPI 23.27.0 (23.27.0)
host refmaster[RO/runtime]
The host that is pool master
Published in:
XenServer 4.0 (rio)
The host that is pool master
VDI ref setmetadata_VDIs[RO/runtime]
The set of currently known metadata VDIs for this pool
Published in:
XenServer 6.0 (boston)
The set of currently known metadata VDIs for this pool
Prototype
boolmigration_compression[RW]
Default behaviour during migration, True if stream compression should be used
Default value:
false
Prototyped in:
XAPI 22.33.0 (22.33.0)
stringname_description[RW]
Description
Published in:
XenServer 4.0 (rio)
Description
stringname_label[RW]
Short name
Published in:
XenServer 4.0 (rio)
Short name
(string → string) mapother_config[RW]
additional configuration
Published in:
XenServer 4.0 (rio)
additional configuration
boolpolicy_no_vendor_device[RW]
The pool-wide policy for clients on whether to use the vendor device or not on newly created VMs. This field will also be consulted if the 'has_vendor_device' field is not specified in the VM.create call.
Default value:
false
Published in:
XenServer 7.0 (dundee)
The pool-wide policy for clients on whether to use the vendor device or not on newly created VMs. This field will also be consulted if the 'has_vendor_device' field is not specified in the VM.create call.
boolredo_log_enabled[RO/runtime]
true a redo-log is to be used other than when HA is enabled, false otherwise
Default value:
false
Published in:
XenServer 5.6 (midnight-ride)
true a redo-log is to be used other than when HA is enabled, false otherwise
VDI refredo_log_vdi[RO/runtime]
indicates the VDI to use for the redo-log other than when HA is enabled
Default value:
OpaqueRef:NULL
Published in:
XenServer 5.6 (midnight-ride)
indicates the VDI to use for the redo-log other than when HA is enabled
Repository ref setrepositories[RO/runtime]
The set of currently enabled repositories
Default value:
{}
Published in:
XAPI 1.301.0 (1.301.0)
The set of currently enabled repositories
secret refrepository_proxy_password[RO/runtime]
Password for the authentication of the proxy used in syncing with the enabled repositories
Default value:
OpaqueRef:NULL
Published in:
XAPI 21.3.0 (21.3.0)
Changed in:
XAPI 23.9.0 (23.9.0)
Changed internal_only to false
stringrepository_proxy_url[RO/runtime]
Url of the proxy used in syncing with the enabled repositories
Default value:
""
Published in:
XAPI 21.3.0 (21.3.0)
Url of the proxy used in syncing with the enabled repositories
stringrepository_proxy_username[RO/runtime]
Username for the authentication of the proxy used in syncing with the enabled repositories
Default value:
""
Published in:
XAPI 21.3.0 (21.3.0)
Username for the authentication of the proxy used in syncing with the enabled repositories
(string → string) maprestrictions[RO/runtime]
Pool-wide restrictions currently in effect
Default value:
{}
Published in:
XenServer 5.6 (midnight-ride)
Pool-wide restrictions currently in effect
SR refsuspend_image_SR[RW]
The SR in which VDIs for suspend images are created
Published in:
XenServer 4.0 (rio)
The SR in which VDIs for suspend images are created
List the names of all installed TLS CA certificates.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Result:
All installed certificates
Published in:
XenServer 5.5 (george)
List installed TLS CA certificate
Deprecated in:
XAPI 1.290.0 (1.290.0)
Use openssl to inspect certificate
voidcertificate_sync(session ref)
Copy the TLS CA certificates and CRLs of the master to all slaves.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Published in:
XenServer 5.5 (george)
Copy the TLS CA certificates and CRLs of the master to all slaves.
Deprecated
voidcertificate_uninstall(session ref, string)
Remove a pool-wide TLS CA certificate.
Parameters:
session ref session_id
Reference to a valid session
string name
The certificate name
Minimum role:
pool-operator
Published in:
XenServer 5.5 (george)
Install TLS CA certificate
Deprecated in:
XAPI 1.290.0 (1.290.0)
Use Pool.uninstall_ca_certificate instead
string set setcheck_update_readiness(session ref, pool ref, bool)
Check if the pool is ready to be updated. If not, report the reasons.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
bool requires_reboot
Assume that the update will require host reboots
Minimum role:
client-cert
Result:
A set of error codes with arguments, if the pool is
not ready to update. An empty list means the pool can be updated.
Published in:
XAPI 1.304.0 (1.304.0)
voidconfigure_repository_proxy(session ref, pool ref, string, string, string)
Configure proxy for RPM package repositories.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
string url
The URL of the proxy server
string username
The username used to authenticate with the proxy server
string password
The password used to authenticate with the proxy server
Minimum role:
client-cert
Published in:
XAPI 21.3.0 (21.3.0)
Configure proxy for RPM package repositories.
Prototype
voidconfigure_update_sync(session ref, pool ref, enum update_sync_frequency, int)
Configure periodic update synchronization to sync updates from a remote CDN
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
enum update_sync_frequency update_sync_frequency
The frequency at which updates are synchronized from a remote CDN: daily or weekly.
int update_sync_day
The day of the week the update synchronization will happen, based on pool's local timezone. Valid values are 0 to 6, 0 being Sunday. For 'daily' schedule, the value is ignored.
Minimum role:
pool-operator
Prototyped in:
XAPI 23.18.0 (23.18.0)
blob refcreate_new_blob(session ref, pool ref, string, string, bool)
Create a placeholder for a named binary blob of data that is associated with this pool
Parameters:
session ref session_id
Reference to a valid session
pool ref pool
The pool
string name
The name associated with the blob
string mime_type
The mime type for the data. Empty string translates to application/octet-stream
bool public
True if the blob should be publicly available
Minimum role:
pool-operator
Result:
The reference of the blob, needed for populating its data
Published in:
XenServer 5.0 (orlando)
Create a placeholder for a named binary blob of data that is associated with this pool
physical interface on any particular host, that identifies the PIF on which to create the (pool-wide) VLAN interface
network ref network
network to which this interface should be connected
int VLAN
VLAN tag for the new interface
Minimum role:
pool-operator
Result:
The references of the created PIF objects
Errors:
VLAN_TAG_INVALID
You tried to create a VLAN, but the tag you gave was invalid -- it must be between 0 and 4094. The parameter echoes the VLAN tag you gave.
Published in:
XenServer 4.0 (rio)
Create a pool-wide VLAN by taking the PIF.
voidcrl_install(session ref, string, string)
Install a TLS CA-issued Certificate Revocation List, pool-wide.
Parameters:
session ref session_id
Reference to a valid session
string name
A name to give the CRL
string cert
The CRL
Minimum role:
pool-operator
Published in:
XenServer 5.5 (george)
Install a TLS CA-issued Certificate Revocation List, pool-wide.
string setcrl_list(session ref)
List the names of all installed TLS CA-issued Certificate Revocation Lists.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Result:
The names of all installed CRLs
Published in:
XenServer 5.5 (george)
List the names of all installed TLS CA-issued Certificate Revocation Lists.
voidcrl_uninstall(session ref, string)
Remove a pool-wide TLS CA-issued Certificate Revocation List.
Parameters:
session ref session_id
Reference to a valid session
string name
The CRL name
Minimum role:
pool-operator
Published in:
XenServer 5.5 (george)
Remove a pool-wide TLS CA-issued Certificate Revocation List.
voiddeconfigure_wlb(session ref)
Permanently deconfigures workload balancing monitoring on this pool
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Published in:
XenServer 5.5 (george)
Permanently deconfigures workload balancing monitoring on this pool
voiddesignate_new_master(session ref, host ref)
Perform an orderly handover of the role of master to the referenced host.
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host who should become the new master
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
Perform an orderly handover of the role of master to the referenced host.
voiddetect_nonhomogeneous_external_auth(session ref, pool ref)
This call asynchronously detects if the external authentication configuration in any slave is different from that in the master and raises appropriate alerts
Parameters:
session ref session_id
Reference to a valid session
pool ref pool
The pool where to detect non-homogeneous external authentication configuration
Minimum role:
pool-operator
Published in:
XenServer 5.5 (george)
This call asynchronously detects if the external authentication configuration in any slave is different from that in the master and raises appropriate alerts
voiddisable_client_certificate_auth(session ref, pool ref)
Disable client certificate authentication on the pool
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
Minimum role:
client-cert
Published in:
XAPI 1.318.0 (1.318.0)
voiddisable_external_auth(session ref, pool ref, (string → string) map)
This call disables external authentication on all the hosts of the pool
Parameters:
session ref session_id
Reference to a valid session
pool ref pool
The pool whose external authentication should be disabled
(string → string) map config
Optional parameters as a list of key-values containing the configuration data
Minimum role:
pool-admin
Published in:
XenServer 5.5 (george)
This call disables external authentication on all the hosts of the pool
voiddisable_ha(session ref)
Turn off High Availability mode
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
client-cert
Published in:
XenServer 4.1 (miami)
Turn off High Availability mode
voiddisable_local_storage_caching(session ref, pool ref)
This call disables pool-wide local storage caching
Parameters:
session ref session_id
Reference to a valid session
pool ref self
Reference to the pool
Minimum role:
pool-operator
Published in:
XenServer 5.6 FP1 (cowley)
This call disables pool-wide local storage caching
voiddisable_redo_log(session ref)
Disable the redo log if in use, unless HA is enabled.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Published in:
XenServer 5.6 (midnight-ride)
Disable the redo log if in use, unless HA is enabled.
voiddisable_repository_proxy(session ref, pool ref)
Disable the proxy for RPM package repositories.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
Minimum role:
client-cert
Published in:
XAPI 21.4.0 (21.4.0)
Disable the proxy for RPM package repositories.
Deprecated
voiddisable_ssl_legacy(session ref, pool ref)
Sets ssl_legacy false on each host, pool-master last. See Host.ssl_legacy and Host.set_ssl_legacy.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
(ignored)
Minimum role:
pool-operator
Published in:
XenServer 7.0 (dundee)
Deprecated in:
Citrix Hypervisor 8.2 (stockholm)
Legacy SSL no longer supported
voideject(session ref, host ref)
Instruct a pool master to eject a host from the pool
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host to eject
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Instruct a pool master to eject a host from the pool
voidemergency_reset_master(session ref, string)
Instruct a slave already in a pool that the master has changed
Parameters:
session ref session_id
Reference to a valid session
string master_address
The hostname of the master
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Instruct a slave already in a pool that the master has changed
voidemergency_transition_to_master(session ref)
Instruct host that's currently a slave to transition to being master
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Instruct host that's currently a slave to transition to being master
voidenable_client_certificate_auth(session ref, pool ref, string)
Enable client certificate authentication on the pool
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
string name
The name (CN/SAN) that an incoming client certificate must have to allow authentication
Minimum role:
client-cert
Published in:
XAPI 1.318.0 (1.318.0)
voidenable_external_auth(session ref, pool ref, (string → string) map, string, string)
This call enables external authentication on all the hosts of the pool
Parameters:
session ref session_id
Reference to a valid session
pool ref pool
The pool whose external authentication should be enabled
(string → string) map config
A list of key-values containing the configuration data
string service_name
The name of the service
string auth_type
The type of authentication (e.g. AD for Active Directory)
Minimum role:
pool-admin
Published in:
XenServer 5.5 (george)
This call enables external authentication on all the hosts of the pool
voidenable_ha(session ref, SR ref set, (string → string) map)
Turn on High Availability mode
Parameters:
session ref session_id
Reference to a valid session
SR ref set heartbeat_srs
Set of SRs to use for storage heartbeating
(string → string) map configuration
Detailed HA configuration to apply
Minimum role:
client-cert
Published in:
XenServer 4.1 (miami)
Turn on High Availability mode
voidenable_local_storage_caching(session ref, pool ref)
This call attempts to enable pool-wide local storage caching
Parameters:
session ref session_id
Reference to a valid session
pool ref self
Reference to the pool
Minimum role:
pool-operator
Published in:
XenServer 5.6 FP1 (cowley)
This call attempts to enable pool-wide local storage caching
voidenable_redo_log(session ref, SR ref)
Enable the redo log on the given SR and start using it, unless HA is enabled.
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
SR to hold the redo log.
Minimum role:
pool-operator
Published in:
XenServer 5.6 (midnight-ride)
Enable the redo log on the given SR and start using it, unless HA is enabled.
Removed
voidenable_ssl_legacy(session ref, pool ref)
Sets ssl_legacy true on each host, pool-master last. See Host.ssl_legacy and Host.set_ssl_legacy.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
(ignored)
Minimum role:
pool-operator
Published in:
XenServer 7.0 (dundee)
Deprecated in:
XenServer 7.0 (dundee)
Legacy SSL will soon cease to be supported
Removed in:
Citrix Hypervisor 8.2 (stockholm)
Legacy SSL no longer supported
voidenable_tls_verification(session ref)
Enable TLS server certificate verification
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-admin
Published in:
XAPI 1.290.0 (1.290.0)
pool ref setget_all(session ref)
Return a list of all the pools known to the system.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
references to all objects
Published in:
XenServer 4.0 (rio)
Pool-wide information
(pool ref → pool record) mapget_all_records(session ref)
Return a map of pool references to pool records for all pools known to the system.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
records of all objects
Published in:
XenServer 4.0 (rio)
Pool-wide information
enum pool_allowed_operations setget_allowed_operations(session ref, pool ref)
Get the allowed_operations field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
(string → blob ref) mapget_blobs(session ref, pool ref)
Get the blobs field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Binary blobs associated with this pool
pool refget_by_uuid(session ref, string)
Get a reference to the pool instance with the specified UUID.
Parameters:
session ref session_id
Reference to a valid session
string uuid
UUID of object to return
Minimum role:
read-only
Result:
reference to the object
Published in:
XenServer 4.0 (rio)
Pool-wide information
boolget_client_certificate_auth_enabled(session ref, pool ref)
Get the client_certificate_auth_enabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XAPI 1.318.0 (1.318.0)
stringget_client_certificate_auth_name(session ref, pool ref)
Get the client_certificate_auth_name field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XAPI 1.318.0 (1.318.0)
boolget_coordinator_bias(session ref, pool ref)
Get the coordinator_bias field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 22.37.0 (22.37.0)
Published in:
XenServer 4.0 (rio)
true if bias against pool master when scheduling vms is enabled, false otherwise
(string → string) mapget_cpu_info(session ref, pool ref)
Get the cpu_info field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
Details about the physical CPUs on the pool
SR refget_crash_dump_SR(session ref, pool ref)
Get the crash_dump_SR field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
The SR in which VDIs for crash dumps are created
(string → enum pool_allowed_operations) mapget_current_operations(session ref, pool ref)
Get the current_operations field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
Prototype
stringget_custom_uefi_certificates(session ref, pool ref)
Get the custom_uefi_certificates field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 24.0.0 (24.0.0)
SR refget_default_SR(session ref, pool ref)
Get the default_SR field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Default SR for VDIs
Prototype
intget_ext_auth_max_threads(session ref, pool ref)
Get the ext_auth_max_threads field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.27.0 (23.27.0)
(string → string) mapget_guest_agent_config(session ref, pool ref)
Get the guest_agent_config field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
Pool-wide guest agent configuration information
(string → string) mapget_gui_config(session ref, pool ref)
Get the gui_config field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
gui-specific configuration for pool
boolget_ha_allow_overcommit(session ref, pool ref)
Get the ha_allow_overcommit field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
If set to false then operations which would cause the Pool to become overcommitted will be blocked.
stringget_ha_cluster_stack(session ref, pool ref)
Get the ha_cluster_stack field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
The HA cluster stack that is currently in use. Only valid when HA is enabled.
(string → string) mapget_ha_configuration(session ref, pool ref)
Get the ha_configuration field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
The current HA configuration
boolget_ha_enabled(session ref, pool ref)
Get the ha_enabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
true if HA is enabled on the pool, false otherwise
intget_ha_host_failures_to_tolerate(session ref, pool ref)
Get the ha_host_failures_to_tolerate field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Number of host failures to tolerate before the Pool is declared to be overcommitted
boolget_ha_overcommitted(session ref, pool ref)
Get the ha_overcommitted field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
True if the Pool is considered to be overcommitted i.e. if there exist insufficient physical resources to tolerate the configured number of host failures
intget_ha_plan_exists_for(session ref, pool ref)
Get the ha_plan_exists_for field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Number of future host failures we have managed to find a plan for. Once this reaches zero any future host failures will cause the failure of protected VMs.
string setget_ha_statefiles(session ref, pool ref)
Get the ha_statefiles field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
HA statefile VDIs in use
(string → string) mapget_health_check_config(session ref, pool ref)
Get the health_check_config field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
Configuration for the automatic health check feature
boolget_igmp_snooping_enabled(session ref, pool ref)
Get the igmp_snooping_enabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.3 (inverness)
true if IGMP snooping is enabled in the pool, false otherwise.
boolget_is_psr_pending(session ref, pool ref)
Get the is_psr_pending field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
Citrix Hypervisor 8.2 Hotfix 2 (stockholm_psr)
True if either a PSR is running or we are waiting for a PSR to be re-run
Prototype
datetimeget_last_update_sync(session ref, pool ref)
Get the last_update_sync field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.18.0 (23.18.0)
(string → string) mapget_license_state(session ref, pool ref)
This call returns the license state for the pool
Parameters:
session ref session_id
Reference to a valid session
pool ref self
Reference to the pool
Minimum role:
read-only
Result:
The pool's license state
Published in:
XenServer 6.2 (clearwater)
This call returns the license state for the pool
boolget_live_patching_disabled(session ref, pool ref)
Get the live_patching_disabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.1 (ely)
The pool-wide flag to show if the live patching feauture is disabled or not.
Prototype
intget_local_auth_max_threads(session ref, pool ref)
Get the local_auth_max_threads field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.27.0 (23.27.0)
host refget_master(session ref, pool ref)
Get the master field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
The host that is pool master
VDI ref setget_metadata_VDIs(session ref, pool ref)
Get the metadata_VDIs field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The set of currently known metadata VDIs for this pool
Prototype
boolget_migration_compression(session ref, pool ref)
Get the migration_compression field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 22.33.0 (22.33.0)
stringget_name_description(session ref, pool ref)
Get the name_description field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Description
stringget_name_label(session ref, pool ref)
Get the name_label field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Short name
(string → string) mapget_other_config(session ref, pool ref)
Get the other_config field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
additional configuration
boolget_policy_no_vendor_device(session ref, pool ref)
Get the policy_no_vendor_device field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
The pool-wide policy for clients on whether to use the vendor device or not on newly created VMs. This field will also be consulted if the 'has_vendor_device' field is not specified in the VM.create call.
pool recordget_record(session ref, pool ref)
Get a record containing the current state of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
all fields from the object
Published in:
XenServer 4.0 (rio)
Pool-wide information
boolget_redo_log_enabled(session ref, pool ref)
Get the redo_log_enabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
true a redo-log is to be used other than when HA is enabled, false otherwise
VDI refget_redo_log_vdi(session ref, pool ref)
Get the redo_log_vdi field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
indicates the VDI to use for the redo-log other than when HA is enabled
Repository ref setget_repositories(session ref, pool ref)
Get the repositories field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XAPI 1.301.0 (1.301.0)
The set of currently enabled repositories
secret refget_repository_proxy_password(session ref, pool ref)
Get the repository_proxy_password field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XAPI 21.3.0 (21.3.0)
Changed in:
XAPI 23.9.0 (23.9.0)
Changed internal_only to false
stringget_repository_proxy_url(session ref, pool ref)
Get the repository_proxy_url field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XAPI 21.3.0 (21.3.0)
Url of the proxy used in syncing with the enabled repositories
stringget_repository_proxy_username(session ref, pool ref)
Get the repository_proxy_username field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XAPI 21.3.0 (21.3.0)
Username for the authentication of the proxy used in syncing with the enabled repositories
(string → string) mapget_restrictions(session ref, pool ref)
Get the restrictions field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
Pool-wide restrictions currently in effect
SR refget_suspend_image_SR(session ref, pool ref)
Get the suspend_image_SR field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
The SR in which VDIs for suspend images are created
string setget_tags(session ref, pool ref)
Get the tags field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
Prototype
enum telemetry_frequencyget_telemetry_frequency(session ref, pool ref)
Get the telemetry_frequency field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.9.0 (23.9.0)
Prototype
datetimeget_telemetry_next_collection(session ref, pool ref)
Get the telemetry_next_collection field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.9.0 (23.9.0)
Prototype
secret refget_telemetry_uuid(session ref, pool ref)
Get the telemetry_uuid field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.9.0 (23.9.0)
boolget_tls_verification_enabled(session ref, pool ref)
Get the tls_verification_enabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XAPI 1.290.0 (1.290.0)
stringget_uefi_certificates(session ref, pool ref)
Get the uefi_certificates field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
Citrix Hypervisor 8.1 (quebec)
The UEFI certificates allowing Secure Boot
Changed in:
XAPI 22.16.0 (22.16.0)
Became StaticRO to be editable through new method
Prototype
intget_update_sync_day(session ref, pool ref)
Get the update_sync_day field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.18.0 (23.18.0)
Prototype
boolget_update_sync_enabled(session ref, pool ref)
Get the update_sync_enabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.18.0 (23.18.0)
Prototype
enum update_sync_frequencyget_update_sync_frequency(session ref, pool ref)
Get the update_sync_frequency field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.18.0 (23.18.0)
stringget_uuid(session ref, pool ref)
Get the uuid field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
Deprecated
stringget_vswitch_controller(session ref, pool ref)
Get the vswitch_controller field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
the IP address of the vswitch controller.
Deprecated in:
XenServer 7.2 (falcon)
Deprecated: set the IP address of the vswitch controller in SDN_controller instead.
boolget_wlb_enabled(session ref, pool ref)
Get the wlb_enabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.5 (george)
true if workload balancing is enabled on the pool, false otherwise
stringget_wlb_url(session ref, pool ref)
Get the wlb_url field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.5 (george)
Url for the configured workload balancing host
stringget_wlb_username(session ref, pool ref)
Get the wlb_username field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.5 (george)
Username for accessing the workload balancing host
Deprecated
boolget_wlb_verify_cert(session ref, pool ref)
Get the wlb_verify_cert field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.5 (george)
Deprecated in:
XAPI 1.290.0 (1.290.0)
Deprecated: to enable TLS verification use Pool.enable_tls_verification instead
Return a VM failover plan assuming a given subset of hosts fail
Parameters:
session ref session_id
Reference to a valid session
host ref set failed_hosts
The set of hosts to assume have failed
VM ref set failed_vms
The set of VMs to restart
Minimum role:
pool-operator
Result:
VM failover plan: a map of VM to host to restart the host on
Published in:
XenServer 5.0 (orlando)
Return a VM failover plan assuming a given subset of hosts fail
boolha_failover_plan_exists(session ref, int)
Returns true if a VM failover plan exists for up to 'n' host failures
Parameters:
session ref session_id
Reference to a valid session
int n
The number of host failures to plan for
Minimum role:
pool-operator
Result:
true if a failover plan exists for the supplied number of host failures
Published in:
XenServer 5.0 (orlando)
Returns true if a VM failover plan exists for up to 'n' host failures
voidha_prevent_restarts_for(session ref, int)
When this call returns the VM restart logic will not run for the requested number of seconds. If the argument is zero then the restart thread is immediately unblocked
Parameters:
session ref session_id
Reference to a valid session
int seconds
The number of seconds to block the restart thread for
Minimum role:
pool-operator
Published in:
XenServer 5.0 Update 1 (orlando-update-1)
When this call returns the VM restart logic will not run for the requested number of seconds. If the argument is zero then the restart thread is immediately unblocked
boolhas_extension(session ref, pool ref, string)
Return true if the extension is available on the pool
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
string name
The name of the API call
Minimum role:
pool-admin
Result:
True if the extension exists, false otherwise
Published in:
XenServer 7.0 (dundee)
Return true if the extension is available on the pool
Sets the pool optimization criteria for the workload balancing server
Parameters:
session ref session_id
Reference to a valid session
(string → string) map config
The configuration to use in optimizing this pool
Minimum role:
pool-operator
Published in:
XenServer 5.5 (george)
Sets the pool optimization criteria for the workload balancing server
voidset_coordinator_bias(session ref, pool ref, bool)
Set the coordinator_bias field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
bool value
New value to set
Minimum role:
pool-operator
Prototyped in:
XAPI 22.37.0 (22.37.0)
Published in:
XenServer 4.0 (rio)
true if bias against pool master when scheduling vms is enabled, false otherwise
voidset_crash_dump_SR(session ref, pool ref, SR ref)
Set the crash_dump_SR field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
SR ref value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
The SR in which VDIs for crash dumps are created
Prototype
voidset_custom_uefi_certificates(session ref, pool ref, string)
Set custom UEFI certificates for a pool and all its hosts. Need `allow-custom-uefi-certs` set to true in conf. If empty: default back to Pool.uefi_certificates
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
string value
The certificates to apply to the pool and its hosts
Minimum role:
pool-admin
Prototyped in:
XAPI 24.0.0 (24.0.0)
voidset_default_SR(session ref, pool ref, SR ref)
Set the default_SR field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
SR ref value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Default SR for VDIs
Prototype
voidset_ext_auth_max_threads(session ref, pool ref, int)
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
int value
The new maximum
Minimum role:
pool-operator
Prototyped in:
XAPI 23.27.0 (23.27.0)
voidset_gui_config(session ref, pool ref, (string → string) map)
Set the gui_config field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
gui-specific configuration for pool
voidset_ha_allow_overcommit(session ref, pool ref, bool)
Set the ha_allow_overcommit field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
bool value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 5.0 (orlando)
If set to false then operations which would cause the Pool to become overcommitted will be blocked.
voidset_ha_host_failures_to_tolerate(session ref, pool ref, int)
Set the maximum number of host failures to consider in the HA VM restart planner
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
int value
New number of host failures to consider
Minimum role:
pool-operator
Published in:
XenServer 5.0 (orlando)
Set the maximum number of host failures to consider in the HA VM restart planner
voidset_health_check_config(session ref, pool ref, (string → string) map)
Set the health_check_config field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 7.0 (dundee)
Configuration for the automatic health check feature
Prototype
voidset_https_only(session ref, pool ref, bool)
updates all the host firewalls in the pool to open or close port 80 depending on the value
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
bool value
true - http port 80 will be blocked, false - http port 80 will be open for the hosts in the pool
Minimum role:
pool-operator
Prototyped in:
XAPI 22.27.0 (22.27.0)
voidset_igmp_snooping_enabled(session ref, pool ref, bool)
Enable or disable IGMP Snooping on the pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
bool value
Enable or disable IGMP Snooping on the pool
Minimum role:
pool-operator
Published in:
XenServer 7.3 (inverness)
Enable or disable IGMP Snooping on the pool.
voidset_is_psr_pending(session ref, pool ref, bool)
Set the is_psr_pending field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
bool value
New value to set
Minimum role:
pool-operator
Published in:
Citrix Hypervisor 8.2 Hotfix 2 (stockholm_psr)
True if either a PSR is running or we are waiting for a PSR to be re-run
voidset_live_patching_disabled(session ref, pool ref, bool)
Set the live_patching_disabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
bool value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 7.1 (ely)
The pool-wide flag to show if the live patching feauture is disabled or not.
Prototype
voidset_local_auth_max_threads(session ref, pool ref, int)
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
int value
The new maximum
Minimum role:
pool-operator
Prototyped in:
XAPI 23.27.0 (23.27.0)
Prototype
voidset_migration_compression(session ref, pool ref, bool)
Set the migration_compression field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
bool value
New value to set
Minimum role:
pool-operator
Prototyped in:
XAPI 22.33.0 (22.33.0)
voidset_name_description(session ref, pool ref, string)
Set the name_description field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
string value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Description
voidset_name_label(session ref, pool ref, string)
Set the name_label field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
string value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Short name
voidset_other_config(session ref, pool ref, (string → string) map)
Set the other_config field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
additional configuration
voidset_policy_no_vendor_device(session ref, pool ref, bool)
Set the policy_no_vendor_device field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
bool value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 7.0 (dundee)
The pool-wide policy for clients on whether to use the vendor device or not on newly created VMs. This field will also be consulted if the 'has_vendor_device' field is not specified in the VM.create call.
voidset_repositories(session ref, pool ref, Repository ref set)
Set enabled set of repositories
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
Repository ref set value
The set of repositories to be enabled
Minimum role:
client-cert
Published in:
XAPI 1.301.0 (1.301.0)
Set enabled set of repositories
voidset_suspend_image_SR(session ref, pool ref, SR ref)
Set the suspend_image_SR field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
SR ref value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
The SR in which VDIs for suspend images are created
voidset_tags(session ref, pool ref, string set)
Set the tags field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
string set value
New value to set
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
Prototype
voidset_telemetry_next_collection(session ref, pool ref, datetime)
Set the timestamp for the next telemetry data collection.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
datetime value
The earliest timestamp (in UTC) when the next round of telemetry collection can be carried out.
Minimum role:
pool-admin
Prototyped in:
XAPI 23.9.0 (23.9.0)
Deprecated
voidset_uefi_certificates(session ref, pool ref, string)
Set the UEFI certificates for a pool and all its hosts. Deprecated: use set_custom_uefi_certificates instead
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
string value
The certificates to apply to the pool and its hosts
Minimum role:
pool-admin
Published in:
XAPI 22.16.0 (22.16.0)
Deprecated in:
XAPI 24.0.0 (24.0.0)
use set_custom_uefi_certificates instead
Prototype
voidset_update_sync_enabled(session ref, pool ref, bool)
enable or disable periodic update synchronization depending on the value
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
bool value
true - enable periodic update synchronization, false - disable it
Minimum role:
pool-operator
Prototyped in:
XAPI 23.18.0 (23.18.0)
Deprecated
voidset_vswitch_controller(session ref, string)
Set the IP address of the vswitch controller.
Parameters:
session ref session_id
Reference to a valid session
string address
IP address of the vswitch controller.
Minimum role:
pool-operator
Published in:
XenServer 5.6 (midnight-ride)
Set the IP address of the vswitch controller.
Extended in:
XenServer 5.6 FP1 (cowley)
Allow to be set to the empty string (no controller is used).
Deprecated in:
XenServer 7.2 (falcon)
Deprecated: use 'SDN_controller.introduce' and 'SDN_controller.forget' instead.
voidset_wlb_enabled(session ref, pool ref, bool)
Set the wlb_enabled field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
bool value
New value to set
Minimum role:
client-cert
Published in:
XenServer 5.5 (george)
true if workload balancing is enabled on the pool, false otherwise
Deprecated
voidset_wlb_verify_cert(session ref, pool ref, bool)
Set the wlb_verify_cert field of the given pool.
Parameters:
session ref session_id
Reference to a valid session
pool ref self
reference to the object
bool value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 5.5 (george)
Deprecated in:
XAPI 1.290.0 (1.290.0)
Deprecated: to enable TLS verification use Pool.enable_tls_verification instead
voidsync_database(session ref)
Forcibly synchronise the database now
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Forcibly synchronise the database now
stringsync_updates(session ref, pool ref, bool, string, string)
Sync with the enabled repository
Parameters:
session ref session_id
Reference to a valid session
pool ref self
The pool
bool force
If true local mirroring repo will be removed before syncing
string token
The token for repository client authentication
string token_id
The ID of the token
Minimum role:
client-cert
Result:
The SHA256 hash of updateinfo.xml.gz
Published in:
XAPI 1.329.0 (1.329.0)
Sync with the enabled repository
stringtest_archive_target(session ref, pool ref, (string → string) map)
This call tests if a location is valid
Parameters:
session ref session_id
Reference to a valid session
pool ref self
Reference to the pool
(string → string) map config
Location config settings to test
Minimum role:
pool-operator
Result:
An XMLRPC result
Published in:
XenServer 5.6 FP1 (cowley)
This call tests if a location is valid
voiduninstall_ca_certificate(session ref, string)
Remove a pool-wide TLS CA certificate.
Parameters:
session ref session_id
Reference to a valid session
string name
The certificate name
Minimum role:
client-cert
Published in:
XAPI 1.290.0 (1.290.0)
Uninstall TLS CA certificate
pool_patch
Deprecated
Class: pool_patch
Pool-wide patches
Published in:
XenServer 4.1 (miami)
Pool-wide patches
Deprecated in:
XenServer 7.1 (ely)
Enums
after_apply_guidance
Values:
restartHVM
This patch requires HVM guests to be restarted once applied.
restartPV
This patch requires PV guests to be restarted once applied.
restartHost
This patch requires the host to be restarted once applied.
restartXAPI
This patch requires XAPI to be restarted once applied.
Set the other_config field of the given pool_update.
Parameters:
session ref session_id
Reference to a valid session
pool_update ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 7.3 (inverness)
additional configuration
probe_result
Class: probe_result
A set of properties that describe one result element of SR.probe. Result elements and properties can change dynamically based on changes to the the SR.probe input-parameters or the target.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
Fields
boolcomplete[RO/runtime]
True if this configuration is complete and can be used to call SR.create. False if it requires further iterative calls to SR.probe, to potentially narrow down on a configuration that can be used.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
(string → string) mapconfiguration[RO/runtime]
Plugin-specific configuration which describes where and how to locate the storage repository. This may include the physical block device name, a remote NFS server and path or an RBD storage pool.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
(string → string) mapextra_info[RO/runtime]
Additional plugin-specific information about this configuration, that might be of use for an API user. This can for example include the LUN or the WWPN.
the subject name of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
Default value:
""
Published in:
XenServer 5.6 (midnight-ride)
the subject name of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
stringauth_user_sid[RO/runtime]
the subject identifier of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
Default value:
""
Published in:
XenServer 5.5 (george)
the subject identifier of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
boolclient_certificate[RO/runtime]
indicates whether this session was authenticated using a client certificate
Default value:
false
Published in:
XAPI 21.2.0 (21.2.0)
indicates whether this session was authenticated using a client certificate
boolis_local_superuser[RO/runtime]
true iff this session was created using local superuser credentials
Default value:
false
Published in:
XenServer 5.5 (george)
true iff this session was created using local superuser credentials
datetimelast_active[RO/runtime]
Timestamp for last time session was active
Published in:
XenServer 4.0 (rio)
Timestamp for last time session was active
stringoriginator[RO/runtime]
a key string provided by a API user to distinguish itself from other users sharing the same login name
Default value:
""
Published in:
XenServer 6.2 (clearwater)
a key string provided by a API user to distinguish itself from other users sharing the same login name
(string → string) mapother_config[RW]
additional configuration
Default value:
{}
Published in:
XenServer 4.1 (miami)
additional configuration
session refparent[RO/constructor]
references the parent session that created this session
Default value:
OpaqueRef:NULL
Published in:
XenServer 5.6 (midnight-ride)
references the parent session that created this session
boolpool[RO/runtime]
True if this session relates to a intra-pool login, false otherwise
Published in:
XenServer 4.0 (rio)
True if this session relates to a intra-pool login, false otherwise
string setrbac_permissions[RO/constructor]
list with all RBAC permissions for this session
Default value:
{}
Published in:
XenServer 5.6 (midnight-ride)
list with all RBAC permissions for this session
subject refsubject[RO/runtime]
references the subject instance that created the session. If a session instance has is_local_superuser set, then the value of this field is undefined.
Default value:
OpaqueRef:NULL
Published in:
XenServer 5.5 (george)
references the subject instance that created the session. If a session instance has is_local_superuser set, then the value of this field is undefined.
Get the auth_user_name field of the given session.
Parameters:
session ref session_id
Reference to a valid session
session ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
the subject name of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
stringget_auth_user_sid(session ref, session ref)
Get the auth_user_sid field of the given session.
Parameters:
session ref session_id
Reference to a valid session
session ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.5 (george)
the subject identifier of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
session refget_by_uuid(session ref, string)
Get a reference to the session instance with the specified UUID.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
(string → blob ref) mapblobs[RO/runtime]
Binary blobs associated with this SR
Default value:
{}
Published in:
XenServer 5.0 (orlando)
Binary blobs associated with this SR
boolclustered[RO/runtime]
True if the SR is using aggregated local storage
Default value:
false
Published in:
XenServer 7.0 (dundee)
stringcontent_type[RO/constructor]
the type of the SR's content, if required (e.g. ISOs)
Published in:
XenServer 4.0 (rio)
the type of the SR's content, if required (e.g. ISOs)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
Default value:
{}
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
DR_task refintroduced_by[RO/runtime]
The disaster recovery task which introduced this SR
Default value:
OpaqueRef:NULL
Published in:
XenServer 6.0 (boston)
The disaster recovery task which introduced this SR
boolis_tools_sr[RO/runtime]
True if this is the SR that contains the Tools ISO VDIs
Default value:
false
Published in:
XenServer 7.0 (dundee)
boollocal_cache_enabled[RO/runtime]
True if this SR is assigned to be the local cache for its host
Default value:
false
Published in:
XenServer 5.6 FP1 (cowley)
True if this SR is assigned to be the local cache for its host
stringname_description[RO/constructor]
a notes field containing human-readable description
Default value:
""
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringname_label[RO/constructor]
a human-readable name
Default value:
""
Published in:
XenServer 4.0 (rio)
a human-readable name
(string → string) mapother_config[RW]
additional configuration
Published in:
XenServer 4.0 (rio)
additional configuration
PBD ref setPBDs[RO/runtime]
describes how particular hosts can see this storage repository
Published in:
XenServer 4.0 (rio)
describes how particular hosts can see this storage repository
intphysical_size[RO/constructor]
total physical size of the repository (in bytes)
Published in:
XenServer 4.0 (rio)
total physical size of the repository (in bytes)
intphysical_utilisation[RO/runtime]
physical space currently utilised on this storage repository (in bytes). Note that for sparse disk formats, physical_utilisation may be less than virtual_allocation
Published in:
XenServer 4.0 (rio)
physical space currently utilised on this storage repository (in bytes). Note that for sparse disk formats, physical_utilisation may be less than virtual_allocation
boolshared[RO/runtime]
true if this SR is (capable of being) shared between multiple hosts
Published in:
XenServer 4.0 (rio)
true if this SR is (capable of being) shared between multiple hosts
(string → string) mapsm_config[RW]
SM dependent data
Default value:
{}
Published in:
XenServer 4.1 (miami)
SM dependent data
string settags[RW]
user-specified tags for categorization purposes
Default value:
{}
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
stringtype[RO/constructor]
type of the storage repository
Published in:
XenServer 4.0 (rio)
type of the storage repository
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
VDI ref setVDIs[RO/runtime]
all virtual disks known to this storage repository
Published in:
XenServer 4.0 (rio)
all virtual disks known to this storage repository
intvirtual_allocation[RO/runtime]
sum of virtual_sizes of all VDIs in this storage repository (in bytes)
Published in:
XenServer 4.0 (rio)
sum of virtual_sizes of all VDIs in this storage repository (in bytes)
Messages
voidadd_tags(session ref, SR ref, string)
Add the given value to the tags field of the given SR. If the value is already in that Set, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
string value
New value to add
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
voidadd_to_other_config(session ref, SR ref, string, string)
Add the given key-value pair to the other_config field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
additional configuration
voidadd_to_sm_config(session ref, SR ref, string, string)
Add the given key-value pair to the sm_config field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
SM dependent data
voidassert_can_host_ha_statefile(session ref, SR ref)
Returns successfully if the given SR can host an HA statefile. Otherwise returns an error to explain why not
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR to query
Minimum role:
pool-operator
Published in:
XenServer 5.0 (orlando)
Returns successfully if the given SR can host an HA statefile. Otherwise returns an error to explain why not
voidassert_supports_database_replication(session ref, SR ref)
Returns successfully if the given SR supports database replication. Otherwise returns an error to explain why not.
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR to query
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
Returns successfully if the given SR supports database replication. Otherwise returns an error to explain why not.
Create a new Storage Repository and introduce it into the managed system, creating both SR record and PBD record to attach it to current host (with specified device_config parameters)
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host to create/make the SR on
(string → string) map device_config
The device config string that will be passed to backend SR driver
int physical_size
The physical size of the new storage repository
string name_label
The name of the new storage repository
string name_description
The description of the new storage repository
string type
The type of the SR; used to specify the SR backend driver to use
string content_type
The type of the new SRs content, if required (e.g. ISOs)
bool shared
True if the SR (is capable of) being shared by multiple hosts
(string → string) map sm_config
Storage backend specific configuration options
Minimum role:
pool-operator
Result:
The reference of the newly created Storage Repository.
Errors:
SR_UNKNOWN_DRIVER
The SR could not be connected because the driver was not recognised.
Published in:
XenServer 4.0 (rio)
Create a new Storage Repository and introduce it into the managed system, creating both SR record and PBD record to attach it to current host (with specified device_config parameters)
blob refcreate_new_blob(session ref, SR ref, string, string, bool)
Create a placeholder for a named binary blob of data that is associated with this SR
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR
string name
The name associated with the blob
string mime_type
The mime type for the data. Empty string translates to application/octet-stream
bool public
True if the blob should be publicly available
Minimum role:
pool-operator
Result:
The reference of the blob, needed for populating its data
Published in:
XenServer 5.0 (orlando)
Create a placeholder for a named binary blob of data that is associated with this SR
voiddestroy(session ref, SR ref)
Destroy specified SR, removing SR-record from database and remove SR from disk. (In order to affect this operation the appropriate device_config is read from the specified SR's PBD on current host)
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR to destroy
Minimum role:
pool-operator
Errors:
SR_HAS_PBD
The SR is still connected to a host via a PBD. It cannot be destroyed or forgotten.
Published in:
XenServer 4.0 (rio)
Destroy specified SR, removing SR-record from database and remove SR from disk. (In order to affect this operation the appropriate device_config is read from the specified SR's PBD on current host)
voiddisable_database_replication(session ref, SR ref)
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR to which metadata should be no longer replicated
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
voidenable_database_replication(session ref, SR ref)
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR to which metadata should be replicated
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
voidforget(session ref, SR ref)
Removing specified SR-record from database, without attempting to remove SR from disk
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR to destroy
Minimum role:
pool-operator
Errors:
SR_HAS_PBD
The SR is still connected to a host via a PBD. It cannot be destroyed or forgotten.
Published in:
XenServer 4.0 (rio)
Removing specified SR-record from database, without attempting to remove SR from disk
voidforget_data_source_archives(session ref, SR ref, string)
Forget the recorded statistics related to the specified data source
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR
string data_source
The data source whose archives are to be forgotten
Minimum role:
pool-operator
Published in:
XenServer 7.0 (dundee)
Forget the recorded statistics related to the specified data source
SR ref setget_all(session ref)
Return a list of all the SRs known to the system.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
references to all objects
Published in:
XenServer 4.0 (rio)
A storage repository
(SR ref → SR record) mapget_all_records(session ref)
Return a map of SR references to SR records for all SRs known to the system.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
records of all objects
Published in:
XenServer 4.0 (rio)
A storage repository
enum storage_operations setget_allowed_operations(session ref, SR ref)
Get the allowed_operations field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
(string → blob ref) mapget_blobs(session ref, SR ref)
Get the blobs field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Binary blobs associated with this SR
SR ref setget_by_name_label(session ref, string)
Get all the SR instances with the given label.
Parameters:
session ref session_id
Reference to a valid session
string label
label of object to return
Minimum role:
read-only
Result:
references to objects with matching names
Published in:
XenServer 4.0 (rio)
A storage repository
SR refget_by_uuid(session ref, string)
Get a reference to the SR instance with the specified UUID.
Parameters:
session ref session_id
Reference to a valid session
string uuid
UUID of object to return
Minimum role:
read-only
Result:
reference to the object
Published in:
XenServer 4.0 (rio)
A storage repository
boolget_clustered(session ref, SR ref)
Get the clustered field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
stringget_content_type(session ref, SR ref)
Get the content_type field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
the type of the SR's content, if required (e.g. ISOs)
(string → enum storage_operations) mapget_current_operations(session ref, SR ref)
Get the current_operations field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
data_source record setget_data_sources(session ref, SR ref)
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR to interrogate
Minimum role:
read-only
Result:
A set of data sources
Published in:
XenServer 7.0 (dundee)
DR_task refget_introduced_by(session ref, SR ref)
Get the introduced_by field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The disaster recovery task which introduced this SR
boolget_is_tools_sr(session ref, SR ref)
Get the is_tools_sr field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
boolget_local_cache_enabled(session ref, SR ref)
Get the local_cache_enabled field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 FP1 (cowley)
True if this SR is assigned to be the local cache for its host
stringget_name_description(session ref, SR ref)
Get the name/description field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringget_name_label(session ref, SR ref)
Get the name/label field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
a human-readable name
(string → string) mapget_other_config(session ref, SR ref)
Get the other_config field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
additional configuration
PBD ref setget_PBDs(session ref, SR ref)
Get the PBDs field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
describes how particular hosts can see this storage repository
intget_physical_size(session ref, SR ref)
Get the physical_size field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
total physical size of the repository (in bytes)
intget_physical_utilisation(session ref, SR ref)
Get the physical_utilisation field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
physical space currently utilised on this storage repository (in bytes). Note that for sparse disk formats, physical_utilisation may be less than virtual_allocation
SR recordget_record(session ref, SR ref)
Get a record containing the current state of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
all fields from the object
Published in:
XenServer 4.0 (rio)
A storage repository
boolget_shared(session ref, SR ref)
Get the shared field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
true if this SR is (capable of being) shared between multiple hosts
(string → string) mapget_sm_config(session ref, SR ref)
Get the sm_config field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
SM dependent data
string setget_supported_types(session ref)
Return a set of all the SR types supported by the system
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
the supported SR types
Published in:
XenServer 4.0 (rio)
Return a set of all the SR types supported by the system
string setget_tags(session ref, SR ref)
Get the tags field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
stringget_type(session ref, SR ref)
Get the type field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
type of the storage repository
stringget_uuid(session ref, SR ref)
Get the uuid field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
VDI ref setget_VDIs(session ref, SR ref)
Get the VDIs field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
all virtual disks known to this storage repository
intget_virtual_allocation(session ref, SR ref)
Get the virtual_allocation field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
sum of virtual_sizes of all VDIs in this storage repository (in bytes)
Perform a backend-specific scan, using the given device_config. If the device_config is complete, then this will return a list of the SRs present of this type on the device, if any. If the device_config is partial, then a backend-specific scan will be performed, returning results that will guide the user in improving the device_config.
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host to create/make the SR on
(string → string) map device_config
The device config string that will be passed to backend SR driver
string type
The type of the SR; used to specify the SR backend driver to use
(string → string) map sm_config
Storage backend specific configuration options
Minimum role:
pool-operator
Result:
An XML fragment containing the scan results. These are specific to the scan being performed, and the backend.
Published in:
XenServer 4.1 (miami)
Perform a backend-specific scan, using the given device_config. If the device_config is complete, then this will return a list of the SRs present of this type on the device, if any. If the device_config is partial, then a backend-specific scan will be performed, returning results that will guide the user in improving the device_config.
Perform a backend-specific scan, using the given device_config. If the device_config is complete, then this will return a list of the SRs present of this type on the device, if any. If the device_config is partial, then a backend-specific scan will be performed, returning results that will guide the user in improving the device_config.
Parameters:
session ref session_id
Reference to a valid session
host ref host
The host to create/make the SR on
(string → string) map device_config
The device config string that will be passed to backend SR driver
string type
The type of the SR; used to specify the SR backend driver to use
(string → string) map sm_config
Storage backend specific configuration options
Minimum role:
pool-operator
Result:
A set of records containing the scan results.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
floatquery_data_source(session ref, SR ref, string)
Query the latest value of the specified data source
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR
string data_source
The data source to query
Minimum role:
read-only
Result:
The latest value, averaged over the last 5 seconds
Published in:
XenServer 7.0 (dundee)
Query the latest value of the specified data source
voidrecord_data_source(session ref, SR ref, string)
Start recording the specified data source
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR
string data_source
The data source to record
Minimum role:
pool-operator
Published in:
XenServer 7.0 (dundee)
Start recording the specified data source
voidremove_from_other_config(session ref, SR ref, string)
Remove the given key and its corresponding value from the other_config field of the given SR. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
string key
Key to remove
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
additional configuration
voidremove_from_sm_config(session ref, SR ref, string)
Remove the given key and its corresponding value from the sm_config field of the given SR. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
string key
Key to remove
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
SM dependent data
voidremove_tags(session ref, SR ref, string)
Remove the given value from the tags field of the given SR. If the value is not in that Set, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
string value
Value to remove
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
voidscan(session ref, SR ref)
Refreshes the list of VDIs associated with an SR
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR to scan
Minimum role:
vm-power-admin
Published in:
XenServer 4.0 (rio)
Refreshes the list of VDIs associated with an SR
voidset_name_description(session ref, SR ref, string)
Set the name description of the SR
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR
string value
The name description for the SR
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Set the name description of the SR
voidset_name_label(session ref, SR ref, string)
Set the name label of the SR
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR
string value
The name label for the SR
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Set the name label of the SR
voidset_other_config(session ref, SR ref, (string → string) map)
Set the other_config field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
additional configuration
voidset_physical_size(session ref, SR ref, int)
Sets the SR's physical_size field
Parameters:
session ref session_id
Reference to a valid session
SR ref self
The SR to modify
int value
The new value of the SR's physical_size
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
Sets the SR's physical_size field
voidset_shared(session ref, SR ref, bool)
Sets the shared flag on the SR
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR
bool value
True if the SR is shared
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
Sets the shared flag on the SR
voidset_sm_config(session ref, SR ref, (string → string) map)
Set the sm_config field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
SM dependent data
voidset_tags(session ref, SR ref, string set)
Set the tags field of the given SR.
Parameters:
session ref session_id
Reference to a valid session
SR ref self
reference to the object
string set value
New value to set
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
voidupdate(session ref, SR ref)
Refresh the fields on the SR object
Parameters:
session ref session_id
Reference to a valid session
SR ref sr
The SR whose fields should be refreshed
Minimum role:
pool-operator
Published in:
XenServer 4.1.1 (symc)
Refresh the fields on the SR object
sr_stat
Class: sr_stat
A set of high-level properties associated with an SR.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
Enums
sr_health
Values:
healthy
Storage is fully available
recovering
Storage is busy recovering, e.g. rebuilding mirrors.
Fields
boolclustered[RO/runtime]
Indicates whether the SR uses clustered local storage.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
intfree_space[RO/runtime]
Number of bytes free on the backing storage (in bytes)
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
enum sr_healthhealth[RO/runtime]
The health status of the SR.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
stringname_description[RO/runtime]
Longer, human-readable description of the SR. Descriptions are generally only displayed by clients when the user is examining SRs in detail.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
stringname_label[RO/runtime]
Short, human-readable label for the SR.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
inttotal_space[RO/runtime]
Total physical size of the backing storage (in bytes)
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
string optionuuid[RO/runtime]
Uuid that uniquely identifies this SR, if one is available.
Prototyped in:
XenServer 7.5 (kolkata)
Published in:
XenServer 7.6 (lima)
Messages
subject
Class: subject
A user or group that can log in xapi
Published in:
XenServer 5.5 (george)
A user or group that can log in xapi
Fields
(string → string) mapother_config[RO/constructor]
additional configuration
Default value:
{}
Published in:
XenServer 5.5 (george)
additional configuration
role ref setroles[RO/runtime]
the roles associated with this subject
Default value:
{OpaqueRef:0165f154-ba3e-034e-6b27-5d271af109ba}
Published in:
XenServer 5.6 (midnight-ride)
the roles associated with this subject
stringsubject_identifier[RO/constructor]
the subject identifier, unique in the external directory service
Default value:
""
Published in:
XenServer 5.5 (george)
the subject identifier, unique in the external directory service
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
Messages
voidadd_to_roles(session ref, subject ref, role ref)
This call adds a new role to a subject
Parameters:
session ref session_id
Reference to a valid session
subject ref self
The subject who we want to add the role to
role ref role
The unique role reference
Minimum role:
pool-admin
Published in:
XenServer 5.6 (midnight-ride)
This call adds a new role to a subject
subject refcreate(session ref, subject record)
Create a new subject instance, and return its handle.
The constructor args are: subject_identifier, other_config (* = non-optional).
Parameters:
session ref session_id
Reference to a valid session
subject record args
All constructor arguments
Minimum role:
pool-admin
Result:
reference to the newly created object
Published in:
XenServer 5.5 (george)
A user or group that can log in xapi
voiddestroy(session ref, subject ref)
Destroy the specified subject instance.
Parameters:
session ref session_id
Reference to a valid session
subject ref self
reference to the object
Minimum role:
pool-admin
Published in:
XenServer 5.5 (george)
A user or group that can log in xapi
subject ref setget_all(session ref)
Return a list of all the subjects known to the system.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
Default value:
{}
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
string seterror_info[RO/runtime]
if the task has failed, this field contains the set of associated error strings. Undefined otherwise.
Published in:
XenServer 4.0 (rio)
if the task has failed, this field contains the set of associated error strings. Undefined otherwise.
datetimefinished[RO/runtime]
Time task finished (i.e. succeeded or failed). If task-status is pending, then the value of this field has no meaning
Published in:
XenServer 4.0 (rio)
Time task finished (i.e. succeeded or failed). If task-status is pending, then the value of this field has no meaning
stringname_description[RO/runtime]
a notes field containing human-readable description
Default value:
""
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringname_label[RO/runtime]
a human-readable name
Default value:
""
Published in:
XenServer 4.0 (rio)
a human-readable name
(string → string) mapother_config[RW]
additional configuration
Default value:
{}
Published in:
XenServer 4.1 (miami)
additional configuration
floatprogress[RO/runtime]
This field contains the estimated fraction of the task which is complete. This field should not be used to determine whether the task is complete - for this the status field of the task should be used.
Published in:
XenServer 4.0 (rio)
This field contains the estimated fraction of the task which is complete. This field should not be used to determine whether the task is complete - for this the status field of the task should be used.
host refresident_on[RO/runtime]
the host on which the task is running
Published in:
XenServer 4.0 (rio)
the host on which the task is running
stringresult[RO/runtime]
if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise.
Published in:
XenServer 4.0 (rio)
if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise.
enum task_status_typestatus[RO/runtime]
current status of the task
Published in:
XenServer 4.0 (rio)
current status of the task
task refsubtask_of[RO/runtime]
Ref pointing to the task this is a substask of.
Default value:
Null
Published in:
XenServer 5.0 (orlando)
Ref pointing to the task this is a substask of.
task ref setsubtasks[RO/runtime]
List pointing to all the substasks.
Published in:
XenServer 5.0 (orlando)
List pointing to all the substasks.
stringtype[RO/runtime]
if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise.
Published in:
XenServer 4.0 (rio)
if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise.
Add the given key-value pair to the other_config field of the given task.
Parameters:
session ref session_id
Reference to a valid session
task ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
pool-operator
Published in:
XenServer 4.1 (miami)
additional configuration
voidcancel(session ref, task ref)
Request that a task be cancelled. Note that a task may fail to be cancelled and may complete or fail normally and note that, even when a task does cancel, it might take an arbitrary amount of time.
Parameters:
session ref session_id
Reference to a valid session
task ref task
The task
Minimum role:
read-only
Errors:
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
Published in:
XenServer 4.0 (rio)
Request that a task be cancelled. Note that a task may fail to be cancelled and may complete or fail normally and note that, even when a task does cancel, it might take an arbitrary amount of time.
task refcreate(session ref, string, string)
Create a new task object which must be manually destroyed.
Parameters:
session ref session_id
Reference to a valid session
string label
short label for the new task
string description
longer description for the new task
Minimum role:
read-only
Result:
The reference of the created task object
Published in:
XenServer 4.0 (rio)
Create a new task object which must be manually destroyed.
voiddestroy(session ref, task ref)
Destroy the task object
Parameters:
session ref session_id
Reference to a valid session
task ref self
Reference to the task object
Minimum role:
read-only
Published in:
XenServer 4.0 (rio)
Destroy the task object
task ref setget_all(session ref)
Return a list of all the tasks known to the system.
Get the allowed_operations field of the given task.
Parameters:
session ref session_id
Reference to a valid session
task ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
This field contains the estimated fraction of the task which is complete. This field should not be used to determine whether the task is complete - for this the status field of the task should be used.
task recordget_record(session ref, task ref)
Get a record containing the current state of the given task.
Parameters:
session ref session_id
Reference to a valid session
task ref self
reference to the object
Minimum role:
read-only
Result:
all fields from the object
Published in:
XenServer 4.0 (rio)
A long-running asynchronous task
host refget_resident_on(session ref, task ref)
Get the resident_on field of the given task.
Parameters:
session ref session_id
Reference to a valid session
task ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
the host on which the task is running
stringget_result(session ref, task ref)
Get the result field of the given task.
Parameters:
session ref session_id
Reference to a valid session
task ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise.
if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
Get the allowed_operations field of the given VBD.
Parameters:
session ref session_id
Reference to a valid session
VBD ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
boolget_bootable(session ref, VBD ref)
Get the bootable field of the given VBD.
Parameters:
session ref session_id
Reference to a valid session
VBD ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
true if this VBD is bootable
VBD refget_by_uuid(session ref, string)
Get a reference to the VBD instance with the specified UUID.
Set the other_config field of the given VBD_metrics.
Parameters:
session ref session_id
Reference to a valid session
VBD_metrics ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 5.0 (orlando)
Deprecated in:
XenServer 6.1 (tampa)
Dummy transition
Removed in:
XenServer 6.1 (tampa)
Disabled in favour of RRD
VDI
Class: VDI
A virtual disk image
Published in:
XenServer 4.0 (rio)
A virtual disk image
Enums
vdi_operations
Values:
clone
Cloning the VDI
copy
Copying the VDI
resize
Resizing the VDI
resize_online
Resizing the VDI which may or may not be online
snapshot
Snapshotting the VDI
mirror
Mirroring the VDI
destroy
Destroying the VDI
forget
Forget about the VDI
update
Refreshing the fields of the VDI
force_unlock
Forcibly unlocking the VDI
generate_config
Generating static configuration
enable_cbt
Enabling changed block tracking for a VDI
disable_cbt
Disabling changed block tracking for a VDI
data_destroy
Deleting the data of the VDI
list_changed_blocks
Exporting a bitmap that shows the changed blocks between two VDIs
set_on_boot
Setting the on_boot field of the VDI
blocked
Operations on this VDI are temporarily blocked
vdi_type
Values:
system
a disk that may be replaced on upgrade
user
a disk that is always preserved on upgrade
ephemeral
a disk that may be reformatted on upgrade
suspend
a disk that stores a suspend image
crashdump
a disk that stores VM crashdump information
ha_statefile
a disk used for HA storage heartbeating
metadata
a disk used for HA Pool metadata
redo_log
a disk used for a general metadata redo-log
rrd
a disk that stores SR-level RRDs
pvs_cache
a disk that stores PVS cache data
cbt_metadata
Metadata about a snapshot VDI that has been deleted: the set of blocks that changed between some previous version of the disk and the version tracked by the snapshot.
on_boot
Values:
reset
When a VM containing this VDI is started, the contents of the VDI are reset to the state they were in when this flag was last set.
persist
Standard behaviour.
Fields
boolallow_caching[RO/runtime]
true if this VDI is to be cached in the local cache SR
Default value:
false
Published in:
XenServer 5.6 FP1 (cowley)
true if this VDI is to be cached in the local cache SR
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
Default value:
{}
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
boolis_a_snapshot[RO/runtime]
true if this is a snapshot.
Default value:
false
Published in:
XenServer 5.0 (orlando)
true if this is a snapshot.
boolis_tools_iso[RO/runtime]
Whether this VDI is a Tools ISO
Default value:
false
Published in:
XenServer 7.0 (dundee)
stringlocation[RO/runtime]
location information
Default value:
""
Published in:
XenServer 4.1 (miami)
location information
boolmanaged[RO/runtime]
Published in:
XenServer 4.0 (rio)
boolmetadata_latest[RO/runtime]
Whether this VDI contains the latest known accessible metadata for the pool
Default value:
false
Published in:
XenServer 6.0 (boston)
Whether this VDI contains the latest known accessible metadata for the pool
pool refmetadata_of_pool[RO/runtime]
The pool whose metadata is contained in this VDI
Default value:
OpaqueRef:NULL
Published in:
XenServer 6.0 (boston)
The pool whose metadata is contained in this VDI
boolmissing[RO/runtime]
true if SR scan operation reported this VDI as not present on disk
Published in:
XenServer 4.0 (rio)
true if SR scan operation reported this VDI as not present on disk
stringname_description[RO/constructor]
a notes field containing human-readable description
Default value:
""
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringname_label[RO/constructor]
a human-readable name
Default value:
""
Published in:
XenServer 4.0 (rio)
a human-readable name
enum on_booton_boot[RO/runtime]
The behaviour of this VDI on a VM boot
Default value:
persist
Published in:
XenServer 5.6 FP1 (cowley)
The behaviour of this VDI on a VM boot
(string → string) mapother_config[RW]
additional configuration
Published in:
XenServer 4.0 (rio)
additional configuration
Deprecated
VDI refparent[RO/runtime]
This field is always null. Deprecated
Published in:
XenServer 4.0 (rio)
Deprecated in:
XenServer 7.1 (ely)
The field was never used.
intphysical_utilisation[RO/runtime]
amount of physical space that the disk image is currently taking up on the storage repository (in bytes)
Published in:
XenServer 4.0 (rio)
amount of physical space that the disk image is currently taking up on the storage repository (in bytes)
boolread_only[RO/constructor]
true if this disk may ONLY be mounted read-only
Published in:
XenServer 4.0 (rio)
true if this disk may ONLY be mounted read-only
boolsharable[RO/constructor]
true if this disk may be shared
Published in:
XenServer 4.0 (rio)
true if this disk may be shared
(string → string) mapsm_config[RW]
SM dependent data
Default value:
{}
Published in:
XenServer 4.1 (miami)
SM dependent data
VDI refsnapshot_of[RO/runtime]
Ref pointing to the VDI this snapshot is of.
Default value:
Null
Published in:
XenServer 5.0 (orlando)
Ref pointing to the VDI this snapshot is of.
datetimesnapshot_time[RO/runtime]
Date/time when this snapshot was created.
Default value:
19700101T00:00:00Z
Published in:
XenServer 5.0 (orlando)
Date/time when this snapshot was created.
VDI ref setsnapshots[RO/runtime]
List pointing to all the VDIs snapshots.
Published in:
XenServer 5.0 (orlando)
List pointing to all the VDIs snapshots.
SR refSR[RO/constructor]
storage repository in which the VDI resides
Published in:
XenServer 4.0 (rio)
storage repository in which the VDI resides
boolstorage_lock[RO/runtime]
true if this disk is locked at the storage level
Published in:
XenServer 4.0 (rio)
true if this disk is locked at the storage level
string settags[RW]
user-specified tags for categorization purposes
Default value:
{}
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
enum vdi_typetype[RO/constructor]
type of the VDI
Published in:
XenServer 4.0 (rio)
type of the VDI
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
VBD ref setVBDs[RO/runtime]
list of vbds that refer to this disk
Published in:
XenServer 4.0 (rio)
list of vbds that refer to this disk
intvirtual_size[RO/constructor]
size of disk as presented to the guest (in bytes). Note that, depending on storage backend type, requested size may not be respected exactly
Published in:
XenServer 4.0 (rio)
size of disk as presented to the guest (in bytes). Note that, depending on storage backend type, requested size may not be respected exactly
(string → string) mapxenstore_data[RW]
data to be inserted into the xenstore tree (/local/domain/0/backend/vbd/<domid>/<device-id>/sm-data) after the VDI is attached. This is generally set by the SM backends on vdi_attach.
Default value:
{}
Published in:
XenServer 4.1 (miami)
data to be inserted into the xenstore tree (/local/domain/0/backend/vbd/<domid>/<device-id>/sm-data) after the VDI is attached. This is generally set by the SM backends on vdi_attach.
Messages
voidadd_tags(session ref, VDI ref, string)
Add the given value to the tags field of the given VDI. If the value is already in that Set, then do nothing.
Add the given key-value pair to the xenstore_data field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
vm-admin
Published in:
XenServer 4.1 (miami)
data to be inserted into the xenstore tree (/local/domain/0/backend/vbd/<domid>/<device-id>/sm-data) after the VDI is attached. This is generally set by the SM backends on vdi_attach.
Take an exact copy of the VDI and return a reference to the new disk. If any driver_params are specified then these are passed through to the storage-specific substrate driver that implements the clone operation. NB the clone lives in the same Storage Repository as its parent.
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to clone
(string → string) map driver_params
Optional parameters that are passed through to the backend driver in order to specify storage-type-specific clone options
Minimum role:
vm-admin
Result:
The ID of the newly created VDI.
Published in:
XenServer 4.0 (rio)
Take an exact copy of the VDI and return a reference to the new disk. If any driver_params are specified then these are passed through to the storage-specific substrate driver that implements the clone operation. NB the clone lives in the same Storage Repository as its parent.
Copy either a full VDI or the block differences between two VDIs into either a fresh VDI or an existing VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to copy
SR ref sr
The destination SR (only required if the destination VDI is not specified
VDI ref base_vdi
The base VDI (only required if copying only changed blocks, by default all blocks will be copied)
VDI ref into_vdi
The destination VDI to copy blocks into (if omitted then a destination SR must be provided and a fresh VDI will be created)
Minimum role:
vm-admin
Result:
The reference of the VDI where the blocks were written.
Errors:
VDI_READONLY
The operation required write access but this VDI is read-only
VDI_TOO_SMALL
The VDI is too small. Please resize it to at least the minimum size.
VDI_NOT_SPARSE
The VDI is not stored using a sparse format. It is not possible to query and manipulate only the changed blocks (or 'block differences' or 'disk deltas') between two VDIs. Please select a VDI which uses a sparse-aware technology such as VHD.
Published in:
XenServer 4.0 (rio)
Copies a VDI 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.
Extended in:
XenServer 6.2 SP1 Hotfix 4 (clearwater-felton)
The copy can now be performed into a pre-created VDI. It is now possible to request copying only changed blocks from a base VDI
VDI refcreate(session ref, VDI record)
Create a new VDI instance, and return its handle.
The constructor args are: name_label, name_description, SR*, virtual_size*, type*, sharable*, read_only*, other_config*, xenstore_data, sm_config, tags (* = non-optional).
Parameters:
session ref session_id
Reference to a valid session
VDI record args
All constructor arguments
Minimum role:
vm-admin
Result:
reference to the newly created object
Published in:
XenServer 4.0 (rio)
A virtual disk image
voiddata_destroy(session ref, VDI ref)
Delete the data of the snapshot VDI, but keep its changed block tracking metadata. When successful, this call changes the type of the VDI to cbt_metadata. This operation is idempotent: calling it on a VDI of type cbt_metadata results in a no-op, and no error will be thrown.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI whose data should be deleted.
Minimum role:
vm-admin
Errors:
SR_OPERATION_NOT_SUPPORTED
The SR backend does not support the operation (check the SR's allowed operations)
VDI_MISSING
This operation cannot be performed because the specified VDI could not be found on the storage substrate
SR_NOT_ATTACHED
The SR is not attached.
SR_HAS_NO_PBDS
The SR has no attached PBDs
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VDI_INCOMPATIBLE_TYPE
This operation cannot be performed because the specified VDI is of an incompatible type (eg: an HA statefile cannot be attached to a guest)
VDI_NO_CBT_METADATA
The requested operation is not allowed because the specified VDI does not have changed block tracking metadata.
VDI_IN_USE
This operation cannot be performed because this VDI is in use by some other operation
VDI_IS_A_PHYSICAL_DEVICE
The operation cannot be performed on physical device
Published in:
XenServer 7.3 (inverness)
Delete the data of the snapshot VDI, but keep its changed block tracking metadata. When successful, this call changes the type of the VDI to cbt_metadata. This operation is idempotent: calling it on a VDI of type cbt_metadata results in a no-op, and no error will be thrown.
voiddestroy(session ref, VDI ref)
Destroy the specified VDI instance.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
A virtual disk image
voiddisable_cbt(session ref, VDI ref)
Disable changed block tracking for the VDI. This call is only allowed on VDIs that support enabling CBT. It is an idempotent operation - disabling CBT for a VDI for which CBT is not enabled results in a no-op, and no error will be thrown.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI for which CBT should be disabled
Minimum role:
vm-admin
Errors:
SR_OPERATION_NOT_SUPPORTED
The SR backend does not support the operation (check the SR's allowed operations)
VDI_MISSING
This operation cannot be performed because the specified VDI could not be found on the storage substrate
SR_NOT_ATTACHED
The SR is not attached.
SR_HAS_NO_PBDS
The SR has no attached PBDs
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VDI_INCOMPATIBLE_TYPE
This operation cannot be performed because the specified VDI is of an incompatible type (eg: an HA statefile cannot be attached to a guest)
VDI_ON_BOOT_MODE_INCOMPATIBLE_WITH_OPERATION
This operation is not permitted on VDIs in the 'on-boot=reset' mode, or on VMs having such VDIs.
Published in:
XenServer 7.3 (inverness)
Disable changed block tracking for the VDI. This call is only allowed on VDIs that support enabling CBT. It is an idempotent operation - disabling CBT for a VDI for which CBT is not enabled results in a no-op, and no error will be thrown.
voidenable_cbt(session ref, VDI ref)
Enable changed block tracking for the VDI. This call is idempotent - enabling CBT for a VDI for which CBT is already enabled results in a no-op, and no error will be thrown.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI for which CBT should be enabled
Minimum role:
vm-admin
Errors:
SR_OPERATION_NOT_SUPPORTED
The SR backend does not support the operation (check the SR's allowed operations)
VDI_MISSING
This operation cannot be performed because the specified VDI could not be found on the storage substrate
SR_NOT_ATTACHED
The SR is not attached.
SR_HAS_NO_PBDS
The SR has no attached PBDs
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VDI_INCOMPATIBLE_TYPE
This operation cannot be performed because the specified VDI is of an incompatible type (eg: an HA statefile cannot be attached to a guest)
VDI_ON_BOOT_MODE_INCOMPATIBLE_WITH_OPERATION
This operation is not permitted on VDIs in the 'on-boot=reset' mode, or on VMs having such VDIs.
Published in:
XenServer 7.3 (inverness)
Enable changed block tracking for the VDI. This call is idempotent - enabling CBT for a VDI for which CBT is already enabled results in a no-op, and no error will be thrown.
voidforget(session ref, VDI ref)
Removes a VDI record from the database
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to forget about
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Removes a VDI record from the database
VDI ref setget_all(session ref)
Return a list of all the VDIs known to the system.
Get the allowed_operations field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
VDI ref setget_by_name_label(session ref, string)
Get all the VDI instances with the given label.
Parameters:
session ref session_id
Reference to a valid session
string label
label of object to return
Minimum role:
read-only
Result:
references to objects with matching names
Published in:
XenServer 4.0 (rio)
A virtual disk image
VDI refget_by_uuid(session ref, string)
Get a reference to the VDI instance with the specified UUID.
Get the current_operations field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
boolget_is_a_snapshot(session ref, VDI ref)
Get the is_a_snapshot field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
true if this is a snapshot.
boolget_is_tools_iso(session ref, VDI ref)
Get the is_tools_iso field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
stringget_location(session ref, VDI ref)
Get the location field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
location information
boolget_managed(session ref, VDI ref)
Get the managed field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
boolget_metadata_latest(session ref, VDI ref)
Get the metadata_latest field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
Whether this VDI contains the latest known accessible metadata for the pool
pool refget_metadata_of_pool(session ref, VDI ref)
Get the metadata_of_pool field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The pool whose metadata is contained in this VDI
boolget_missing(session ref, VDI ref)
Get the missing field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
true if SR scan operation reported this VDI as not present on disk
stringget_name_description(session ref, VDI ref)
Get the name/description field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringget_name_label(session ref, VDI ref)
Get the name/label field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
a human-readable name
vdi_nbd_server_info record setget_nbd_info(session ref, VDI ref)
Get details specifying how to access this VDI via a Network Block Device server. For each of a set of NBD server addresses on which the VDI is available, the return value set contains a vdi_nbd_server_info object that contains an exportname to request once the NBD connection is established, and connection details for the address. An empty list is returned if there is no network that has a PIF on a host with access to the relevant SR, or if no such network has been assigned an NBD-related purpose in its purpose field. To access the given VDI, any of the vdi_nbd_server_info objects can be used to make a connection to a server, and then the VDI will be available by requesting the exportname.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI to access via Network Block Device protocol
Minimum role:
vm-admin
Result:
The details necessary for connecting to the VDI over NBD. This includes an authentication token, so must be treated as sensitive material and must not be sent over insecure networks.
Errors:
VDI_INCOMPATIBLE_TYPE
This operation cannot be performed because the specified VDI is of an incompatible type (eg: an HA statefile cannot be attached to a guest)
Published in:
XenServer 7.3 (inverness)
Get details specifying how to access this VDI via a Network Block Device server. For each of a set of NBD server addresses on which the VDI is available, the return value set contains a vdi_nbd_server_info object that contains an exportname to request once the NBD connection is established, and connection details for the address. An empty list is returned if there is no network that has a PIF on a host with access to the relevant SR, or if no such network has been assigned an NBD-related purpose in its purpose field. To access the given VDI, any of the vdi_nbd_server_info objects can be used to make a connection to a server, and then the VDI will be available by requesting the exportname.
data to be inserted into the xenstore tree (/local/domain/0/backend/vbd/<domid>/<device-id>/sm-data) after the VDI is attached. This is generally set by the SM backends on vdi_attach.
Remove the given key and its corresponding value from the xenstore_data field of the given VDI. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
string key
Key to remove
Minimum role:
vm-admin
Published in:
XenServer 4.1 (miami)
data to be inserted into the xenstore tree (/local/domain/0/backend/vbd/<domid>/<device-id>/sm-data) after the VDI is attached. This is generally set by the SM backends on vdi_attach.
voidremove_tags(session ref, VDI ref, string)
Remove the given value from the tags field of the given VDI. If the value is not in that Set, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
string value
Value to remove
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
voidresize(session ref, VDI ref, int)
Resize the VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to resize
int size
The new size of the VDI
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Resize the VDI.
Removed
voidresize_online(session ref, VDI ref, int)
Resize the VDI which may or may not be attached to running guests.
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to resize
int size
The new size of the VDI
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Deprecated in:
XenServer 7.3 (inverness)
Dummy transition
Removed in:
XenServer 7.3 (inverness)
Online VDI resize is not supported by any of the storage backends.
voidset_allow_caching(session ref, VDI ref, bool)
Set the value of the allow_caching parameter. This value can only be changed when the VDI is not attached to a running VM. The caching behaviour is only affected by this flag for VHD-based VDIs that have one parent and no child VHDs. Moreover, caching only takes place when the host running the VM containing this VDI has a nominated SR for local caching.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI to modify
bool value
The value to set
Minimum role:
vm-admin
Published in:
XenServer 5.6 FP1 (cowley)
Set the value of the allow_caching parameter. This value can only be changed when the VDI is not attached to a running VM. The caching behaviour is only affected by this flag for VHD-based VDIs that have one parent and no child VHDs. Moreover, caching only takes place when the host running the VM containing this VDI has a nominated SR for local caching.
data to be inserted into the xenstore tree (/local/domain/0/backend/vbd/<domid>/<device-id>/sm-data) after the VDI is attached. This is generally set by the SM backends on vdi_attach.
Take a read-only snapshot of the VDI, returning a reference to the snapshot. If any driver_params are specified then these are passed through to the storage-specific substrate driver that takes the snapshot. NB the snapshot lives in the same Storage Repository as its parent.
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to snapshot
(string → string) map driver_params
Optional parameters that can be passed through to backend driver in order to specify storage-type-specific snapshot options
Minimum role:
vm-admin
Result:
The ID of the newly created VDI.
Published in:
XenServer 4.0 (rio)
Take a read-only snapshot of the VDI, returning a reference to the snapshot. If any driver_params are specified then these are passed through to the storage-specific substrate driver that takes the snapshot. NB the snapshot lives in the same Storage Repository as its parent.
voidupdate(session ref, VDI ref)
Ask the storage backend to refresh the fields in the VDI object
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI whose stats (eg size) should be updated
Minimum role:
vm-admin
Errors:
SR_OPERATION_NOT_SUPPORTED
The SR backend does not support the operation (check the SR's allowed operations)
Published in:
XenServer 4.1.1 (symc)
Ask the storage backend to refresh the fields in the VDI object
vdi_nbd_server_info
Class: vdi_nbd_server_info
Details for connecting to a VDI using the Network Block Device protocol
Published in:
XenServer 7.3 (inverness)
Fields
stringaddress[RO/runtime]
An address on which the server can be reached; this can be IPv4, IPv6, or a DNS name.
Published in:
XenServer 7.3 (inverness)
stringcert[RO/runtime]
The TLS certificate of the server
Published in:
XenServer 7.3 (inverness)
stringexportname[RO/runtime]
The exportname to request over NBD. This holds details including an authentication token, so it must be protected appropriately. Clients should regard the exportname as an opaque string or token.
Published in:
XenServer 7.3 (inverness)
intport[RO/runtime]
The TCP port
Published in:
XenServer 7.3 (inverness)
stringsubject[RO/runtime]
For convenience, this redundant field holds a DNS (hostname) subject of the certificate. This can be a wildcard, but only for a certificate that has a wildcard subject and no concrete hostname subjects.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
Get the allowed_operations field of the given VIF.
Parameters:
session ref session_id
Reference to a valid session
VIF ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
VIF refget_by_uuid(session ref, string)
Get a reference to the VIF instance with the specified UUID.
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. Resource constraints may cause the VM to be started elsewhere.
Published in:
XenServer 4.0 (rio)
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. Resource constraints may cause the VM to be started elsewhere.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
if true then the system will attempt to keep the VM running as much as possible.
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)
stringha_restart_priority[RO/constructor]
has 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"; "restart" meaning "this VM should be restarted"; "" meaning "do not try to restart this VM"
Default value:
""
Published in:
XenServer 5.0 (orlando)
has 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"; "restart" meaning "this VM should be restarted"; "" meaning "do not try to restart this VM"
inthardware_platform_version[RW]
The host virtual hardware platform version the VM can run on
Default value:
0
Published in:
XenServer 6.5 SP1 (cream)
The host virtual hardware platform version the VM can run on
boolhas_vendor_device[RO/constructor]
When an HVM guest starts, this controls the presence of the emulated C000 PCI device which triggers Windows Update to fetch or update PV drivers.
Default value:
false
Published in:
XenServer 7.0 (dundee)
(string → string) mapHVM_boot_params[RW]
HVM boot params
Published in:
XenServer 4.0 (rio)
HVM boot params
Deprecated
stringHVM_boot_policy[RO/constructor]
HVM boot policy
Published in:
XenServer 4.0 (rio)
Deprecated in:
XenServer 7.5 (kolkata)
Replaced by VM.domain_type
floatHVM_shadow_multiplier[RO/constructor]
multiplier applied to the amount of shadow that will be made available to the guest
Default value:
1.
Published in:
XenServer 4.1 (miami)
multiplier applied to the amount of shadow that will be made available to the guest
boolis_a_snapshot[RO/runtime]
true if this is a snapshot. Snapshotted VMs can never be started, they are used only for cloning other VMs
Default value:
false
Published in:
XenServer 5.0 (orlando)
true if this is a snapshot. Snapshotted VMs can never be started, they are used only for cloning other VMs
boolis_a_template[RW]
true if this is a template. Template VMs can never be started, they are used only for cloning other VMs
Published in:
XenServer 4.0 (rio)
true if this is a template. Template VMs can never be started, they are used only for cloning other VMs
boolis_control_domain[RO/runtime]
true if this is a control domain (domain 0 or a driver domain)
Published in:
XenServer 4.0 (rio)
true if this is a control domain (domain 0 or a driver domain)
boolis_default_template[RO/runtime]
true if this is a default template. Default template VMs can never be started or migrated, they are used only for cloning other VMs
Default value:
false
Published in:
XenServer 7.2 (falcon)
Identifies default templates
Removed
boolis_snapshot_from_vmpp[RO/constructor]
true if this snapshot was created by the protection policy
Default value:
false
Published in:
XenServer 5.6 FP1 (cowley)
Deprecated in:
XenServer 6.2 (clearwater)
Dummy transition
Removed in:
XenServer 6.2 (clearwater)
The VMPR feature was removed
boolis_vmss_snapshot[RO/constructor]
true if this snapshot was created by the snapshot schedule
Default value:
false
Published in:
XenServer 7.2 (falcon)
true if this snapshot was created by the snapshot schedule
describes the CPU flags on which the VM was last booted
Default value:
{}
Published in:
XenServer 4.0 (rio)
describes the CPU flags on which the VM was last booted
stringlast_booted_record[RO/constructor]
marshalled value containing VM record at time of last boot
Default value:
""
Published in:
XenServer 4.1 (miami)
Marshalled value containing VM record at time of last boot, updated dynamically to reflect the runtime state of the domain
Changed in:
XAPI 1.257.0 (1.257.0)
Become static to allow Suspended VM creation
intmemory_dynamic_max[RO/constructor]
Dynamic maximum (bytes)
Published in:
XenServer 4.0 (rio)
Dynamic maximum (bytes)
intmemory_dynamic_min[RO/constructor]
Dynamic minimum (bytes)
Published in:
XenServer 4.0 (rio)
Dynamic minimum (bytes)
intmemory_overhead[RO/runtime]
Virtualization memory overhead (bytes).
Default value:
0
Published in:
XenServer 4.0 (rio)
Virtualization memory overhead (bytes).
intmemory_static_max[RO/constructor]
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.
Published in:
XenServer 4.0 (rio)
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.
intmemory_static_min[RO/constructor]
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.
Published in:
XenServer 4.0 (rio)
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.
Deprecated
intmemory_target[RO/constructor]
Dynamically-set memory target (bytes). The value of this field indicates the current target for memory available to this VM.
Default value:
0
Published in:
XenServer 4.0 (rio)
Dynamically-set memory target (bytes). The value of this field indicates the current target for memory available to this VM.
Deprecated in:
XenServer 5.6 (midnight-ride)
VM_metrics refmetrics[RO/runtime]
metrics associated with this VM
Published in:
XenServer 4.0 (rio)
metrics associated with this VM
stringname_description[RW]
a notes field containing human-readable description
Default value:
""
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringname_label[RW]
a human-readable name
Default value:
""
Published in:
XenServer 4.0 (rio)
a human-readable name
(string → string) mapNVRAM[RO/constructor]
initial value for guest NVRAM (containing UEFI variables, etc). Cannot be changed while the VM is running
Default value:
{}
Published in:
Citrix Hypervisor 8.0 (naples)
intorder[RO/constructor]
The point in the startup or shutdown sequence at which this VM will be started
Default value:
0
Published in:
XenServer 6.0 (boston)
The point in the startup or shutdown sequence at which this VM will be started
The set of pending full guidances after applying updates, which a user should follow to make some updates, e.g. specific hardware drivers or CPU features, fully effective, but the 'average user' doesn't need to
The set of pending recommended guidances after applying updates, which most users should follow to make the updates effective, but if not followed, will not cause a failure
Default value:
{}
Prototyped in:
XAPI 24.10.0 (24.10.0)
(string → string) mapplatform[RW]
platform-specific configuration
Published in:
XenServer 4.0 (rio)
platform-specific configuration
enum vm_power_statepower_state[RO/constructor]
Current power state of the machine
Default value:
Halted
Published in:
XenServer 4.0 (rio)
Changed in:
XAPI 1.257.0 (1.257.0)
Made StaticRO to allow Suspended VM creation
Deprecated
VMPP refprotection_policy[RO/constructor]
Ref pointing to a protection policy for this VM
Default value:
OpaqueRef:NULL
Published in:
XenServer 5.6 FP1 (cowley)
Deprecated in:
XenServer 6.2 (clearwater)
The VMPR feature was removed
stringPV_args[RW]
kernel command-line arguments
Published in:
XenServer 4.0 (rio)
kernel command-line arguments
stringPV_bootloader[RW]
name of or path to bootloader
Published in:
XenServer 4.0 (rio)
name of or path to bootloader
stringPV_bootloader_args[RW]
miscellaneous arguments for the bootloader
Published in:
XenServer 4.0 (rio)
miscellaneous arguments for the bootloader
stringPV_kernel[RW]
path to the kernel
Published in:
XenServer 4.0 (rio)
path to the kernel
stringPV_legacy_args[RW]
to make Zurich guests boot
Published in:
XenServer 4.0 (rio)
to make Zurich guests boot
stringPV_ramdisk[RW]
path to the initrd
Published in:
XenServer 4.0 (rio)
path to the initrd
stringrecommendations[RW]
An XML specification of recommended values and ranges for properties of this VM
Published in:
XenServer 4.0 (rio)
An XML specification of recommended values and ranges for properties of this VM
stringreference_label[RO/constructor]
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:
""
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.
boolrequires_reboot[RO/runtime]
Indicates whether a VM requires a reboot in order to update its configuration, e.g. its memory allocation.
Default value:
false
Published in:
XenServer 7.1 (ely)
host refresident_on[RO/runtime]
the host the VM is currently resident on
Published in:
XenServer 4.0 (rio)
the host the VM is currently resident on
host refscheduled_to_be_resident_on[RO/runtime]
the host on which the VM is due to be started/resumed/migrated. This acts as a memory reservation indicator
Default value:
OpaqueRef:NULL
Published in:
XenServer 4.0 (rio)
the host on which the VM is due to be started/resumed/migrated. This acts as a memory reservation indicator
intshutdown_delay[RO/constructor]
The delay to wait before proceeding to the next order in the shutdown sequence (seconds)
Default value:
0
Published in:
XenServer 6.0 (boston)
The delay to wait before proceeding to the next order in the shutdown sequence (seconds)
(string → string) mapsnapshot_info[RO/runtime]
Human-readable information concerning this snapshot
Default value:
{}
Published in:
XenServer 5.6 (midnight-ride)
Human-readable information concerning this snapshot
stringsnapshot_metadata[RO/runtime]
Encoded information about the VM's metadata this is a snapshot of
Default value:
""
Published in:
XenServer 5.6 (midnight-ride)
Encoded information about the VM's metadata this is a snapshot of
VM refsnapshot_of[RO/runtime]
Ref pointing to the VM this snapshot is of.
Default value:
Null
Published in:
XenServer 5.0 (orlando)
Ref pointing to the VM this snapshot is of.
VMSS refsnapshot_schedule[RO/constructor]
Ref pointing to a snapshot schedule for this VM
Default value:
OpaqueRef:NULL
Published in:
XenServer 7.2 (falcon)
Ref pointing to a snapshot schedule for this VM
datetimesnapshot_time[RO/runtime]
Date/time when this snapshot was created.
Default value:
19700101T00:00:00Z
Published in:
XenServer 5.0 (orlando)
Date/time when this snapshot was created.
VM ref setsnapshots[RO/runtime]
List pointing to all the VM snapshots.
Published in:
XenServer 5.0 (orlando)
List pointing to all the VM snapshots.
intstart_delay[RO/constructor]
The delay to wait before proceeding to the next order in the startup sequence (seconds)
Default value:
0
Published in:
XenServer 6.0 (boston)
The delay to wait before proceeding to the next order in the startup sequence (seconds)
SR refsuspend_SR[RW]
The SR on which a suspend image is stored
Default value:
OpaqueRef:NULL
Published in:
XenServer 6.0 (boston)
The SR on which a suspend image is stored
VDI refsuspend_VDI[RO/constructor]
The VDI that a suspend image is stored on. (Only has meaning if VM is currently suspended)
Default value:
OpaqueRef:NULL
Published in:
XenServer 4.0 (rio)
Changed in:
XAPI 1.257.0 (1.257.0)
Become static to allow Suspended VM creation
string settags[RW]
user-specified tags for categorization purposes
Default value:
{}
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
stringtransportable_snapshot_id[RO/runtime]
Transportable ID of the snapshot VM
Default value:
""
Published in:
XenServer 5.0 (orlando)
Transportable ID of the snapshot VM
intuser_version[RW]
Creators of VMs and templates may store version information here.
Published in:
XenServer 4.0 (rio)
Creators of VMs and templates may store version information here.
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
VBD ref setVBDs[RO/runtime]
virtual block devices
Published in:
XenServer 4.0 (rio)
virtual block devices
intVCPUs_at_startup[RO/constructor]
Boot number of VCPUs
Published in:
XenServer 4.0 (rio)
Boot number of VCPUs
intVCPUs_max[RO/constructor]
Max number of VCPUs
Published in:
XenServer 4.0 (rio)
Max number of VCPUs
(string → string) mapVCPUs_params[RW]
configuration parameters for the selected VCPU policy
Published in:
XenServer 4.0 (rio)
configuration parameters for the selected VCPU policy
intversion[RO/constructor]
The number of times this VM has been recovered
Default value:
0
Published in:
XenServer 6.0 (boston)
The number of times this VM has been recovered
VGPU ref setVGPUs[RO/runtime]
Virtual GPUs
Published in:
XenServer 6.0 (boston)
VIF ref setVIFs[RO/runtime]
virtual network interfaces
Published in:
XenServer 4.0 (rio)
virtual network interfaces
VTPM ref setVTPMs[RO/runtime]
virtual TPMs
Published in:
XenServer 4.0 (rio)
virtual TPMs
VUSB ref setVUSBs[RO/runtime]
vitual usb devices
Published in:
XenServer 4.0 (rio)
vitual usb devices
(string → string) mapxenstore_data[RW]
data to be inserted into the xenstore tree (/local/domain/<domid>/vm-data) after the VM is created.
Default value:
{}
Published in:
XenServer 4.1 (miami)
data to be inserted into the xenstore tree (/local/domain/<domid>/vm-data) after the VM is created.
Messages
voidadd_tags(session ref, VM ref, string)
Add the given value to the tags field of the given VM. If the value is already in that Set, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to add
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
voidadd_to_blocked_operations(session ref, VM ref, enum vm_operations, string)
Add the given key-value pair to the blocked_operations field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
enum vm_operations key
Key to add
string value
Value to add
Minimum role:
vm-admin
Published in:
XenServer 5.0 (orlando)
List of operations which have been explicitly blocked and an error code
voidadd_to_HVM_boot_params(session ref, VM ref, string, string)
Add the given key-value pair to the HVM/boot_params field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
HVM boot params
voidadd_to_NVRAM(session ref, VM ref, string, string)
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
string key
The key
string value
The value
Minimum role:
vm-admin
Published in:
Citrix Hypervisor 8.0 (naples)
voidadd_to_other_config(session ref, VM ref, string, string)
Add the given key-value pair to the other_config field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
additional configuration
voidadd_to_platform(session ref, VM ref, string, string)
Add the given key-value pair to the platform field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
platform-specific configuration
voidadd_to_VCPUs_params(session ref, VM ref, string, string)
Add the given key-value pair to the VCPUs/params field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
configuration parameters for the selected VCPU policy
voidadd_to_VCPUs_params_live(session ref, VM ref, string, string)
Add the given key-value pair to VM.VCPUs_params, and apply that value on the running VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
string key
The key
string value
The value
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Add the given key-value pair to VM.VCPUs_params, and apply that value on the running VM
voidadd_to_xenstore_data(session ref, VM ref, string, string)
Add the given key-value pair to the xenstore_data field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role:
vm-admin
Published in:
XenServer 4.1 (miami)
data to be inserted into the xenstore tree (/local/domain/<domid>/vm-data) after the VM is created.
voidassert_agile(session ref, VM ref)
Returns an error if the VM is not considered agile e.g. because it is tied to a resource local to a host
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
Minimum role:
read-only
Published in:
XenServer 5.0 (orlando)
Returns an error if the VM is not considered agile e.g. because it is tied to a resource local to a host
voidassert_can_be_recovered(session ref, VM ref, session ref)
Assert whether all SRs required to recover this VM are available.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to recover
session ref session_to
The session to which the VM is to be recovered.
Minimum role:
read-only
Errors:
VM_IS_PART_OF_AN_APPLIANCE
This operation is not allowed as the VM is part of an appliance.
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.
Published in:
XenServer 6.0 (boston)
Assert whether all SRs required to recover this VM are available.
voidassert_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.
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.
Assert whether a VM can be migrated to the specified destination.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM
(string → string) map dest
The result of a VM.migrate_receive call.
bool live
Live migration
(VDI ref → SR ref) map vdi_map
Map of source VDI to destination SR
(VIF ref → network ref) map vif_map
Map of source VIF to destination network
(string → string) map options
Other parameters
(VGPU ref → GPU_group ref) map vgpu_map
Map of source vGPU to destination GPU group
Minimum role:
vm-power-admin
Errors:
LICENCE_RESTRICTION
This operation is not allowed because your license lacks a needed feature. Please contact your support representative.
Published in:
XenServer 6.1 (tampa)
Assert whether a VM can be migrated to the specified destination.
voidassert_operation_valid(session ref, VM ref, enum vm_operations)
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
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
enum vm_operations op
proposed operation
Minimum role:
read-only
Published in:
XenServer 4.0 (rio)
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
stringcall_plugin(session ref, VM ref, string, string, (string → string) map)
Call an API plugin on this vm
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The vm
string plugin
The name of the plugin
string fn
The name of the function within the plugin
(string → string) map args
Arguments for the function
Minimum role:
vm-operator
Result:
Result from the plugin
Published in:
XenServer 6.5 SP1 (cream)
Call an API plugin on this vm
VM refcheckpoint(session ref, VM ref, string)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to be checkpointed
string new_name
The name of the checkpointed 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_CHECKPOINT_SUSPEND_FAILED
An error occured while saving the memory image of the specified virtual machine
VM_CHECKPOINT_RESUME_FAILED
An error occured while restoring the memory image of the specified virtual machine
Published in:
XenServer 5.6 (midnight-ride)
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.
voidclean_reboot(session ref, VM ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to shutdown
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
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.
voidclean_shutdown(session ref, VM ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to shutdown
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
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.
VM refclone(session ref, VM ref, string)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to be cloned
string new_name
The name of the cloned VM
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)
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.
intcompute_memory_overhead(session ref, VM ref)
Computes the virtualization memory overhead of a VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM for which to compute the memory overhead
Minimum role:
read-only
Result:
the virtualization memory overhead of the VM.
Published in:
XenServer 5.6 (midnight-ride)
Computes the virtualization memory overhead of a VM.
VM refcopy(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.
voidcopy_bios_strings(session ref, VM ref, host ref)
Copy the BIOS strings from the given host to this VM
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to modify
host ref host
The host to copy the BIOS strings from
Minimum role:
vm-admin
Published in:
XenServer 5.6 (midnight-ride)
Copy the BIOS strings from the given host to this VM
VM refcreate(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 refcreate_new_blob(session ref, VM ref, string, string, bool)
Create a placeholder for a named binary blob of data that is associated with this VM
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM
string name
The name associated with the blob
string mime_type
The mime type for the data. Empty string translates to application/octet-stream
bool public
True if the blob should be publicly available
Minimum role:
vm-power-admin
Result:
The reference of the blob, needed for populating its data
Published in:
XenServer 5.0 (orlando)
Create a placeholder for a named binary blob of data that is associated with this VM
voiddestroy(session ref, VM ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
vm-admin
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
voidforget_data_source_archives(session ref, VM ref, string)
Forget the recorded statistics related to the specified data source
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
string data_source
The data source whose archives are to be forgotten
Minimum role:
vm-admin
Published in:
XenServer 5.0 (orlando)
Forget the recorded statistics related to the specified data source
enum on_crash_behaviourget_actions_after_crash(session ref, VM ref)
Get the actions/after_crash field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
action to take if the guest crashes
enum on_normal_exitget_actions_after_reboot(session ref, VM ref)
Get the actions/after_reboot field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
action to take after the guest has rebooted itself
enum on_normal_exitget_actions_after_shutdown(session ref, VM ref)
Get the actions/after_shutdown field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
action to take after the guest has shutdown itself
Prototype
enum on_softreboot_behaviorget_actions_after_softreboot(session ref, VM ref)
Get the actions/after_softreboot field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 23.1.0 (23.1.0)
host refget_affinity(session ref, VM ref)
Get the affinity field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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. Resource constraints may cause the VM to be started elsewhere.
VM ref setget_all(session ref)
Return a list of all the VMs known to the system.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
references to all objects
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
(VM ref → VM record) mapget_all_records(session ref)
Return a map of VM references to VM records for all VMs known to the system.
Parameters:
session ref session_id
Reference to a valid session
Minimum role:
read-only
Result:
records of all objects
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
enum vm_operations setget_allowed_operations(session ref, VM ref)
Get the allowed_operations field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
string setget_allowed_VBD_devices(session ref, VM ref)
Returns a list of the allowed values that a VBD device field can take
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to query
Minimum role:
read-only
Result:
The allowed values
Published in:
XenServer 4.0 (rio)
Returns a list of the allowed values that a VBD device field can take
string setget_allowed_VIF_devices(session ref, VM ref)
Returns a list of the allowed values that a VIF device field can take
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to query
Minimum role:
read-only
Result:
The allowed values
Published in:
XenServer 4.0 (rio)
Returns a list of the allowed values that a VIF device field can take
VM_appliance refget_appliance(session ref, VM ref)
Get the appliance field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
the appliance to which this VM belongs
PCI ref setget_attached_PCIs(session ref, VM ref)
Get the attached_PCIs field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
(string → string) mapget_bios_strings(session ref, VM ref)
Get the bios_strings field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
BIOS strings
(string → blob ref) mapget_blobs(session ref, VM ref)
Get the blobs field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Binary blobs associated with this VM
(enum vm_operations → string) mapget_blocked_operations(session ref, VM ref)
Get the blocked_operations field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
List of operations which have been explicitly blocked and an error code
Deprecated
VM recordget_boot_record(session ref, VM ref)
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
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM whose boot-time state to return
Minimum role:
read-only
Result:
A record describing the VM
Published in:
XenServer 4.0 (rio)
Deprecated in:
XenServer 7.3 (inverness)
Use the current VM record/fields instead
VM ref setget_by_name_label(session ref, string)
Get all the VM instances with the given label.
Parameters:
session ref session_id
Reference to a valid session
string label
label of object to return
Minimum role:
read-only
Result:
references to objects with matching names
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
VM refget_by_uuid(session ref, string)
Get a reference to the VM instance with the specified UUID.
Parameters:
session ref session_id
Reference to a valid session
string uuid
UUID of object to return
Minimum role:
read-only
Result:
reference to the 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
VM ref setget_children(session ref, VM ref)
Get the children field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
List pointing to all the children of this VM
console ref setget_consoles(session ref, VM ref)
Get the consoles field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
virtual console devices
Deprecated
boolget_cooperative(session ref, VM ref)
Return true if the VM is currently 'co-operative' i.e. is expected to reach a balloon target and actually has done
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
Minimum role:
read-only
Result:
true if the VM is currently 'co-operative'; false otherwise
Published in:
XenServer 5.6 (midnight-ride)
Return true if the VM is currently 'co-operative' i.e. is expected to reach a balloon target and actually has done
Deprecated in:
XenServer 6.1 (tampa)
crashdump ref setget_crash_dumps(session ref, VM ref)
Get the crash_dumps field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
crash dumps associated with this VM
(string → enum vm_operations) mapget_current_operations(session ref, VM ref)
Get the current_operations field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
data_source record setget_data_sources(session ref, VM ref)
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to interrogate
Minimum role:
read-only
Result:
A set of data sources
Published in:
XenServer 5.0 (orlando)
enum domain_typeget_domain_type(session ref, VM ref)
VM_guest_metrics refget_guest_metrics(session ref, VM ref)
Get the guest_metrics field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
metrics associated with the running guest
Deprecated
boolget_ha_always_run(session ref, VM ref)
Get the ha_always_run field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
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)
stringget_ha_restart_priority(session ref, VM ref)
Get the ha_restart_priority field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
has 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"; "restart" meaning "this VM should be restarted"; "" meaning "do not try to restart this VM"
intget_hardware_platform_version(session ref, VM ref)
Get the hardware_platform_version field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.5 SP1 (cream)
The host virtual hardware platform version the VM can run on
boolget_has_vendor_device(session ref, VM ref)
Get the has_vendor_device field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
(string → string) mapget_HVM_boot_params(session ref, VM ref)
Get the HVM/boot_params field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
HVM boot params
Deprecated
stringget_HVM_boot_policy(session ref, VM ref)
Get the HVM/boot_policy field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Deprecated in:
XenServer 7.5 (kolkata)
Replaced by VM.domain_type
floatget_HVM_shadow_multiplier(session ref, VM ref)
Get the HVM/shadow_multiplier field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
multiplier applied to the amount of shadow that will be made available to the guest
boolget_is_a_snapshot(session ref, VM ref)
Get the is_a_snapshot field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
true if this is a snapshot. Snapshotted VMs can never be started, they are used only for cloning other VMs
boolget_is_a_template(session ref, VM ref)
Get the is_a_template field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
true if this is a template. Template VMs can never be started, they are used only for cloning other VMs
boolget_is_control_domain(session ref, VM ref)
Get the is_control_domain field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
true if this is a control domain (domain 0 or a driver domain)
boolget_is_default_template(session ref, VM ref)
Get the is_default_template field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.2 (falcon)
Identifies default templates
Removed
boolget_is_snapshot_from_vmpp(session ref, VM ref)
Get the is_snapshot_from_vmpp field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 FP1 (cowley)
Deprecated in:
XenServer 6.2 (clearwater)
Dummy transition
Removed in:
XenServer 6.2 (clearwater)
The VMPR feature was removed
boolget_is_vmss_snapshot(session ref, VM ref)
Get the is_vmss_snapshot field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.2 (falcon)
true if this snapshot was created by the snapshot schedule
(string → string) mapget_last_boot_CPU_flags(session ref, VM ref)
Get the last_boot_CPU_flags field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
describes the CPU flags on which the VM was last booted
stringget_last_booted_record(session ref, VM ref)
Get the last_booted_record field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
Marshalled value containing VM record at time of last boot, updated dynamically to reflect the runtime state of the domain
Changed in:
XAPI 1.257.0 (1.257.0)
Become static to allow Suspended VM creation
intget_memory_dynamic_max(session ref, VM ref)
Get the memory/dynamic_max field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Dynamic maximum (bytes)
intget_memory_dynamic_min(session ref, VM ref)
Get the memory/dynamic_min field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Dynamic minimum (bytes)
intget_memory_overhead(session ref, VM ref)
Get the memory/overhead field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Virtualization memory overhead (bytes).
intget_memory_static_max(session ref, VM ref)
Get the memory/static_max field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
intget_memory_static_min(session ref, VM ref)
Get the memory/static_min field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
Deprecated
intget_memory_target(session ref, VM ref)
Get the memory/target field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Dynamically-set memory target (bytes). The value of this field indicates the current target for memory available to this VM.
Deprecated in:
XenServer 5.6 (midnight-ride)
VM_metrics refget_metrics(session ref, VM ref)
Get the metrics field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
metrics associated with this VM
stringget_name_description(session ref, VM ref)
Get the name/description field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringget_name_label(session ref, VM ref)
Get the name/label field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
a human-readable name
(string → string) mapget_NVRAM(session ref, VM ref)
Get the NVRAM field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
Citrix Hypervisor 8.0 (naples)
intget_order(session ref, VM ref)
Get the order field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The point in the startup or shutdown sequence at which this VM will be started
(string → string) mapget_other_config(session ref, VM ref)
Get the other_config field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
additional configuration
VM refget_parent(session ref, VM ref)
Get the parent field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
Ref pointing to the parent of this VM
Deprecated
stringget_PCI_bus(session ref, VM ref)
Get the PCI_bus field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
PCI bus path for pass-through devices
Deprecated in:
XenServer 6.0 (boston)
Field was never used
enum update_guidances setget_pending_guidances(session ref, VM ref)
Get the pending_guidances field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
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
Prototype
enum update_guidances setget_pending_guidances_full(session ref, VM ref)
Get the pending_guidances_full field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 24.10.0 (24.10.0)
Prototype
enum update_guidances setget_pending_guidances_recommended(session ref, VM ref)
Get the pending_guidances_recommended field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Prototyped in:
XAPI 24.10.0 (24.10.0)
(string → string) mapget_platform(session ref, VM ref)
Get the platform field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
platform-specific configuration
host ref setget_possible_hosts(session ref, VM ref)
Return the list of hosts on which this VM may run.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM
Minimum role:
read-only
Result:
The possible hosts
Published in:
XenServer 4.0 (rio)
Return the list of hosts on which this VM may run.
enum vm_power_stateget_power_state(session ref, VM ref)
Get the power_state field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Changed in:
XAPI 1.257.0 (1.257.0)
Made StaticRO to allow Suspended VM creation
Deprecated
VMPP refget_protection_policy(session ref, VM ref)
Get the protection_policy field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 FP1 (cowley)
Deprecated in:
XenServer 6.2 (clearwater)
The VMPR feature was removed
stringget_PV_args(session ref, VM ref)
Get the PV/args field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
kernel command-line arguments
stringget_PV_bootloader(session ref, VM ref)
Get the PV/bootloader field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
name of or path to bootloader
stringget_PV_bootloader_args(session ref, VM ref)
Get the PV/bootloader_args field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
miscellaneous arguments for the bootloader
stringget_PV_kernel(session ref, VM ref)
Get the PV/kernel field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
path to the kernel
stringget_PV_legacy_args(session ref, VM ref)
Get the PV/legacy_args field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
to make Zurich guests boot
stringget_PV_ramdisk(session ref, VM ref)
Get the PV/ramdisk field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
path to the initrd
stringget_recommendations(session ref, VM ref)
Get the recommendations field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
An XML specification of recommended values and ranges for properties of this VM
VM recordget_record(session ref, VM ref)
Get a record containing the current state of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
all fields from the 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
stringget_reference_label(session ref, VM ref)
Get the reference_label field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
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.
boolget_requires_reboot(session ref, VM ref)
Get the requires_reboot field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.1 (ely)
host refget_resident_on(session ref, VM ref)
Get the resident_on field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
the host the VM is currently resident on
host refget_scheduled_to_be_resident_on(session ref, VM ref)
Get the scheduled_to_be_resident_on field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
the host on which the VM is due to be started/resumed/migrated. This acts as a memory reservation indicator
intget_shutdown_delay(session ref, VM ref)
Get the shutdown_delay field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The delay to wait before proceeding to the next order in the shutdown sequence (seconds)
(string → string) mapget_snapshot_info(session ref, VM ref)
Get the snapshot_info field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
Human-readable information concerning this snapshot
stringget_snapshot_metadata(session ref, VM ref)
Get the snapshot_metadata field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.6 (midnight-ride)
Encoded information about the VM's metadata this is a snapshot of
VM refget_snapshot_of(session ref, VM ref)
Get the snapshot_of field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Ref pointing to the VM this snapshot is of.
VMSS refget_snapshot_schedule(session ref, VM ref)
Get the snapshot_schedule field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.2 (falcon)
Ref pointing to a snapshot schedule for this VM
datetimeget_snapshot_time(session ref, VM ref)
Get the snapshot_time field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Date/time when this snapshot was created.
VM ref setget_snapshots(session ref, VM ref)
Get the snapshots field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
List pointing to all the VM snapshots.
SR ref setget_SRs_required_for_recovery(session ref, VM ref, session ref)
List all the SR's that are required for the VM to be recovered
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM for which the SRs have to be recovered
session ref session_to
The session to which the SRs of the VM have to be recovered.
Minimum role:
read-only
Result:
refs for SRs required to recover the VM
Published in:
XenServer 6.5 (creedence)
List all the SR's that are required for the VM to be recovered
intget_start_delay(session ref, VM ref)
Get the start_delay field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The delay to wait before proceeding to the next order in the startup sequence (seconds)
SR refget_suspend_SR(session ref, VM ref)
Get the suspend_SR field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The SR on which a suspend image is stored
VDI refget_suspend_VDI(session ref, VM ref)
Get the suspend_VDI field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Changed in:
XAPI 1.257.0 (1.257.0)
Become static to allow Suspended VM creation
string setget_tags(session ref, VM ref)
Get the tags field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
stringget_transportable_snapshot_id(session ref, VM ref)
Get the transportable_snapshot_id field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
Transportable ID of the snapshot VM
intget_user_version(session ref, VM ref)
Get the user_version field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Creators of VMs and templates may store version information here.
stringget_uuid(session ref, VM ref)
Get the uuid field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
VBD ref setget_VBDs(session ref, VM ref)
Get the VBDs field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
virtual block devices
intget_VCPUs_at_startup(session ref, VM ref)
Get the VCPUs/at_startup field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Boot number of VCPUs
intget_VCPUs_max(session ref, VM ref)
Get the VCPUs/max field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
Max number of VCPUs
(string → string) mapget_VCPUs_params(session ref, VM ref)
Get the VCPUs/params field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
configuration parameters for the selected VCPU policy
intget_version(session ref, VM ref)
Get the version field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The number of times this VM has been recovered
VGPU ref setget_VGPUs(session ref, VM ref)
Get the VGPUs field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
VIF ref setget_VIFs(session ref, VM ref)
Get the VIFs field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
virtual network interfaces
VTPM ref setget_VTPMs(session ref, VM ref)
Get the VTPMs field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
virtual TPMs
VUSB ref setget_VUSBs(session ref, VM ref)
Get the VUSBs field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
vitual usb devices
(string → string) mapget_xenstore_data(session ref, VM ref)
Get the xenstore_data field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
data to be inserted into the xenstore tree (/local/domain/<domid>/vm-data) after the VM is created.
voidhard_reboot(session ref, VM ref)
Stop executing the specified VM without attempting a clean shutdown and immediately restart the VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to reboot
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
Stop executing the specified VM without attempting a clean shutdown and immediately restart the VM.
voidhard_shutdown(session ref, VM ref)
Stop executing the specified VM without attempting a clean shutdown.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to destroy
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
Stop executing the specified VM without attempting a clean shutdown.
VM ref setimport(session ref, string, SR ref, bool, bool)
intmaximise_memory(session ref, VM ref, int, bool)
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
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int total
Total amount of physical RAM to fit within
bool approximate
If false the limit is calculated with the guest's current exact configuration. Otherwise a more approximate calculation is performed
Minimum role:
read-only
Result:
The maximum possible static-max
Published in:
XenServer 4.1 (miami)
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
Migrate the VM to another host. This can only be called when the specified VM is in the Running state.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM
(string → string) map dest
The result of a Host.migrate_receive call.
bool live
Live migration
(VDI ref → SR ref) map vdi_map
Map of source VDI to destination SR
(VIF ref → network ref) map vif_map
Map of source VIF to destination network
(string → string) map options
Other parameters
(VGPU ref → GPU_group ref) map vgpu_map
Map of source vGPU to destination GPU group
Minimum role:
vm-power-admin
Result:
The reference of the newly created VM in the destination pool
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.
LICENCE_RESTRICTION
This operation is not allowed because your license lacks a needed feature. Please contact your support representative.
Published in:
XenServer 6.1 (tampa)
Migrate the VM to another host. This can only be called when the specified VM is in the Running state.
voidpause(session ref, VM ref)
Pause the specified VM. This can only be called when the specified VM is in the Running state.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to pause
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
Pause the specified VM. This can only be called when the specified VM is in the Running state.
voidpool_migrate(session ref, VM ref, host ref, (string → string) map)
Migrate a VM to another Host.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to migrate
host ref host
The target host
(string → string) map options
Extra configuration operations: force, live, copy, compress. Each is a boolean option, taking 'true' or 'false' as a value. Option 'compress' controls the use of stream compression during migration.
Minimum role:
client-cert
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
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.
Published in:
XenServer 4.0 (rio)
Migrate a VM to another Host.
voidpower_state_reset(session ref, VM ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to reset
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
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.
voidprovision(session ref, VM ref)
Inspects the disk configuration contained within the VM's other_config, creates VDIs and VBDs and then executes any applicable post-install script.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to be provisioned
Minimum role:
vm-admin
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)
Inspects the disk configuration contained within the VM's other_config, creates VDIs and VBDs and then executes any applicable post-install script.
floatquery_data_source(session ref, VM ref, string)
Query the latest value of the specified data source
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
string data_source
The data source to query
Minimum role:
read-only
Result:
The latest value, averaged over the last 5 seconds
Published in:
XenServer 5.0 (orlando)
Query the latest value of the specified data source
(string → string) mapquery_services(session ref, VM ref)
Query the system services advertised by this VM and register them. This can only be applied to a system domain.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
Minimum role:
pool-admin
Result:
map of service type to name
Published in:
XenServer 6.1 (tampa)
Query the system services advertised by this VM and register them. This can only be applied to a system domain.
voidrecord_data_source(session ref, VM ref, string)
Start recording the specified data source
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
string data_source
The data source to record
Minimum role:
vm-admin
Published in:
XenServer 5.0 (orlando)
Start recording the specified data source
voidrecover(session ref, VM ref, session ref, bool)
Recover the VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to recover
session ref session_to
The session to which the VM is to be recovered.
bool force
Whether the VM should replace newer versions of itself.
Minimum role:
read-only
Published in:
XenServer 6.0 (boston)
Recover the VM
voidremove_from_blocked_operations(session ref, VM ref, enum vm_operations)
Remove the given key and its corresponding value from the blocked_operations field of the given VM. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
enum vm_operations key
Key to remove
Minimum role:
vm-admin
Published in:
XenServer 5.0 (orlando)
List of operations which have been explicitly blocked and an error code
voidremove_from_HVM_boot_params(session ref, VM ref, string)
Remove the given key and its corresponding value from the HVM/boot_params field of the given VM. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to remove
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
HVM boot params
voidremove_from_NVRAM(session ref, VM ref, string)
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
string key
The key
Minimum role:
vm-admin
Published in:
Citrix Hypervisor 8.0 (naples)
voidremove_from_other_config(session ref, VM ref, string)
Remove the given key and its corresponding value from the other_config field of the given VM. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to remove
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
additional configuration
voidremove_from_platform(session ref, VM ref, string)
Remove the given key and its corresponding value from the platform field of the given VM. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to remove
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
platform-specific configuration
voidremove_from_VCPUs_params(session ref, VM ref, string)
Remove the given key and its corresponding value from the VCPUs/params field of the given VM. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to remove
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
configuration parameters for the selected VCPU policy
voidremove_from_xenstore_data(session ref, VM ref, string)
Remove the given key and its corresponding value from the xenstore_data field of the given VM. If the key is not in that Map, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string key
Key to remove
Minimum role:
vm-admin
Published in:
XenServer 4.1 (miami)
data to be inserted into the xenstore tree (/local/domain/<domid>/vm-data) after the VM is created.
voidremove_tags(session ref, VM ref, string)
Remove the given value from the tags field of the given VM. If the value is not in that Set, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
Value to remove
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
Prototype
voidrestart_device_models(session ref, VM ref)
Restart device models of the VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
Minimum role:
client-cert
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
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.
Prototyped in:
XAPI 23.30.0 (23.30.0)
voidresume(session ref, VM ref, bool, bool)
Awaken the specified VM and resume it. This can only be called when the specified VM is in the Suspended state.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to resume
bool start_paused
Resume VM in paused state if set to true.
bool force
Attempt to force the VM to resume. If this flag is false then the VM may fail pre-resume safety checks (e.g. if the CPU the VM was running 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.
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
Awaken the specified VM and resume it. This can only be called when the specified VM is in the Suspended state.
voidresume_on(session ref, VM ref, host ref, bool, bool)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to resume
host ref host
The Host on which to resume the VM
bool start_paused
Resume VM in paused state if set to true.
bool force
Attempt to force the VM to resume. If this flag is false then the VM may fail pre-resume safety checks (e.g. if the CPU the VM was running on looks substantially different to the current one)
Minimum role:
client-cert
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.
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
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.
(host ref → string set) mapretrieve_wlb_recommendations(session ref, VM ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM
Minimum role:
read-only
Result:
The potential hosts and their corresponding recommendations or errors
Published in:
XenServer 5.5 (george)
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.
voidrevert(session ref, VM ref)
Reverts the specified VM to a previous state.
Parameters:
session ref session_id
Reference to a valid session
VM ref snapshot
The snapshotted state that we revert to
Minimum role:
vm-power-admin
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.
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
SR_FULL
The SR is full. Requested new size exceeds the maximum size
VM_REVERT_FAILED
An error occured while reverting the specified virtual machine to the specified snapshot
Published in:
XenServer 5.6 (midnight-ride)
Reverts the specified VM to a previous state.
voidsend_sysrq(session ref, VM ref, string)
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.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM
string key
The key to send
Minimum role:
pool-admin
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.
Published in:
XenServer 4.0 (rio)
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.
voidsend_trigger(session ref, VM ref, string)
Send the named trigger to this VM. This can only be called when the specified VM is in the Running state.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM
string trigger
The trigger to send
Minimum role:
pool-admin
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.
Published in:
XenServer 4.0 (rio)
Send the named trigger to this VM. This can only be called when the specified VM is in the Running state.
voidset_actions_after_crash(session ref, VM ref, enum on_crash_behaviour)
Sets the actions_after_crash parameter
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to set
enum on_crash_behaviour value
The new value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Sets the actions_after_crash parameter
voidset_actions_after_reboot(session ref, VM ref, enum on_normal_exit)
Set the actions/after_reboot field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
enum on_normal_exit value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
action to take after the guest has rebooted itself
voidset_actions_after_shutdown(session ref, VM ref, enum on_normal_exit)
Set the actions/after_shutdown field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
enum on_normal_exit value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
action to take after the guest has shutdown itself
Prototype
voidset_actions_after_softreboot(session ref, VM ref, enum on_softreboot_behavior)
Set the actions/after_softreboot field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
enum on_softreboot_behavior value
New value to set
Minimum role:
vm-admin
Prototyped in:
XAPI 23.1.0 (23.1.0)
voidset_affinity(session ref, VM ref, host ref)
Set the affinity field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
host ref value
New value to set
Minimum role:
vm-power-admin
Published in:
XenServer 4.0 (rio)
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. Resource constraints may cause the VM to be started elsewhere.
voidset_appliance(session ref, VM ref, VM_appliance ref)
Assign this VM to an appliance.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to assign to an appliance.
VM_appliance ref value
The appliance to which this VM should be assigned.
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
Assign this VM to an appliance.
voidset_bios_strings(session ref, VM ref, (string → string) map)
Set custom BIOS strings to this VM. VM will be given a default set of BIOS strings, only some of which can be overridden by the supplied values. Allowed keys are: 'bios-vendor', 'bios-version', 'system-manufacturer', 'system-product-name', 'system-version', 'system-serial-number', 'enclosure-asset-tag', 'baseboard-manufacturer', 'baseboard-product-name', 'baseboard-version', 'baseboard-serial-number', 'baseboard-asset-tag', 'baseboard-location-in-chassis', 'enclosure-asset-tag'
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to modify
(string → string) map value
The custom BIOS strings as a list of key-value pairs
Minimum role:
vm-admin
Errors:
VM_BIOS_STRINGS_ALREADY_SET
The BIOS strings for this VM have already been set and cannot be changed.
INVALID_VALUE
The value given is invalid
Published in:
XenServer 7.3 (inverness)
Set custom BIOS strings to this VM. VM will be given a default set of BIOS strings, only some of which can be overridden by the supplied values. Allowed keys are: 'bios-vendor', 'bios-version', 'system-manufacturer', 'system-product-name', 'system-version', 'system-serial-number', 'enclosure-asset-tag', 'baseboard-manufacturer', 'baseboard-product-name', 'baseboard-version', 'baseboard-serial-number', 'baseboard-asset-tag', 'baseboard-location-in-chassis', 'enclosure-asset-tag'
voidset_blocked_operations(session ref, VM ref, (enum vm_operations → string) map)
Set the blocked_operations field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
(enum vm_operations → string) map value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 5.0 (orlando)
List of operations which have been explicitly blocked and an error code
voidset_domain_type(session ref, VM ref, enum domain_type)
Set the VM.domain_type field of the given VM, which will take effect when it is next started
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
enum domain_type value
The new domain type
Minimum role:
vm-admin
Published in:
XenServer 7.5 (kolkata)
Deprecated
voidset_ha_always_run(session ref, VM ref, bool)
Set the value of the ha_always_run
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
bool value
The value
Minimum role:
pool-operator
Published in:
XenServer 5.0 (orlando)
Set the value of the ha_always_run
Deprecated in:
XenServer 6.0 (boston)
voidset_ha_restart_priority(session ref, VM ref, string)
Set the value of the ha_restart_priority field
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
string value
The value
Minimum role:
pool-operator
Published in:
XenServer 5.0 (orlando)
Set the value of the ha_restart_priority field
voidset_hardware_platform_version(session ref, VM ref, int)
Set the hardware_platform_version field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
int value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 6.5 SP1 (cream)
The host virtual hardware platform version the VM can run on
voidset_has_vendor_device(session ref, VM ref, bool)
Controls whether, when the VM starts in HVM mode, its virtual hardware will include the emulated PCI device for which drivers may be available through Windows Update. Usually this should never be changed on a VM on which Windows has been installed: changing it on such a VM is likely to lead to a crash on next start.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM on which to set this flag
bool value
True to provide the vendor PCI device.
Minimum role:
vm-admin
Published in:
XenServer 7.0 (dundee)
Controls whether, when the VM starts in HVM mode, its virtual hardware will include the emulated PCI device for which drivers may be available through Windows Update. Usually this should never be changed on a VM on which Windows has been installed: changing it on such a VM is likely to lead to a crash on next start.
voidset_HVM_boot_params(session ref, VM ref, (string → string) map)
Set the HVM/boot_params field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
HVM boot params
Deprecated
voidset_HVM_boot_policy(session ref, VM ref, string)
Set the VM.HVM_boot_policy field of the given VM, which will take effect when it is next started
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
string value
The new HVM boot policy
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Deprecated in:
XenServer 7.5 (kolkata)
Replaced by VM.set_domain_type
voidset_HVM_shadow_multiplier(session ref, VM ref, float)
Set the shadow memory multiplier on a halted VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
float value
The new shadow memory multiplier to set
Minimum role:
vm-power-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the shadow memory multiplier on a halted VM
voidset_is_a_template(session ref, VM ref, bool)
Set the is_a_template field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
bool value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
true if this is a template. Template VMs can never be started, they are used only for cloning other VMs
voidset_memory(session ref, VM ref, int)
Set the memory allocation of this VM. Sets all of memory_static_max, memory_dynamic_min, and memory_dynamic_max to the given value, and leaves memory_static_min untouched.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int value
The new memory allocation (bytes).
Minimum role:
vm-power-admin
Published in:
XenServer 7.1 (ely)
Set the memory allocation of this VM. Sets all of memory_static_max, memory_dynamic_min, and memory_dynamic_max to the given value, and leaves memory_static_min untouched.
voidset_memory_dynamic_max(session ref, VM ref, int)
Set the value of the memory_dynamic_max field
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to modify
int value
The new value of memory_dynamic_max
Minimum role:
vm-power-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the value of the memory_dynamic_max field
voidset_memory_dynamic_min(session ref, VM ref, int)
Set the value of the memory_dynamic_min field
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to modify
int value
The new value of memory_dynamic_min
Minimum role:
vm-power-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the value of the memory_dynamic_min field
voidset_memory_dynamic_range(session ref, VM ref, int, int)
Set the minimum and maximum amounts of physical memory the VM is allowed to use.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int min
The new minimum value
int max
The new maximum value
Minimum role:
vm-power-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the minimum and maximum amounts of physical memory the VM is allowed to use.
voidset_memory_limits(session ref, VM ref, int, int, int, int)
Set the memory limits of this VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int static_min
The new value of memory_static_min.
int static_max
The new value of memory_static_max.
int dynamic_min
The new value of memory_dynamic_min.
int dynamic_max
The new value of memory_dynamic_max.
Minimum role:
vm-power-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the memory limits of this VM.
voidset_memory_static_max(session ref, VM ref, int)
Set the value of the memory_static_max field
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to modify
int value
The new value of memory_static_max
Minimum role:
vm-power-admin
Errors:
HA_OPERATION_WOULD_BREAK_FAILOVER_PLAN
This operation cannot be performed because it would invalidate VM failover planning such that the system would be unable to guarantee to restart protected VMs after a Host failure.
Published in:
XenServer 5.0 (orlando)
Set the value of the memory_static_max field
voidset_memory_static_min(session ref, VM ref, int)
Set the value of the memory_static_min field
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM to modify
int value
The new value of memory_static_min
Minimum role:
vm-power-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the value of the memory_static_min field
voidset_memory_static_range(session ref, VM ref, int, int)
Set the static (ie boot-time) range of virtual memory that the VM is allowed to use.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int min
The new minimum value
int max
The new maximum value
Minimum role:
vm-power-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the static (ie boot-time) range of virtual memory that the VM is allowed to use.
Deprecated
voidset_memory_target_live(session ref, VM ref, int)
Set the memory target for a running VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int target
The target in bytes
Minimum role:
vm-power-admin
Published in:
XenServer 4.0 (rio)
Set the memory target for a running VM
Deprecated in:
XenServer 5.6 (midnight-ride)
voidset_name_description(session ref, VM ref, string)
Set the name/description field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
voidset_name_label(session ref, VM ref, string)
Set the name/label field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
a human-readable name
voidset_NVRAM(session ref, VM ref, (string → string) map)
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
(string → string) map value
The value
Minimum role:
vm-admin
Published in:
Citrix Hypervisor 8.0 (naples)
voidset_order(session ref, VM ref, int)
Set this VM's boot order
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int value
This VM's boot order
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
Set this VM's boot order
voidset_other_config(session ref, VM ref, (string → string) map)
Set the other_config field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
additional configuration
Deprecated
voidset_PCI_bus(session ref, VM ref, string)
Set the PCI_bus field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
PCI bus path for pass-through devices
Deprecated in:
XenServer 6.0 (boston)
Field was never used
voidset_platform(session ref, VM ref, (string → string) map)
Set the platform field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
platform-specific configuration
Removed
voidset_protection_policy(session ref, VM ref, VMPP ref)
Set the value of the protection_policy field
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
VMPP ref value
The value
Minimum role:
pool-operator
Published in:
XenServer 5.6 FP1 (cowley)
Deprecated in:
XenServer 6.2 (clearwater)
Dummy transition
Removed in:
XenServer 6.2 (clearwater)
The VMPR feature was removed
voidset_PV_args(session ref, VM ref, string)
Set the PV/args field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
kernel command-line arguments
voidset_PV_bootloader(session ref, VM ref, string)
Set the PV/bootloader field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
name of or path to bootloader
voidset_PV_bootloader_args(session ref, VM ref, string)
Set the PV/bootloader_args field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
miscellaneous arguments for the bootloader
voidset_PV_kernel(session ref, VM ref, string)
Set the PV/kernel field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
path to the kernel
voidset_PV_legacy_args(session ref, VM ref, string)
Set the PV/legacy_args field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
to make Zurich guests boot
voidset_PV_ramdisk(session ref, VM ref, string)
Set the PV/ramdisk field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
path to the initrd
voidset_recommendations(session ref, VM ref, string)
Set the recommendations field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
An XML specification of recommended values and ranges for properties of this VM
voidset_shadow_multiplier_live(session ref, VM ref, float)
Set the shadow memory multiplier on a running VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
float multiplier
The new shadow memory multiplier to set
Minimum role:
vm-power-admin
Published in:
XenServer 4.0 (rio)
Set the shadow memory multiplier on a running VM
voidset_shutdown_delay(session ref, VM ref, int)
Set this VM's shutdown delay in seconds
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int value
This VM's shutdown delay in seconds
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
Set this VM's shutdown delay in seconds
voidset_snapshot_schedule(session ref, VM ref, VMSS ref)
Set the value of the snapshot schedule field
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
VMSS ref value
The value
Minimum role:
pool-operator
Published in:
XenServer 7.2 (falcon)
Set the value of the snapshot schedule field
voidset_start_delay(session ref, VM ref, int)
Set this VM's start delay in seconds
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int value
This VM's start delay in seconds
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
Set this VM's start delay in seconds
voidset_suspend_SR(session ref, VM ref, SR ref)
Set the suspend_SR field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
SR ref value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 6.0 (boston)
The SR on which a suspend image is stored
voidset_suspend_VDI(session ref, VM ref, VDI ref)
Set this VM's suspend VDI, which must be indentical to its current one
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
VDI ref value
The suspend VDI uuid
Minimum role:
pool-operator
Published in:
XenServer 6.0 (boston)
Set this VM's suspend VDI, which must be indentical to its current one
voidset_tags(session ref, VM ref, string set)
Set the tags field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
string set value
New value to set
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
voidset_user_version(session ref, VM ref, int)
Set the user_version field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
int value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Creators of VMs and templates may store version information here.
voidset_VCPUs_at_startup(session ref, VM ref, int)
Set the number of startup VCPUs for a halted VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int value
The new maximum number of VCPUs
Minimum role:
vm-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the number of startup VCPUs for a halted VM
voidset_VCPUs_max(session ref, VM ref, int)
Set the maximum number of VCPUs for a halted VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int value
The new maximum number of VCPUs
Minimum role:
vm-admin
Published in:
XenServer 5.6 (midnight-ride)
Set the maximum number of VCPUs for a halted VM
voidset_VCPUs_number_live(session ref, VM ref, int)
Set the number of VCPUs for a running VM
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
int nvcpu
The number of VCPUs
Minimum role:
vm-admin
Errors:
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)
Set the number of VCPUs for a running VM
Changed in:
XenServer 7.1 (ely)
Unless the feature is explicitly enabled for every host in the pool, this fails with Api_errors.license_restriction.
voidset_VCPUs_params(session ref, VM ref, (string → string) map)
Set the VCPUs/params field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
configuration parameters for the selected VCPU policy
voidset_xenstore_data(session ref, VM ref, (string → string) map)
Set the xenstore_data field of the given VM.
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
(string → string) map value
New value to set
Minimum role:
vm-admin
Published in:
XenServer 4.1 (miami)
data to be inserted into the xenstore tree (/local/domain/<domid>/vm-data) after the VM is created.
voidshutdown(session ref, VM ref)
Attempts to first clean shutdown a VM and if it should fail then perform a hard shutdown on it.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to shutdown
Minimum role:
client-cert
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 6.2 (clearwater)
Attempts to first clean shutdown a VM and if it should fail then perform a hard shutdown on it.
VM refsnapshot(session ref, VM ref, string, VDI ref set)
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).
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
VDI ref set ignore_vdis
A list of VDIs to ignore for the snapshot
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.
Published in:
XenServer 5.0 (orlando)
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).
Removed
VM refsnapshot_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
voidstart(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.
voidstart_on(session ref, VM ref, host ref, bool, bool)
Start the specified VM on a particular host. 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
host ref host
The Host on which to start the VM
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:
client-cert
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_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
Published in:
XenServer 4.0 (rio)
Start the specified VM on a particular host. This function can only be called with the VM is in the Halted State.
voidsuspend(session ref, VM ref)
Suspend the specified VM to disk. This can only be called when the specified VM is in the Running state.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to suspend
Minimum role:
client-cert
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.
OTHER_OPERATION_IN_PROGRESS
Another operation involving the object is currently in progress
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
Suspend the specified VM to disk. This can only be called when the specified VM is in the Running state.
voidunpause(session ref, VM ref)
Resume the specified VM. This can only be called when the specified VM is in the Paused state.
Parameters:
session ref session_id
Reference to a valid session
VM ref vm
The VM to unpause
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.
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VM_IS_TEMPLATE
The operation attempted is not valid for a template VM
Published in:
XenServer 4.0 (rio)
Resume the specified VM. This can only be called when the specified VM is in the Paused state.
voidupdate_allowed_operations(session ref, VM ref)
Recomputes the list of acceptable operations
Parameters:
session ref session_id
Reference to a valid session
VM ref self
reference to the object
Minimum role:
pool-admin
Published in:
XenServer 4.0 (rio)
Recomputes the list of acceptable operations
Deprecated
voidwait_memory_target_live(session ref, VM ref)
Wait for a running VM to reach its current memory target
Parameters:
session ref session_id
Reference to a valid session
VM ref self
The VM
Minimum role:
read-only
Published in:
XenServer 5.0 (orlando)
Wait for a running VM to reach its current memory target
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
Get the allowed_operations field of the given VM_appliance.
Parameters:
session ref session_id
Reference to a valid session
VM_appliance ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
Set the name/label field of the given VM_appliance.
Parameters:
session ref session_id
Reference to a valid session
VM_appliance ref self
reference to the object
string value
New value to set
Minimum role:
pool-operator
Published in:
XenServer 4.0 (rio)
a human-readable name
voidshutdown(session ref, VM_appliance ref)
For each VM in the appliance, try to shut it down cleanly. If this fails, perform a hard shutdown of the VM.
Parameters:
session ref session_id
Reference to a valid session
VM_appliance ref self
The VM appliance
Minimum role:
pool-operator
Errors:
OPERATION_PARTIALLY_FAILED
Some VMs belonging to the appliance threw an exception while carrying out the specified operation
Published in:
XenServer 6.0 (boston)
For each VM in the appliance, try to shut it down cleanly. If this fails, perform a hard shutdown of the VM.
voidstart(session ref, VM_appliance ref, bool)
Start all VMs in the appliance
Parameters:
session ref session_id
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
Errors:
OPERATION_PARTIALLY_FAILED
Some VMs belonging to the appliance threw an exception while carrying out the specified operation
Published in:
XenServer 6.0 (boston)
Start all VMs in the appliance
VM_guest_metrics
Class: VM_guest_metrics
The metrics reported by the guest (as opposed to inferred from outside)
Published in:
XenServer 4.0 (rio)
The metrics reported by the guest (as opposed to inferred from outside)
Enums
tristate_type
Values:
yes
Known to be true
no
Known to be false
unspecified
Unknown or unspecified
Fields
enum tristate_typecan_use_hotplug_vbd[RO/runtime]
The guest's statement of whether it supports VBD hotplug, i.e. whether it is capable of responding immediately to instantiation of a new VBD by bringing online a new PV block device. If the guest states that it is not capable, then the VBD plug and unplug operations will not be allowed while the guest is running.
Default value:
unspecified
Published in:
XenServer 7.0 (dundee)
To be used where relevant and available instead of checking PV driver version.
enum tristate_typecan_use_hotplug_vif[RO/runtime]
The guest's statement of whether it supports VIF hotplug, i.e. whether it is capable of responding immediately to instantiation of a new VIF by bringing online a new PV network device. If the guest states that it is not capable, then the VIF plug and unplug operations will not be allowed while the guest is running.
Default value:
unspecified
Published in:
XenServer 7.0 (dundee)
To be used where relevant and available instead of checking PV driver version.
Removed
(string → string) mapdisks[RO/runtime]
This field exists but has no data.
Default value:
{}
Published in:
XenServer 4.0 (rio)
Disk configuration/free space
Deprecated in:
XenServer 5.0 (orlando)
Dummy transition
Removed in:
XenServer 5.0 (orlando)
No data
datetimelast_updated[RO/runtime]
Time at which this information was last updated
Published in:
XenServer 4.0 (rio)
Time at which this information was last updated
boollive[RO/runtime]
True if the guest is sending heartbeat messages via the guest agent
Default value:
false
Published in:
XenServer 5.0 (orlando)
True if the guest is sending heartbeat messages via the guest agent
Removed
(string → string) mapmemory[RO/runtime]
This field exists but has no data. Use the memory and memory_internal_free RRD data-sources instead.
Default value:
{}
Published in:
XenServer 4.0 (rio)
free/used/total
Deprecated in:
XenServer 5.5 (george)
Dummy transition
Removed in:
XenServer 5.5 (george)
Disabled in favour of the RRDs, to improve scalability
(string → string) mapnetworks[RO/runtime]
network configuration
Published in:
XenServer 4.0 (rio)
network configuration
(string → string) mapos_version[RO/runtime]
version of the OS
Published in:
XenServer 4.0 (rio)
version of the OS
(string → string) mapother[RO/runtime]
anything else
Published in:
XenServer 4.0 (rio)
anything else
(string → string) mapother_config[RW]
additional configuration
Default value:
{}
Published in:
XenServer 5.0 (orlando)
additional configuration
boolPV_drivers_detected[RO/runtime]
At least one of the guest's devices has successfully connected to the backend.
Default value:
false
Published in:
XenServer 7.0 (dundee)
Deprecated
boolPV_drivers_up_to_date[RO/runtime]
Logically equivalent to PV_drivers_detected
Published in:
XenServer 4.0 (rio)
true if the PV drivers appear to be up to date
Deprecated in:
XenServer 7.0 (dundee)
Deprecated in favour of PV_drivers_detected, and redefined in terms of it
Remove the given key and its corresponding value from the other_config field of the given VM_guest_metrics. If the key is not in that Map, then do nothing.
Create a new VMSS instance, and return its handle.
The constructor args are: name_label, name_description, enabled, type*, retained_snapshots, frequency*, schedule (* = non-optional).
Parameters:
session ref session_id
Reference to a valid session
VMSS record args
All constructor arguments
Minimum role:
pool-operator
Result:
reference to the newly created object
Published in:
XenServer 7.2 (falcon)
VM Snapshot Schedule
voiddestroy(session ref, VMSS ref)
Destroy the specified VMSS instance.
Parameters:
session ref session_id
Reference to a valid session
VMSS ref self
reference to the object
Minimum role:
pool-operator
Published in:
XenServer 7.2 (falcon)
VM Snapshot Schedule
VMSS ref setget_all(session ref)
Return a list of all the VMSSs known to the system.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
Get the allowed_operations field of the given VTPM.
Parameters:
session ref session_id
Reference to a valid session
VTPM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
VM refget_backend(session ref, VTPM ref)
Get the backend field of the given VTPM.
Parameters:
session ref session_id
Reference to a valid session
VTPM ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
The domain where the backend is located (unused)
Prototype
VTPM refget_by_uuid(session ref, string)
Get a reference to the VTPM instance with the specified UUID.
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
Get the allowed_operations field of the given VUSB.
Parameters:
session ref session_id
Reference to a valid session
VUSB ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
VUSB refget_by_uuid(session ref, string)
Get a reference to the VUSB instance with the specified UUID.
