Chapter 3. Overview of the XenServer API

Table of Contents

3.1.1. Authentication: acquiring a session reference
3.1.2. Acquiring a list of templates to base a new VM installation on
3.1.3. Installing the VM based on a template
3.1.4. Taking the VM through a start/suspend/resume/stop cycle
3.1.5. Logging out
3.1.6. "Install and start example": summary

3.3.1. Creating disks and attaching them to VMs
3.3.2. Creating and attaching Network Devices to VMs
3.3.3. Host configuration for networking and storage

In this chapter we introduce the XenServer API (hereafter referred to as just "the API") and its associated object model. The API has the following key features:

Management of all aspects of XenServer: Through the API one can manage VMs, storage, networking, host configuration and pools. Performance and status metrics can also be queried via the API.
Persistent Object Model: The results of all side-effecting operations (e.g. object creation, deletion and parameter modifications) are persisted in a server-side database that is managed by the XenServer installation.
An event mechanism: Through the API, clients can register to be notified when persistent (server-side) objects are modified. This enables applications to keep track of datamodel modifications performed by concurrently executing clients.
Synchronous and asynchronous invocation: All API calls can be invoked synchronously (i.e. block until completion); any API call that may be long-running can also be invoked asynchronously. Asynchronous calls return immediately with a reference to a task object. This task object can be queried (through the API) for progress and status information. When an asynchronously invoked operation completes, the result (or error code) is available via the task object.
Remotable and Cross-Platform: The client issuing the API calls does not have to be resident on the host being managed; nor does it have to be connected to the host via ssh in order to execute the API. API calls make use of the XML-RPC protocol to transmit requests and responses over the network.
Secure and Authenticated Access: The XML-RPC API server executing on the host accepts secure socket connections. This allows a client to execute the APIs over the https protocol. Further, all the API calls execute in the context of a login session generated through username and password validation at the server. This provides secure and authenticated access to the XenServer installation.

3.1. Getting Started with the API

We will start our tour of the API by describing the calls required to create a new VM on a XenServer installation, and take it through a start/suspend/resume/stop cycle. This is done without reference to code in any specific language; at this stage we just describe the informal sequence of RPC invocations that accomplish our "install and start" task.

3.1.1. Authentication: acquiring a session reference

The first step is to call Session.login(username, password). The API is session based, so before you can make other calls you need to authenticate with the server. Assuming the username and password are authenticated correctly, the result of this call is a session reference. Subsequent API calls take the session reference as a parameter. In this way we ensure that only API users who are suitably authorized can perform operations on a XenServer installation.

3.1.2. Acquiring a list of templates to base a new VM installation on

The next step is to query the list of "templates" on the host. Templates are specially-marked VM objects that specify suitable default parameters for a variety of supported guest types. (If you want to see a quick enumeration of the templates on a XenServer installation for yourself then you can execute the "xe template-list" CLI command.) To get a list of templates via the API, we need to find the VM objects on the server that have their "is_a_template" field set to true. One way to do this by calling VM.get_all_records(session) where the session parameter is the reference we acquired from our Session.login_with_password call earlier. This call queries the server, returning a snapshot (taken at the time of the call) containing all the VM object references and their field values.

(Remember that at this stage we are not concerned about the particular mechanisms by which the returned object references and field values can be manipulated in any particular client language: that detail is dealt with by our language-specific API bindings and described concretely in the following chapter. For now it suffices just to assume the existence of an abstract mechanism for reading and manipulating objects and field values returned by API calls.)

Now that we have a snapshot of all the VM objects' field values in the memory of our client application we can simply iterate through them and find the ones that have their "is_a_template" set to true. At this stage let's assume that our example application further iterates through the template objects and remembers the reference corresponding to the one that has its "name_label" set to "Debian Etch 4.0" (one of the default Linux templates supplied with XenServer).

3.1.3. Installing the VM based on a template

Continuing through our example, we must now install a new VM based on the template we selected. The installation process requires 2 API calls:

First we must now invoke the API call VM.clone(session, t_ref, "my first VM"). This tells the server to clone the VM object referenced by t_ref in order to make a new VM object. The return value of this call is the VM reference corresponding to the newly created VM. Let's call this new_vm_ref.
At this stage the object referred to by new_vm_ref is still a template (just like the VM object referred to by t_ref, from which it was cloned). To make new_vm_ref into a VM object we need to call VM.provision(session, new_vm_ref). When this call returns the new_vm_ref object will have had its is_a_template field set to false, indicating that new_vm_ref now refers to a regular VM ready for starting.

Note that the provision operation may take a few minutes, as it is as during this call that the template's disk images are created. In the case of the Debian template, the newly created disks are actually populated with a Debian root filesystem at this stage too.

3.1.4. Taking the VM through a start/suspend/resume/stop cycle

Now we have an object reference representing our newly installed VM, it is trivial to take it through a few lifecycle operations:

To start our VM we can just call VM.start(session, new_vm_ref)
After it's running, we can suspend it by calling VM.suspend(session, new_vm_ref);
and then resume it by calling VM.resume(session, new_vm_ref).
We can call VM.shutdown(session, new_vm_ref) to shutdown the VM cleanly.

3.1.5. Logging out

Once an application is finished interacting with a XenServer host it is good practice to call Session.logout(session). This invalidates the session reference (so it can not be used in subsequent API calls) and simultaneously deallocates server-side memory used to store the session object.

Although inactive sessions will timeout eventually, the server has a hardcoded limit of 200 concurrent sessions. Once this limit has been reached fresh logins will evict the oldest session objects, causing their associated session references to become invalid. So if you want your applications to play nice with others accessing the server concurrently, then the best policy is to create a single session at start-of-day, use this throughout the applications (note that sessions can be used across multiple separate client-server network connections) and then explicitly logout when possible.

3.1.6. "Install and start example": summary

We have seen how the API can be used to install a VM from a XenServer template and perform a number of lifecycle operations on it. You will note that the number of calls we had to make in order to affect these operations was small:

One call to acquire a session: Session.login_with_password(...)
One call to query the VM (and template) objects present on the XenServer installation: VM.get_all_records(...). Recall that we used the information returned from this call to select a suitable template to install from.
Two calls to install a VM from our chosen template: VM.clone(...), followed by VM.provision(...).
One call to start the resultant VM: VM.start(...) (and similarly other single calls to suspend, resume and shutdown accordingly)
And then one call to logout Session.logout(...)

The take-home message here is that, although the API as a whole is complex and fully featured, common tasks (such as creating and performing lifecycle operations on VMs) are very straightforward to perform, requiring only a small number of simple API calls. Keep this in mind whilst you study the next section which may, on first reading, appear a little daunting!