Develop for XenServer

XenServer Management API extensions

June 18, 2024

Contributed by:

The Management API is a general and comprehensive interface to managing the life-cycles of virtual machines, and offers a lot of flexibility in the way that Management API providers may implement specific functionality (for example, storage provisioning, or console handling). XenServer has several extensions which provide useful functionality used in our own XenCenter interface. The workings of these mechanisms are described in this chapter.

Extensions to the Management API are often provided by specifying other-config map keys to various objects. The use of this parameter indicates that the functionality is supported for that particular release of XenServer, but not as a long-term feature. We are constantly evaluating promoting functionality into the API, but this requires the nature of the interface to be well-understood. Developer feedback as to how you are using some of these extensions is always welcome to help us make these decisions.

VM console forwarding

Most Management API graphical interfaces will want to gain access to the VM consoles, in order to render them to the user as if they were physical machines. There are several types of consoles available, depending on the type of guest or if the physical host console is being accessed:

Console access

Operating System	Text	Graphical	Optimized graphical
Windows	No	VNC, using an API call	RDP, directly from guest
Linux	Yes, through VNC and an API call	No	VNC, directly from guest
Physical Host	Yes, through VNC and an API call	No	No

Hardware-assisted VMs, such as Windows, directly provide a graphical console over VNC. There is no text-based console, and guest networking is not necessary to use the graphical console. Once guest networking has been established, it is more efficient to setup Remote Desktop Access and use an RDP client to connect directly (this must be done outside of the Management API).

Paravirtual VMs, such as Linux guests, provide a native text console directly. XenServer provides a utility (called vncterm) to convert this text-based console into a graphical VNC representation. Guest networking is not necessary for this console to function. As with Windows above, Linux distributions often configure VNC within the guest, and directly connect to it over a guest network interface.

The physical host console is only available as a vt100 console, which is exposed through the Management API as a VNC console by using vncterm in the control domain.

RFB (Remote Framebuffer) is the protocol which underlies VNC, specified in The RFB Protocol. Third-party developers are expected to provide their own VNC viewers, and many freely available implementations can be adapted for this purpose. RFB 3.3 is the minimum version which viewers must support.

Retrieving VNC consoles using the API

VNC consoles are retrieved using a special URL passed through to the host agent. The sequence of API calls is as follows:

Client to Master/443: RPC: Session.login_with_password().
Master/443 to Client: Returns a session reference to be used with subsequent calls.
Client to Master/443: RPC: VM.get_by_name_label().
Master/443 to Client: Returns a reference to a particular VM (or the “control domain” if you want to retrieve the physical host console).
Client to Master/443: RPC: VM.get_consoles().
Master/443 to Client: Returns a list of console objects associated with the VM.
Client to Master/443: RPC: VM.get_location().
Returns a URI describing where the requested console is located. The URIs are of the form: https://192.168.0.1/console?ref=OpaqueRef:c038533a-af99-a0ff-9095-c1159f2dc6a0 or https://192.168.0.1/console?uuid=026e34fe-f0f2-20ee-5344-46d1aa922d5b
Client to 192.168.0.1: HTTP CONNECT “/console?ref=(…)”. You will also need to pass in “session_id=<session reference>” as a cookie.

The final HTTP CONNECT is slightly non-standard since the HTTP/1.1 RFC specifies that it must only be a host and a port, rather than a URL. Once the HTTP connect is complete, the connection can subsequently directly be used as a VNC server without any further HTTP protocol action.

This scheme requires direct access from the client to the control domain’s IP, and will not work correctly if there are Network Address Translation (NAT) devices blocking such connectivity. You can use the CLI to retrieve the console URI from the client and perform a connectivity check.

Retrieve the VM UUID by running:

    xe vm-list params=uuid --minimal name-label=name
<!--NeedCopy-->

Retrieve the console information:

    xe console-list vm-uuid=uuid
    uuid ( RO): 714f388b-31ed-67cb-617b-0276e35155ef
    vm-uuid ( RO): 8acb7723-a5f0-5fc5-cd53-9f1e3a7d3069
    vm-name-label ( RO): etch
    protocol ( RO): RFB
    location ( RO): https://192.168.0.1/console?ref=(...)
<!--NeedCopy-->

Use command-line utilities like ping to test connectivity to the IP address provided in the location field.

