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
int
API_version_major
[RO/runtime]
major version number
Published in: XenServer 4.0 (rio)
major version number
int
API_version_minor
[RO/runtime]
minor version number
Published in: XenServer 4.0 (rio)
minor version number
string
API_version_vendor
[RO/runtime]
identification of vendor
Published in: XenServer 4.0 (rio)
identification of vendor
(string → string) map
API_version_vendor_implementation
[RO/runtime]
details of vendor implementation
Published in: XenServer 4.0 (rio)
details of vendor implementation
PBD ref set
PBDs
[RO/runtime]
physical blockdevices
Published in: XenServer 4.0 (rio)
physical blockdevices
PCI ref set
PCIs
[RO/runtime]
List of PCI devices in the host
Published in: XenServer 6.0 (boston)
PGPU ref set
PGPUs
[RO/runtime]
List of physical GPUs in the host
Published in: XenServer 6.0 (boston)
PIF ref set
PIFs
[RO/runtime]
physical network interfaces
Published in: XenServer 4.0 (rio)
physical network interfaces
PUSB ref set
PUSBs
[RO/runtime]
List of physical USBs in the host
Published in: XenServer 7.3 (inverness)
string
address
[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
enum host_allowed_operations set
allowed_operations
[RO/runtime]
list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client.
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 → string) map
bios_strings
[RO/runtime]
BIOS strings
Default value: {}
Published in: XenServer 5.6 (midnight-ride)
BIOS strings
(string → blob ref) map
blobs
[RO/runtime]
Binary blobs associated with this host
Default value: {}
Published in: XenServer 5.0 (orlando)
Binary blobs associated with this host
string set
capabilities
[RO/constructor]
Xen capabilities
Published in: XenServer 4.0 (rio)
Xen capabilities
Certificate ref set
certificates
[RO/runtime]
List of certificates installed in the host
Published in: Citrix Hypervisor 8.2 (stockholm)
(string → string) map
chipset_info
[RO/runtime]
Information about chipset features
Default value: {}
Published in: XenServer 6.0 (boston)
VM ref
control_domain
[RO/runtime]
The control domain (domain 0)
Default value: OpaqueRef:NULL
Published in: XenServer 7.1 (ely)
The control domain (domain 0)
(string → string) map
cpu_configuration
[RO/runtime]
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"
(string → string) map
cpu_info
[RO/runtime]
Details about the physical CPUs on this host
Default value: {}
Published in: XenServer 5.6 (midnight-ride)
Details about the physical CPUs on this host
SR ref
crash_dump_sr
[RW]
The SR in which VDIs for crash dumps are created
Published in: XenServer 4.0 (rio)
The SR in which VDIs for crash dumps are created
host_crashdump ref set
crashdumps
[RO/runtime]
Set of host crash dumps
Published in: XenServer 4.0 (rio)
Set of host crash dumps
(string → enum host_allowed_operations) map
current_operations
[RO/runtime]
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
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.
enum host_display
display
[RW]
indicates whether the host is configured to output its console to a physical display device
Default value: enabled
Published in: XenServer 6.5 SP1 (cream)
indicates whether the host is configured to output its console to a physical display device
string
edition
[RO/runtime]
Product edition
Default value: ""
Published in: XenServer 5.6 (midnight-ride)
Product edition
string set
editions
[RO/runtime]
List of all available product editions
Default value: {}
Published in: Citrix Hypervisor 8.2 (stockholm)
bool
enabled
[RO/runtime]
True if the host is currently enabled
Published in: XenServer 4.0 (rio)
True if the host is currently enabled
(string → string) map
external_auth_configuration
[RO/runtime]
configuration specific to external authentication service
Default value: {}
Published in: XenServer 5.5 (george)
configuration specific to external authentication service
string
external_auth_service_name
[RO/runtime]
name of external authentication service configured; empty if none configured.
Default value: ""
Published in: XenServer 5.5 (george)
name of external authentication service configured; empty if none configured.
string
external_auth_type
[RO/runtime]
type of external authentication service configured; empty if none configured.
Default value: ""
Published in: XenServer 5.5 (george)
type of external authentication service configured; empty if none configured.
Feature ref set
features
[RO/runtime]
List of features available on this host
Published in: XenServer 7.2 (falcon)
(string → string) map
guest_VCPUs_params
[RW]
VCPUs params to apply to all resident guests
Default value: {}
Published in: XenServer 6.1 (tampa)
VCPUs params to apply to all resident guests
string set
ha_network_peers
[RO/runtime]
The set of hosts visible via the network from this host
Default value: {}
Published in: XenServer 5.0 (orlando)
The set of hosts visible via the network from this host
string set
ha_statefiles
[RO/runtime]
The set of statefiles accessible from this host
Default value: {}
Published in: XenServer 5.0 (orlando)
The set of statefiles accessible from this host
host_cpu ref set
host_CPUs
[RO/runtime]
The physical CPUs on this host
Published in: XenServer 4.0 (rio)
The physical CPUs on this host
string
hostname
[RW]
The hostname of this host
Published in: XenServer 4.0 (rio)
The hostname of this host
Prototype
bool
https_only
[RO/runtime]
Reflects whether port 80 is open (false) or not (true)
Default value: false
Prototyped in: XAPI 22.27.0 (22.27.0)
string
iscsi_iqn
[RO/constructor]
The initiator IQN for the host
Default value: ""
Published in: XenServer 7.5 (kolkata)
Prototype
datetime
last_software_update
[RO/runtime]
Date and time when the last software update was applied
Default value: 19700101T00:00:00Z
Prototyped in: XAPI 22.20.0 (22.20.0)
Prototype
string
last_update_hash
[RO/runtime]
The SHA256 checksum of updateinfo of the most recently applied update on the host
Default value: ""
Prototyped in: XAPI 24.10.0 (24.10.0)
Prototype
enum latest_synced_updates_applied_state
latest_synced_updates_applied
[RO/runtime]
Default as 'unknown', 'yes' if the host is up to date with updates synced from remote CDN, otherwise 'no'
Default value: unknown
Prototyped in: XAPI 23.18.0 (23.18.0)
(string → string) map
license_params
[RO/runtime]
State of the current license
Published in: XenServer 4.0 (rio)
State of the current license
(string → string) map
license_server
[RW]
Contact information of the license server
Default value: {"address" -> "localhost", "port" -> "27000"}
Published in: XenServer 5.6 (midnight-ride)
Contact information of the license server
SR ref
local_cache_sr
[RO/constructor]
The SR that is used as a local cache
Default value: OpaqueRef:NULL
Published in: XenServer 5.6 FP1 (cowley)
The SR that is used as a local cache
(string → string) map
logging
[RW]
logging configuration
Published in: XenServer 4.0 (rio)
logging configuration
int
memory_overhead
[RO/runtime]
Virtualization memory overhead (bytes).
Default value: 0
Published in: XenServer 4.0 (rio)
Virtualization memory overhead (bytes).
host_metrics ref
metrics
[RO/runtime]
metrics associated with this host
Published in: XenServer 4.0 (rio)
metrics associated with this host
bool
multipathing
[RO/constructor]
Specifies whether multipathing is enabled
Default value: false
Published in: XenServer 7.5 (kolkata)
string
name_description
[RW]
a notes field containing human-readable description
Default value: ""
Published in: XenServer 4.0 (rio)
string
name_label
[RW]
a human-readable name
Default value: ""
Published in: XenServer 4.0 (rio)
Prototype
enum host_numa_affinity_policy
numa_affinity_policy
[RO/runtime]
NUMA-aware VM memory and vCPU placement policy
Default value: default_policy
Prototyped in: XAPI 24.0.0 (24.0.0)
(string → string) map
other_config
[RW]
additional configuration
Published in: XenServer 4.0 (rio)
additional configuration
Deprecated
host_patch ref set
patches
[RO/runtime]
Set of host patches
Published in: XenServer 4.0 (rio)
Set of host patches
Deprecated in: XenServer 7.1 (ely)
enum update_guidances set
pending_guidances
[RO/runtime]
The set of pending mandatory guidances after applying updates, which must be applied, as otherwise there may be e.g. VM failures
Default value: {}
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 set
pending_guidances_full
[RO/runtime]
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
Default value: {}
Prototyped in: XAPI 24.10.0 (24.10.0)
Prototype
enum update_guidances set
pending_guidances_recommended
[RO/runtime]
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) map
power_on_config
[RO/runtime]
The power on config
Default value: {}
Published in: XenServer 5.6 (midnight-ride)
The power on config
string
power_on_mode
[RO/runtime]
The power on mode
Default value: ""
Published in: XenServer 5.6 (midnight-ride)
The power on mode
VM ref set
resident_VMs
[RO/runtime]
list of VMs currently resident on host
Published in: XenServer 4.0 (rio)
list of VMs currently resident on host
string
sched_policy
[RO/runtime]
Scheduler policy currently in force on this host
Published in: XenServer 4.0 (rio)
Scheduler policy currently in force on this host
(string → string) map
software_version
[RO/constructor]
version strings
Published in: XenServer 4.0 (rio)
version strings
Deprecated
bool
ssl_legacy
[RO/constructor]
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 set
supported_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 ref
suspend_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
bool
tls_verification_enabled
[RO/runtime]
True if this host has TLS verifcation enabled
Default value: false
Published in: XAPI 1.313.0 (1.313.0)
True if this host has TLS verifcation enabled
Deprecated
string
uefi_certificates
[RO/constructor]
The UEFI certificates allowing Secure Boot
Default value: ""
Published in: Citrix Hypervisor 8.1 (quebec)
Deprecated in: XAPI 22.16.0 (22.16.0)
Use Pool.uefi_certificates instead
pool_update ref set
updates
[RO/runtime]
Set of updates
Published in: XenServer 7.1 (ely)
Set of updates
pool_update ref set
updates_requiring_reboot
[RO/runtime]
List of updates which require reboot
Published in: XenServer 7.1 (ely)
string
uuid
[RO/runtime]
Unique identifier/object reference
Published in: XenServer 4.0 (rio)
Unique identifier/object reference
int set
virtual_hardware_platform_versions
[RO/runtime]
Messages
Hide implicit
void
add_tags
(session ref, host ref, string)
void
add_to_guest_VCPUs_params
(session ref, host ref, string, string)
Add the given key-value pair to the guest_VCPUs_params field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role: pool-operator
Published in: XenServer 6.1 (tampa)
VCPUs params to apply to all resident guests
void
add_to_license_server
(session ref, host ref, string, string)
Add the given key-value pair to the license_server field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string key
Key to add
string value
Value to add
Minimum role: pool-operator
Published in: XenServer 5.6 (midnight-ride)
Contact information of the license server
void
add_to_logging
(session ref, host ref, string, string)
Add the given key-value pair to the logging field of the given host.
Parameters: session ref session_id
Reference to a valid session
host 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)
logging configuration
void
add_to_other_config
(session ref, host ref, string, string)
Add the given key-value pair to the other_config field of the given host.
Parameters: session ref session_id
Reference to a valid session
host 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
void
apply_edition
(session ref, host ref, string, bool)
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.
Removed
void
apply_recommended_guidances
(session ref, host ref)
apply all recommended guidances both on the host and on all HVM VMs on the host after updates are applied on the host
Parameters: session ref session_id
Reference to a valid session
host ref self
The host whose recommended guidances will be applied
Minimum role: pool-operator
Prototyped in: XAPI 23.18.0 (23.18.0)
Removed in: XAPI 23.25.0 (23.25.0)
string set set
apply_updates
(session ref, host ref, string)
apply updates from current enabled repository on a host
Parameters: session ref session_id
Reference to a valid session
host ref self
The host where updates will be applied
string hash
The hash of updateinfo to be applied which is returned by previous pool.sync_udpates
Minimum role: client-cert
Result: The list of results after applying updates, including livepatch apply failures and recommended guidances
Published in: XAPI 1.301.0 (1.301.0)
void
assert_can_evacuate
(session ref, host ref)
Check this host can be evacuated.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host to evacuate
Minimum role: pool-operator
Published in: XenServer 4.1 (miami)
Check this host can be evacuated.
void
backup_rrds
(session ref, host ref, float)
This causes the RRDs to be backed up to the master
Parameters: session ref session_id
Reference to a valid session
host ref host
Schedule a backup of the RRDs of this host
float delay
Delay in seconds from when the call is received to perform the backup
Minimum role: pool-admin
Published in: XenServer 5.0 (orlando)
This causes the RRDs to be backed up to the master
void
bugreport_upload
(session ref, host ref, string, (string → string) map)
Run xen-bugtool --yestoall and upload the output to support
Parameters: session ref session_id
Reference to a valid session
host ref host
The host on which to run xen-bugtool
string url
The URL to upload to
(string → string) map options
Extra configuration operations
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
Run xen-bugtool --yestoall and upload the output to support
string
call_extension
(session ref, host ref, string)
Call an API extension on this host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string call
Rpc call for the extension
Minimum role: pool-admin
Result: Result from the extension
Published in: XenServer 7.1 (ely)
Call an API extension on this host
string
call_plugin
(session ref, host ref, string, string, (string → string) map)
Call an API plugin on this host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
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: pool-admin
Result: Result from the plugin
Published in: XenServer 5.0 (orlando)
Call an API plugin on this host
int
compute_free_memory
(session ref, host ref)
Computes the amount of free memory on the host.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host to send the request to
Minimum role: read-only
Result: the amount of free memory on the host.
Published in: XenServer 5.0 (orlando)
Computes the amount of free memory on the host.
int
compute_memory_overhead
(session ref, host ref)
Computes the virtualization memory overhead of a host.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host for which to compute the memory overhead
Minimum role: read-only
Result: the virtualization memory overhead of the host.
Published in: XenServer 5.6 (midnight-ride)
Computes the virtualization memory overhead of a host.
blob ref
create_new_blob
(session ref, host ref, string, string, bool)
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
void
declare_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
void
destroy
(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
void
disable
(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.
enum host_display
disable_display
(session ref, host ref)
Disable console output to the physical display device next time this host boots
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
Minimum role: pool-operator
Result: This host's physical display usage
Published in: XenServer 6.5 SP1 (cream)
void
disable_external_auth
(session ref, host ref, (string → string) map)
This call disables external authentication on the local host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host 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 the local host
void
disable_local_storage_caching
(session ref, host ref)
Disable the use of a local SR for caching purposes
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
Minimum role: pool-operator
Published in: XenServer 5.6 FP1 (cowley)
Disable the use of a local SR for caching purposes
string
dmesg
(session ref, host ref)
Get the host xen dmesg.
Parameters: session ref session_id
Reference to a valid session
host ref host
The Host to query
Minimum role: pool-operator
Result: dmesg string
Published in: XenServer 4.0 (rio)
Get the host xen dmesg.
string
dmesg_clear
(session ref, host ref)
Get the host xen dmesg, and clear the buffer.
Parameters: session ref session_id
Reference to a valid session
host ref host
The Host to query
Minimum role: pool-operator
Result: dmesg string
Published in: XenServer 4.0 (rio)
Get the host xen dmesg, and clear the buffer.
Prototype
void
emergency_clear_mandatory_guidance
(session ref)
Clear the pending mandatory guidance on this host
Parameters: session ref session_id
Reference to a valid session
Minimum role:
Prototyped in: XAPI 24.10.0 (24.10.0)
void
emergency_disable_tls_verification
(session ref)
Disable TLS verification for this host only
Parameters: session ref session_id
Reference to a valid session
Minimum role:
Published in: XAPI 1.290.0 (1.290.0)
void
emergency_ha_disable
(session ref, bool)
This call disables HA on the local host. This should only be used with extreme care.
Parameters: session ref session_id
Reference to a valid session
bool soft
Disable HA temporarily, revert upon host reboot or further changes, idempotent
Minimum role: pool-operator
Published in: XenServer 5.0 (orlando)
This call disables HA on the local host. This should only be used with extreme care.
void
emergency_reenable_tls_verification
(session ref)
Reenable TLS verification for this host only
Parameters: session ref session_id
Reference to a valid session
Minimum role:
Published in: XAPI 1.298.0 (1.298.0)
void
emergency_reset_server_certificate
(session ref)
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
Minimum role:
Published in: Citrix Hypervisor 8.2 (stockholm)
void
enable
(session ref, host ref)
Puts the host into a state in which new VMs can be started.
Parameters: session ref session_id
Reference to a valid session
host ref host
The Host to enable
Minimum role: client-cert
Published in: XenServer 4.0 (rio)
Puts the host into a state in which new VMs can be started.
enum host_display
enable_display
(session ref, host ref)
Enable console output to the physical display device next time this host boots
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
Minimum role: pool-operator
Result: This host's physical display usage
Published in: XenServer 6.5 SP1 (cream)
void
enable_external_auth
(session ref, host ref, (string → string) map, string, string)
This call enables external authentication on a host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host 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 a host
void
enable_local_storage_caching
(session ref, host ref, SR ref)
Enable the use of a local SR for caching purposes
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
SR ref sr
The SR to use as a local cache
Minimum role: pool-operator
Published in: XenServer 5.6 FP1 (cowley)
Enable the use of a local SR for caching purposes
void
evacuate
(session ref, host ref, network ref, int)
Migrate all VMs off of this host, where possible.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host to evacuate
network ref network
Optional preferred network for migration
int evacuate_batch_size
The maximum number of VMs to be migrated per batch 0 will use the value `evacuation-batch-size` defined in xapi.conf
Minimum role: client-cert
Published in: XenServer 4.1 (miami)
Extended in: XAPI 1.297.0 (1.297.0)
Enable migration network selection.
Extended in: XAPI 23.27.0 (23.27.0)
Choose batch size of VM evacuation.
void
forget_data_source_archives
(session ref, host ref, string)
Forget the recorded statistics related to the specified data source
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string data_source
The data source whose archives are to be forgotten
Minimum role: pool-operator
Published in: XenServer 5.0 (orlando)
Forget the recorded statistics related to the specified data source
int
get_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
int
get_API_version_minor
(session ref, host ref)
Get the API_version/minor 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)
minor version number
string
get_API_version_vendor
(session ref, host ref)
Get the API_version/vendor 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)
identification of vendor
(string → string) map
get_API_version_vendor_implementation
(session ref, host ref)
Get the API_version/vendor_implementation 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)
details of vendor implementation
PBD ref set
get_PBDs
(session ref, host ref)
Get the PBDs 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)
physical blockdevices
PCI ref set
get_PCIs
(session ref, host ref)
Get the PCIs 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 6.0 (boston)
PGPU ref set
get_PGPUs
(session ref, host ref)
Get the PGPUs 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 6.0 (boston)
PIF ref set
get_PIFs
(session ref, host ref)
Get the PIFs 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)
physical network interfaces
PUSB ref set
get_PUSBs
(session ref, host ref)
Get the PUSBs 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 7.3 (inverness)
string
get_address
(session ref, host ref)
Get the address 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 address by which this host can be contacted from any other host in the pool
host ref set
get_all
(session ref)
Return a list of all the hosts 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 host
(host ref → host record) map
get_all_records
(session ref)
Return a map of host references to host records for all hosts 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 host
enum host_allowed_operations set
get_allowed_operations
(session ref, host ref)
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.
(string → string) map
get_bios_strings
(session ref, host ref)
Get the bios_strings 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 5.6 (midnight-ride)
BIOS strings
(string → blob ref) map
get_blobs
(session ref, host ref)
Get the blobs 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 5.0 (orlando)
Binary blobs associated with this host
host ref set
get_by_name_label
(session ref, string)
Get all the host 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 physical host
host ref
get_by_uuid
(session ref, string)
Get a reference to the host 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 host
string set
get_capabilities
(session ref, host ref)
Get the capabilities 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)
Xen capabilities
Certificate ref set
get_certificates
(session ref, host ref)
Get the certificates 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: Citrix Hypervisor 8.2 (stockholm)
(string → string) map
get_chipset_info
(session ref, host ref)
Get the chipset_info 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 6.0 (boston)
VM ref
get_control_domain
(session ref, host ref)
Get the control_domain 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 7.1 (ely)
The control domain (domain 0)
(string → string) map
get_cpu_configuration
(session ref, host ref)
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"
(string → string) map
get_cpu_info
(session ref, host ref)
Get the cpu_info 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 5.6 (midnight-ride)
Details about the physical CPUs on this host
SR ref
get_crash_dump_sr
(session ref, host ref)
Get the crash_dump_sr 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 SR in which VDIs for crash dumps are created
host_crashdump ref set
get_crashdumps
(session ref, host ref)
Get the crashdumps 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)
Set of host crash dumps
(string → enum host_allowed_operations) map
get_current_operations
(session ref, host ref)
Get the current_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)
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 set
get_data_sources
(session ref, host ref)
Parameters: session ref session_id
Reference to a valid session
host ref host
The host to interrogate
Minimum role: read-only
Result: A set of data sources
Published in: XenServer 5.0 (orlando)
enum host_display
get_display
(session ref, host ref)
Get the display 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 6.5 SP1 (cream)
indicates whether the host is configured to output its console to a physical display device
string
get_edition
(session ref, host ref)
Get the edition 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 5.6 (midnight-ride)
Product edition
string set
get_editions
(session ref, host ref)
Get the editions 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: Citrix Hypervisor 8.2 (stockholm)
bool
get_enabled
(session ref, host ref)
Get the enabled 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)
True if the host is currently enabled
(string → string) map
get_external_auth_configuration
(session ref, host ref)
Get the external_auth_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 5.5 (george)
configuration specific to external authentication service
string
get_external_auth_service_name
(session ref, host ref)
Get the external_auth_service_name 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 5.5 (george)
name of external authentication service configured; empty if none configured.
string
get_external_auth_type
(session ref, host ref)
Get the external_auth_type 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 5.5 (george)
type of external authentication service configured; empty if none configured.
Feature ref set
get_features
(session ref, host ref)
Get the features 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 7.2 (falcon)
(string → string) map
get_guest_VCPUs_params
(session ref, host ref)
Get the guest_VCPUs_params 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 6.1 (tampa)
VCPUs params to apply to all resident guests
string set
get_ha_network_peers
(session ref, host ref)
Get the ha_network_peers 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 5.0 (orlando)
The set of hosts visible via the network from this host
string set
get_ha_statefiles
(session ref, host ref)
Get the ha_statefiles 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 5.0 (orlando)
The set of statefiles accessible from this host
host_cpu ref set
get_host_CPUs
(session ref, host ref)
Get the host_CPUs 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 physical CPUs on this host
string
get_hostname
(session ref, host ref)
Get the hostname 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 hostname of this host
Prototype
bool
get_https_only
(session ref, host ref)
Get the https_only 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
Prototyped in: XAPI 22.27.0 (22.27.0)
string
get_iscsi_iqn
(session ref, host ref)
Get the iscsi_iqn 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 7.5 (kolkata)
Prototype
datetime
get_last_software_update
(session ref, host ref)
Get the last_software_update 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
Prototyped in: XAPI 22.20.0 (22.20.0)
Prototype
string
get_last_update_hash
(session ref, host ref)
Get the last_update_hash 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
Prototyped in: XAPI 24.10.0 (24.10.0)
Prototype
enum latest_synced_updates_applied_state
get_latest_synced_updates_applied
(session ref, host ref)
Get the latest_synced_updates_applied 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
Prototyped in: XAPI 23.18.0 (23.18.0)
(string → string) map
get_license_params
(session ref, host ref)
Get the license_params 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)
State of the current license
(string → string) map
get_license_server
(session ref, host ref)
Get the license_server 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 5.6 (midnight-ride)
Contact information of the license server
SR ref
get_local_cache_sr
(session ref, host ref)
Get the local_cache_sr 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 5.6 FP1 (cowley)
The SR that is used as a local cache
string
get_log
(session ref, host ref)
Get the host's log file
Parameters: session ref session_id
Reference to a valid session
host ref host
The Host to query
Minimum role: read-only
Result: The contents of the host's primary log file
Published in: XenServer 4.0 (rio)
Get the host's log file
(string → string) map
get_logging
(session ref, host ref)
Get the logging 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)
logging configuration
PIF ref
get_management_interface
(session ref, host ref)
Returns the management interface for the specified host
Parameters: session ref session_id
Reference to a valid session
host ref host
Which host's management interface is required
Minimum role: pool-operator
Result: The management interface for the host
Published in: XenServer 6.1 (tampa)
int
get_memory_overhead
(session ref, host ref)
Get the memory/overhead 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)
Virtualization memory overhead (bytes).
host_metrics ref
get_metrics
(session ref, host ref)
Get the metrics 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)
metrics associated with this host
bool
get_multipathing
(session ref, host ref)
Get the multipathing 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 7.5 (kolkata)
string
get_name_description
(session ref, host ref)
Get the name/description 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)
string
get_name_label
(session ref, host ref)
Get the name/label 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)
Prototype
enum host_numa_affinity_policy
get_numa_affinity_policy
(session ref, host ref)
Get the numa_affinity_policy 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
Prototyped in: XAPI 24.0.0 (24.0.0)
(string → string) map
get_other_config
(session ref, host ref)
Get the other_config 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)
additional configuration
Deprecated
host_patch ref set
get_patches
(session ref, host ref)
Get the patches 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)
Set of host patches
Deprecated in: XenServer 7.1 (ely)
enum update_guidances set
get_pending_guidances
(session ref, host ref)
Get the pending_guidances 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: 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 set
get_pending_guidances_full
(session ref, host ref)
Get the pending_guidances_full 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
Prototyped in: XAPI 24.10.0 (24.10.0)
Prototype
enum update_guidances set
get_pending_guidances_recommended
(session ref, host ref)
Get the pending_guidances_recommended 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
Prototyped in: XAPI 24.10.0 (24.10.0)
(string → string) map
get_power_on_config
(session ref, host ref)
Get the power_on_config 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 5.6 (midnight-ride)
The power on config
string
get_power_on_mode
(session ref, host ref)
Get the power_on_mode 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 5.6 (midnight-ride)
The power on mode
host record
get_record
(session ref, host ref)
Get a record containing the current state 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: all fields from the object
Published in: XenServer 4.0 (rio)
A physical host
VM ref set
get_resident_VMs
(session ref, host ref)
Get the resident_VMs 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 VMs currently resident on host
enum host_sched_gran
get_sched_gran
(session ref, host ref)
Gets xen's sched-gran on a host
Parameters: session ref session_id
Reference to a valid session
host ref self
The host
Minimum role:
Result: The host's sched-gran
Published in: XAPI 1.271.0 (1.271.0)
string
get_sched_policy
(session ref, host ref)
Get the sched_policy 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)
Scheduler policy currently in force on this host
string
get_server_certificate
(session ref, host ref)
Get the installed server public TLS certificate.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
Minimum role: read-only
Result: The installed server public TLS certificate, in PEM form.
Published in: XenServer 5.5 (george)
Changed in: XenServer 7.3 (inverness)
Now available to all RBAC roles.
datetime
get_server_localtime
(session ref, host ref)
This call queries the host's clock for the current time in the host's local timezone
Parameters: session ref session_id
Reference to a valid session
host ref host
The host whose clock should be queried
Minimum role: read-only
Result: The current local time
Published in: XenServer 5.6 FP1 (cowley)
This call queries the host's clock for the current time in the host's local timezone
datetime
get_servertime
(session ref, host ref)
This call queries the host's clock for the current time
Parameters: session ref session_id
Reference to a valid session
host ref host
The host whose clock should be queried
Minimum role: read-only
Result: The current time
Published in: XenServer 5.0 (orlando)
This call queries the host's clock for the current time
(string → string) map
get_software_version
(session ref, host ref)
Get the software_version 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)
version strings
Deprecated
bool
get_ssl_legacy
(session ref, host ref)
Get the ssl_legacy 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 7.0 (dundee)
Deprecated in: Citrix Hypervisor 8.2 (stockholm)
Legacy SSL no longer supported
string set
get_supported_bootloaders
(session ref, host ref)
Get the supported_bootloaders 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)
a list of the bootloaders installed on the machine
SR ref
get_suspend_image_sr
(session ref, host ref)
Get 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
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
get_system_status_capabilities
(session ref, host ref)
Parameters: session ref session_id
Reference to a valid session
host ref host
The host to interrogate
Minimum role: read-only
Result: An XML fragment containing the system status capabilities.
Published in: XenServer 4.1 (miami)
string set
get_tags
(session ref, host ref)
bool
get_tls_verification_enabled
(session ref, host ref)
Get the tls_verification_enabled 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: XAPI 1.313.0 (1.313.0)
True if this host has TLS verifcation enabled
Deprecated
string
get_uefi_certificates
(session ref, host ref)
Get the uefi_certificates 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: Citrix Hypervisor 8.1 (quebec)
Deprecated in: XAPI 22.16.0 (22.16.0)
Use Pool.uefi_certificates instead
Deprecated
VM ref set
get_uncooperative_resident_VMs
(session ref, host ref)
Return a set of VMs which are not co-operating with the host's memory control system
Parameters: session ref session_id
Reference to a valid session
host ref self
The host to query
Minimum role: read-only
Result: VMs which are not co-operating
Published in: XenServer 5.6 (midnight-ride)
Return a set of VMs which are not co-operating with the host's memory control system
Deprecated in: XenServer 6.1 (tampa)
pool_update ref set
get_updates
(session ref, host ref)
Get the updates 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 7.1 (ely)
Set of updates
pool_update ref set
get_updates_requiring_reboot
(session ref, host ref)
Get the updates_requiring_reboot 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 7.1 (ely)
string
get_uuid
(session ref, host ref)
Get the uuid 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)
Unique identifier/object reference
int set
get_virtual_hardware_platform_versions
(session ref, host ref)
(VM ref → string set) map
get_vms_which_prevent_evacuation
(session ref, host ref)
Return a set of VMs which prevent the host being evacuated, with per-VM error codes
Parameters: session ref session_id
Reference to a valid session
host ref self
The host to query
Minimum role: read-only
Result: VMs which block evacuation together with reasons
Published in: XenServer 5.0 (orlando)
Return a set of VMs which prevent the host being evacuated, with per-VM error codes
bool
has_extension
(session ref, host ref, string)
Return true if the extension is available on the host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string name
The name of the API call
Minimum role: pool-admin
Result: True if the extension exists, false otherwise
Published in: XenServer 7.1 (ely)
Return true if the extension is available on the host
void
install_server_certificate
(session ref, host ref, string, string, string)
Install the TLS server certificate.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string certificate
The server certificate, in PEM form
string private_key
The unencrypted private key used to sign the certificate, in PKCS#8 form
string certificate_chain
The certificate chain, in PEM form
Minimum role: pool-admin
Published in: Citrix Hypervisor 8.2 (stockholm)
void
license_add
(session ref, host ref, string)
Apply a new license to a host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host to upload the license to
string contents
The contents of the license file, base64 encoded
Minimum role: pool-operator
Errors: LICENSE_PROCESSING_ERROR
There was an error processing your license. Please contact your support representative.
Published in: XenServer 6.5 SP1 Hotfix 31 (indigo)
Functionality for parsing license files re-added
Removed
void
license_apply
(session ref, host ref, string)
Apply a new license to a host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host to upload the license to
string contents
The contents of the license file, base64 encoded
Minimum role: pool-operator
Errors: LICENSE_PROCESSING_ERROR
There was an error processing your license. Please contact your support representative.
Published in: XenServer 4.0 (rio)
Apply a new license to a host
Deprecated in: XenServer 6.2 (clearwater)
Dummy transition
Removed in: XenServer 6.2 (clearwater)
Free licenses no longer handled by xapi
void
license_remove
(session ref, host ref)
Remove any license file from the specified host, and switch that host to the unlicensed edition
Parameters: session ref session_id
Reference to a valid session
host ref host
The host from which any license will be removed
Minimum role: pool-operator
Published in: XenServer 6.5 SP1 Hotfix 31 (indigo)
string set
list_methods
(session ref)
List all supported methods
Parameters: session ref session_id
Reference to a valid session
Minimum role: read-only
Result: The name of every supported method.
Published in: XenServer 4.0 (rio)
List all supported methods
void
local_management_reconfigure
(session ref, string)
void
management_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
void
management_reconfigure
(session ref, PIF ref)
(string → string) map
migrate_receive
(session ref, host ref, network ref, (string → string) map)
Prepare to receive a VM, returning a token which can be passed to VM.migrate.
Parameters: session ref session_id
Reference to a valid session
host ref host
The target host
network ref network
The network through which migration traffic should be received.
(string → string) map options
Extra configuration operations
Minimum role: vm-power-admin
Result: A value which should be passed to VM.migrate
Published in: XenServer 6.1 (tampa)
Prepare to receive a VM, returning a token which can be passed to VM.migrate.
void
power_on
(session ref, host ref)
Attempt to power-on the host (if the capability exists).
Parameters: session ref session_id
Reference to a valid session
host ref host
The Host to power on
Minimum role: pool-operator
Published in: XenServer 5.0 (orlando)
Attempt to power-on the host (if the capability exists).
float
query_data_source
(session ref, host ref, string)
Query the latest value of the specified data source
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
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
void
reboot
(session ref, host ref)
Reboot 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 reboot
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
Reboot the host. (This function can only be called if there are no currently running VMs on the host and it is disabled.)
void
record_data_source
(session ref, host ref, string)
Start recording the specified data source
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string data_source
The data source to record
Minimum role: pool-operator
Published in: XenServer 5.0 (orlando)
Start recording the specified data source
Deprecated
void
refresh_pack_info
(session ref, host ref)
Refresh the list of installed Supplemental Packs.
Parameters: session ref session_id
Reference to a valid session
host ref host
The Host to modify
Minimum role: pool-operator
Published in: XenServer 5.6 (midnight-ride)
Deprecated in: XenServer 7.1 (ely)
Use Pool_update.resync_host instead
void
refresh_server_certificate
(session ref, host ref)
Replace the internal self-signed host certficate with a new one.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
Minimum role: pool-admin
Published in: XAPI 1.307.0 (1.307.0)
void
remove_from_guest_VCPUs_params
(session ref, host ref, string)
Remove the given key and its corresponding value from the guest_VCPUs_params field of the given host. If the key is not in that Map, then do nothing.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string key
Key to remove
Minimum role: pool-operator
Published in: XenServer 6.1 (tampa)
VCPUs params to apply to all resident guests
void
remove_from_license_server
(session ref, host ref, string)
Remove the given key and its corresponding value from the license_server field of the given host. If the key is not in that Map, then do nothing.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string key
Key to remove
Minimum role: pool-operator
Published in: XenServer 5.6 (midnight-ride)
Contact information of the license server
void
remove_from_logging
(session ref, host ref, string)
Remove the given key and its corresponding value from the logging field of the given host. If the key is not in that Map, then do nothing.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string key
Key to remove
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
logging configuration
void
remove_from_other_config
(session ref, host ref, string)
Remove the given key and its corresponding value from the other_config field of the given host. If the key is not in that Map, then do nothing.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string key
Key to remove
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
additional configuration
void
remove_tags
(session ref, host ref, string)
Removed
void
reset_cpu_features
(session ref, host ref)
Remove the feature mask, such that after a reboot all features of the CPU are enabled.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
Minimum role: pool-operator
Published in: XenServer 5.6 (midnight-ride)
Deprecated in: XenServer 7.0 (dundee)
Dummy transition
Removed in: XenServer 7.0 (dundee)
Manual CPU feature setting was removed
void
reset_server_certificate
(session ref, host ref)
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)
void
restart_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.
(VM ref → string set) map
retrieve_wlb_evacuate_recommendations
(session ref, host ref)
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.
void
send_debug_keys
(session ref, host ref, string)
Inject the given string as debugging keys into Xen
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string keys
The keys to send
Minimum role: pool-admin
Published in: XenServer 4.0 (rio)
Inject the given string as debugging keys into Xen
void
set_address
(session ref, host ref, string)
Set the address field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string value
New value to set
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
The address by which this host can be contacted from any other host in the pool
Removed
void
set_cpu_features
(session ref, host ref, string)
Set the CPU features to be used after a reboot, if the given features string is valid.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string features
The features string (32 hexadecimal digits)
Minimum role: pool-operator
Published in: XenServer 5.6 (midnight-ride)
Deprecated in: XenServer 7.0 (dundee)
Dummy transition
Removed in: XenServer 7.0 (dundee)
Manual CPU feature setting was removed
void
set_crash_dump_sr
(session ref, host ref, SR ref)
Set the crash_dump_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 crash dumps are created
void
set_display
(session ref, host ref, enum host_display)
Set the display field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
enum host_display value
New value to set
Minimum role: pool-operator
Published in: XenServer 6.5 SP1 (cream)
indicates whether the host is configured to output its console to a physical display device
void
set_guest_VCPUs_params
(session ref, host ref, (string → string) map)
Set the guest_VCPUs_params field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
(string → string) map value
New value to set
Minimum role: pool-operator
Published in: XenServer 6.1 (tampa)
VCPUs params to apply to all resident guests
void
set_hostname
(session ref, host ref, string)
Set the hostname field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string value
New value to set
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
The hostname of this host
void
set_hostname_live
(session ref, host ref, string)
Sets the host name to the specified string. Both the API and lower-level system hostname are changed immediately.
Parameters: session ref session_id
Reference to a valid session
host ref host
The host whose host name to set
string hostname
The new host name
Minimum role: pool-operator
Errors: HOST_NAME_INVALID
The server name is invalid.
Published in: XenServer 4.1 (miami)
Sets the host name to the specified string. Both the API and lower-level system hostname are changed immediately.
Prototype
void
set_https_only
(session ref, host ref, bool)
updates the host firewall to open or close port 80 depending on the value
Parameters: session ref session_id
Reference to a valid session
host ref self
The Host
bool value
true - http port 80 will be blocked, false - http port 80 will be open
Minimum role: pool-operator
Prototyped in: XAPI 22.27.0 (22.27.0)
void
set_iscsi_iqn
(session ref, host ref, string)
Sets the initiator IQN for the host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string value
The value to which the IQN should be set
Minimum role: pool-operator
Published in: XenServer 7.5 (kolkata)
void
set_license_server
(session ref, host ref, (string → string) map)
Set the license_server field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
(string → string) map value
New value to set
Minimum role: pool-operator
Published in: XenServer 5.6 (midnight-ride)
Contact information of the license server
void
set_logging
(session ref, host ref, (string → string) map)
Set the logging field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
(string → string) map value
New value to set
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
logging configuration
void
set_multipathing
(session ref, host ref, bool)
Specifies whether multipathing is enabled
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
bool value
Whether multipathing should be enabled
Minimum role: pool-operator
Published in: XenServer 7.5 (kolkata)
void
set_name_description
(session ref, host ref, string)
Set the name/description field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string value
New value to set
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
void
set_name_label
(session ref, host ref, string)
Set the name/label field of the given host.
Parameters: session ref session_id
Reference to a valid session
host ref self
reference to the object
string value
New value to set
Minimum role: pool-operator
Published in: XenServer 4.0 (rio)
Prototype
void
set_numa_affinity_policy
(session ref, host ref, enum host_numa_affinity_policy)
Set VM placement NUMA affinity policy
Parameters: session ref session_id
Reference to a valid session
host ref self
The host
enum host_numa_affinity_policy value
The NUMA affinity policy to apply to a host
Minimum role: pool-admin
Prototyped in: XAPI 24.0.0 (24.0.0)
void
set_other_config
(session ref, host ref, (string → string) map)
Set the other_config field of the given host.
Parameters: session ref session_id
Reference to a valid session
host 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
void
set_power_on_mode
(session ref, host ref, string, (string → string) map)
Set the power-on-mode, host, user and password
Parameters: session ref session_id
Reference to a valid session
host ref self
The host
string power_on_mode
power-on-mode can be empty, wake-on-lan, IPMI or other
(string → string) map power_on_config
Power on config
Minimum role: pool-operator
Published in: XenServer 5.6 FP1 (cowley)
Changed in: Citrix Hypervisor 8.2 (stockholm)
Removed iLO script
Changed in: XAPI 24.19.0 (24.19.0)
Replaced DRAC mode with IPMI
void
set_sched_gran
(session ref, host ref, enum host_sched_gran)
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)
void
set_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
void
set_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
void
set_tags
(session ref, host ref, string set)
Deprecated
void
set_uefi_certificates
(session ref, host ref, string)
Sets the UEFI certificates on a host
Parameters: session ref session_id
Reference to a valid session
host ref host
The host
string value
The certificates to apply to a host
Minimum role:
Published in: Citrix Hypervisor 8.1 (quebec)
Deprecated in: XAPI 22.16.0 (22.16.0)
Use Pool.set_uefi_certificates instead
void
shutdown
(session ref, host ref)
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.)
void
shutdown_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.
void
sync_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
void
syslog_reconfigure
(session ref, host ref)