Disabling VNC forwarding for Linux VM

When creating and destroying Linux VMs, the host agent automatically manages the vncterm processes which convert the text console into VNC. Advanced users who want to directly access the text console can disable VNC forwarding for that VM. The text console can then only be accessed directly from the control domain directly, and graphical interfaces such as XenCenter will not be able to render a console for that VM.

Before starting the guest, set the following parameter on the VM record:

xe vm-param-set uuid=uuid other-config:disable_pv_vnc=1

Start the VM.

Use the CLI to retrieve the underlying domain ID of the VM with:

xe vm-list params=dom-id uuid=uuid --minimal

On the host console, connect to the text console directly by:

/usr/lib/xen/bin/xenconsole domain_id

This configuration is an advanced procedure, and we do not recommend that the text console is directly used for heavy I/O operations. Instead, connect to the guest over SSH or some other network-based connection mechanism.

Adding xenstore entries to VMs

Developers might want to install guest agents into VMs which take special action based on the type of the VM. In order to communicate this information into the guest, a special xenstore name-space known as vm-data is available which is populated at VM creation time. It is populated from the xenstore-data map in the VM record.

Set the xenstore-data parameter in the VM record:

xe vm-param-set uuid=vm_uuid xenstore-data:vm-data/foo=bar

Start the VM.

If it is a Linux-based VM, install the XenServer VM Tools and use the command xenstore-read to verify that the node exists in xenstore.

Note:

Only prefixes beginning with vm-data are permitted, and anything not in this name-space will be silently ignored when starting the VM.

Security enhancements

The control domain in XenServer has various security enhancements in order to harden it against attack from malicious guests. These changes do not result in any loss of correct functionality, but the changes are documented here as variations of behavior from other distributions.

The socket interface, xenstored, access using libxenstore. Interfaces are restricted by xs_restrict().
The device /dev/xen/evtchn, which is accessed by calling xs_evtchn_open() in libxenctrl. A handle can be restricted using xs_evtchn_restrict().
The device /proc/xen/privcmd, accessed through xs_interface_open() in libxenctrl. A handle is restricted using xc_interface_restrict(). Some privileged commands are naturally hard to restrict (for example, the ability to make arbitrary hypercalls), and these are simply prohibited on restricted handles.
A restricted handle cannot later be granted more privilege, and so the interface must be closed and re-opened. Security is only gained if the process cannot subsequently open more handles.

The control domain privileged user-space interfaces can now be restricted to only work for certain domains. There are three interfaces affected by this change:

The qemu device emulation processes and vncterm terminal emulation processes run as a non-root user ID and are restricted into an empty directory. They uses the restriction API above to drop privileges where possible.
Access to xenstore is rate-limited to prevent malicious guests from causing a denial of service on the control domain. This is implemented as a token bucket with a restricted fill-rate, where most operations take one token and opening a transaction takes 20. The limits are set high enough that they are never hit when running even a large number of concurrent guests under loaded operation.
The VNC guest consoles are bound only to the localhost interface, so that they are not exposed externally even if the control domain packet filter is disabled by user intervention.

Advanced settings for network interfaces

Virtual and physical network interfaces have some advanced settings that can be configured using the other-config map parameter. There is a set of custom ethtool settings and some miscellaneous settings.

ethtool settings

Developers might want to configure custom ethtool settings for physical and virtual network interfaces. This is accomplished with ethtool-<option> keys in the other-config map parameter.

Key	Description	Valid settings
ethtool-rx	Specify if RX checksumming is enabled	`on` or `true` to enable the setting, `off` or `false` to disable it
ethtool-tx	Specify if TX checksumming is enabled	`on` or `true` to enable the setting, `off` or `false` to disable it
ethtool-sg	Specify if scatter-gather is enabled	`on` or `true` to enable the setting, `off` or `false` to disable it
ethtool-tso	Specify if tcp segmentation offload is enabled	`on` or `true` to enable the setting, `off` or `false` to disable it
ethtool-ufo	Specify if UDP fragmentation offload is enabled	`on` or `true` to enable the setting, `off` or `false` to disable it
ethtool-gso	Specify if generic segmentation offload is enabled	`on` or `true` to enable the setting, `off` or `false` to disable it
ethtool-autoneg	Specify if autonegotiation is enabled	`on` or `true` to enable the setting, `off` or `false` to disable it
ethtool-speed	Set the device speed in Mb/s	10, 100, or 1000
ethtool-duplex	Set full or half duplex mode	half or full

For example, to enable TX checksumming on a virtual NIC using the xe CLI:

xe vif-param-set uuid=<VIF UUID> other-config:ethtool-tx="on"

or:

xe vif-param-set uuid=<VIF UUID> other-config:ethtool-tx="true"

To set the duplex setting on a physical NIC to half duplex using the xe CLI:

xe vif-param-set uuid=<VIF UUID> other-config:ethtool-duplex="half"

Miscellaneous settings

You can also set a promiscuous mode on a VIF or PIF by setting the promiscuous key to on. For example, to enable promiscuous mode on a physical NIC using the xe CLI:

xe pif-param-set uuid=<PIF UUID> other-config:promiscuous="on"

or:

xe pif-param-set uuid=<PIF UUID> other-config:promiscuous="true"

The VIF and PIF objects have a MTU parameter that is read-only and provide the current setting of the maximum transmission unit for the interface. You can override the default maximum transmission unit of a physical or virtual NIC with the mtu key in the other-config map parameter. For example, to reset the MTU on a virtual NIC to use jumbo frames using the xe CLI:

xe vif-param-set uuid=<VIF UUID> other-config:mtu=9000

Note that changing the MTU of underlying interfaces is an advanced and experimental feature, and may lead to unexpected side-effects if you have varying MTUs across NICs in a single resource pool.

The SRs created at install time now have an other_config key indicating how their names may be internationalized.

other_config["i18n-key"] may be one of

local-hotplug-cd
local-hotplug-disk
local-storage
XenServer-tools

Additionally, other_config["i18n-original-value-<field name>"] gives the value of that field when the SR was created. If XenCenter sees a record where SR.name_label equals other_config["i18n-original-value-name_label"] (that is, the record has not changed since it was created during XenServer installation), then internationalization will be applied. In other words, XenCenter will disregard the current contents of that field, and instead use a value appropriate to the user’s own language.

If you change SR.name_label for your own purpose, then it no longer is the same as other_config["i18n-original-value-name_label"]. Therefore, XenCenter does not apply internationalization, and instead preserves your given name.

Hiding objects from XenCenter

Networks, PIFs, and VMs can be hidden from XenCenter by adding the key HideFromXenCenter=true to the other_config parameter for the object. This capability is intended for ISVs who know what they are doing, not general use by everyday users. For example, you might want to hide certain VMs because they are cloned VMs that are not intended to be used directly by general users in your environment.

In XenCenter, hidden Networks, PIFs, and VMs can be made visible, using the View menu.

Other extensions

The following section details the assumptions and API extensions that we have made, over and above the documented API. Extensions are encoded as particular key-value pairs in dictionaries such as VM.other_config.

Pool

Key	Semantics
pool.other_config[“rolling_upgrade_in_progress”]	Present if the pool is in the middle of a rolling upgrade.

Host

Key	Semantics
host.other_config[“iscsi_iqn”]	The host’s iSCSI IQN.
host.license_params[“expiry”]	The expiry date of the host’s license, in ISO 8601, UTC.
host.license_params[“sku_type”]	The host license type i.e. Server or Enterprise.
host.license_params[“restrict_pooling”]	Returns `true` if pooling is restricted by the host.
host.license_params[“restrict_connection”]	The number of connections that can be made from XenCenter is restricted.
host.license_params[“restrict_qos”]	Returns `true` if Quality of Service settings are enabled on the host.
host.license_params[“restrict_vlan”]	Returns `true` if creation of virtual networks is restricted on the host.
host.license_params[“restrict_pool_attached_storage”]	Returns `true` if the creation of shared storage is restricted on this host.
host.software_version[“product_version”]	Returns the host’s product version.
host.software_version[“build_number”]	Returns the host’s build number.
host.software_version[“xapi”]	Returns the host’s api revision number.
host.software_version[“package-linux”]	Returns “installed” if the Linux pack has been installed.
host.software_version[“oem_build_number”]	If the host is the OEM version, return its revision number.
host.logging[“syslog_destination”]	Gets or sets the destination for the XenServer system logger (null for local logging).
host.logging[“multipathing”]	“true” if storage multipathing is enabled on this host.
host.logging[“boot_time”]	A floating point Unix time giving the time that the host booted.
host.logging[“agent_start_time”]	A floating point Unix time giving the time that the control domain management daemon started.

VM

Key	Semantics
VM.other_config[“default_template”]	This template is one that was installed by . This is used to selectively hide these in the tree view, to use a different icon for them, and to disallow deletion.
VM.other_config[“xensource_internal”]	This template is special, such as the P2V server template. These are completely hidden by the UI.
VM.other_config[“install_distro”] == “rhlike”	This template is for RHEL 5, or CentOS equivalents. This is used to prompt for the Install Repository during install, including support for install from ISO / CD, and to modify NFS URLs to suit these installers.
VM.other_config[“install-repository”] == “cdrom”	Requests an install from a repository in the VM’s attached CD drive, rather than a URL.
VM.other_config[“auto_poweron”]	Gets or sets whether the VM starts when the server boots, “true” or “false”.
VM.other_config[“ignore_excessive_vcpus”]	Gets or sets to ignore XenCenter warning if a VM has more VCPUs than its host has physical CPUs, `true` to ignore.
VM.other_config[“HideFromXenCenter”]	Gets or sets whether XenCenter will show the VM in the treeview, “true” to hide.
VM.other_config[“import_task”]	Gets the import task that created this VM.
VM.HVM_boot_params[“order”]	Gets or sets the VM’s boot order on HVM VM’s only, for example, “CDN” will boot in the following order - First boot disk, CD drive, Network.
VM.VCPU_params[“weight”]	Gets or sets the IONice value for the VM’s VCPUs, ranges from 1 to 65536, 65536 being the highest.
VM.pool_migrate(…, options[‘live’])	`true` indicates live migration. XenCenter always uses this.
VM.other_config[“install-methods”]	A comma-separated list of install methods available for this template. Can include “cdrom”, “nfs”, “http” or “ftp”.
VM.other_config[“last_shutdown_time”]	The time that this VM was last shut down or rebooted, formatted as a UTC ISO8601 datetime.
VM.other_config[“p2v_source_machine”]	The source machine, if this VM was imported by a P2V process.
VM.other_config[“p2v_import_date”]	The date the VM was imported, if it was imported by a P2V process. Formatted as a UTC ISO8601 datetime.

SR

Key	Semantics
SR.other_config[“auto-scan”]	The SR will be automatically scanned for changes. Set on all SRs created by XenCenter.
SR.sm_config[“type”]	Set as type `cd` for SRs which are physical CD drives.

VDI

Key	Semantics
VDI.sm_config[“vmhint”]	The UUID of the VM that this VDI supports. This is set when VDIs are created through the user interface, to improve performance for certain storage backends.

VBD

Key	Semantics
VBD.other_config[“owner”]	If set, then this disk may be deleted when the VM is uninstalled.
VBD.other_config[“class”]	Set to an integer, corresponding to the Best Effort setting of `ionice`.

Network

Key	Semantics
network.other_config[“automatic”]	The New VM wizard will create a VIF connected to this network by default, if this key has any value other than `false`.
network.other_config[“import_task”]	Gets the import task that created this network.

VM_guest_metrics

Key	Semantics
PV_drivers_version[“major”]	Gets the major version of the XenServer VM Tools on the VM.
PV_drivers_version[“minor”]	Gets the minor version of the XenServer VM Tools on the VM.
PV_drivers_version[“micro”]	Gets the micro (build number) of the XenServer VM Tools on the VM.

Task

Key	Semantics
task.other_config[“object_creation”] == “complete”	For the task associated with a VM import, this flag will be set when all the objects (VMs, networks) have been created. This is useful in the import VM wizard for us to then go and re-map all the networks that need it.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

XenServer Management API extensions

June 18, 2024

Contributed by:

June 18, 2024

Contributed by:

XenServer Management API extensions

VM console forwarding

Console access

Retrieving VNC consoles using the API

Disabling VNC forwarding for Linux VM

Adding xenstore entries to VMs

Security enhancements

Advanced settings for network interfaces

ethtool settings

Miscellaneous settings

Internationalization for SR names

Hiding objects from XenCenter

Other extensions

Pool

Host

VM

SR

VDI

VBD

Network

VM_guest_metrics

Task

In this article