XenAPI Basics

This document contains a description of the Xen Management API - an interface for remotely configuring and controlling virtualised guests running on a Xen-enabled host.

The API is presented here as a set of Remote Procedure Calls (RPCs). There are two supported wire formats, one based upon XML-RPC and one based upon JSON-RPC (v1.0 and v2.0 are both recognized). No specific language bindings are prescribed, although examples are given in the Python programming language.

Although we adopt some terminology from object-oriented programming, future client language bindings may or may not be object-oriented. The API reference uses the terminology classes and objects. For our purposes a class is simply a hierarchical namespace; an object is an instance of a class with its fields set to specific values. Objects are persistent and exist on the server-side. Clients may obtain opaque references to these server-side objects and then access their fields via get/set RPCs.

For each class we specify a list of fields along with their types and qualifiers. A qualifier is one of:

• RO/runtime: the field is Read Only. Furthermore, its value is automatically computed at runtime. For example, current CPU load and disk IO throughput.

• RO/constructor: the field must be manually set when a new object is created, but is then Read Only for the duration of the object’s life. For example, the maximum memory addressable by a guest is set before the guest boots.

• RW: the field is Read/Write. For example, the name of a VM.

Types

The following types are used to specify methods and fields in the API Reference:

• string: Text strings.
• int: 64-bit integers.
• float: IEEE double-precision floating-point numbers.
• bool: Boolean.
• datetime: Date and timestamp.
• c ref: Reference to an object of class c.
• t set: Arbitrary-length set of values of type t.
• (k -> v) map: Mapping from values of type k to values of type v.
• e enum: Enumeration type with name e. Enums are defined in the API reference together with classes that use them.

Note that there are a number of cases where refs are doubly linked. For example, a VM has a field called VIFs of type VIF ref set; this field lists the network interfaces attached to a particular VM. Similarly, the VIF class has a field called VM of type VM ref which references the VM to which the interface is connected. These two fields are bound together, in the sense that creating a new VIF causes the VIFs field of the corresponding VM object to be updated automatically.

The API reference lists explicitly the fields that are bound together in this way. It also contains a diagram that shows relationships between classes. In this diagram an edge signifies the existence of a pair of fields that are bound together, using standard crows-foot notation to signify the type of relationship (e.g. one-many, many-many).

RPCs associated with fields

Each field, f, has an RPC accessor associated with it that returns f’s value:

• get_f (r): takes a ref, r that refers to an object and returns the value of f.

Each field, f, with qualifier RW and whose outermost type is set has the following additional RPCs associated with it:

• add_f(r, v): adds a new element v to the set. Note that sets cannot contain duplicate values, hence this operation has no action in the case that v is already in the set.

• remove_f(r, v): removes element v from the set.

Each field, f, with qualifier RW and whose outermost type is map has the following additional RPCs associated with it:

• add_to_f(r, k, v): adds new pair k -> v to the mapping stored in f in object r. Attempting to add a new pair for duplicate key, k, fails with a MAP_DUPLICATE_KEY error.

• remove_from_f(r, k): removes the pair with key k from the mapping stored in f in object r.

Each field whose outermost type is neither set nor map, but whose qualifier is RW has an RPC accessor associated with it that sets its value:

• set_f(r, v): sets the field f on object r to value v.

RPCs associated with classes

• Most classes have a constructor RPC named create that takes as parameters all fields marked RW and RO/constructor. The result of this RPC is that a new persistent object is created on the server-side with the specified field values.

• Each class has a get_by_uuid(uuid) RPC that returns the object of that class that has the specified uuid.

• Each class that has a name_label field has a get_by_name_label(name_label) RPC that returns a set of objects of that class that have the specified name_label.

• Most classes have a destroy(r) RPC that explicitly deletes the persistent object specified by r from the system. This is a non-cascading delete - if the object being removed is referenced by another object then the destroy call will fail.

Apart from the RPCs enumerated above, most classes have additional RPCs associated with them. For example, the VM class has RPCs for cloning, suspending, starting etc. Such additional RPCs are described explicitly in the API reference.

Wire Protocol

API calls are sent over a network to a Xen-enabled host using an RPC protocol. Here we describe how the higher-level types used in our API Reference are mapped to primitive RPC types, covering the two supported wire formats XML-RPC and JSON-RPC.

XML-RPC Protocol

We specify the signatures of API functions in the following style:

(VM ref set)  VM.get_all()

This specifies that the function with name VM.get_all takes no parameters and returns a set of VM ref. These types are mapped onto XML-RPC types in a straight-forward manner:

• the types float, bool, datetime, and string map directly to the XML-RPC <double>, <boolean>, <dateTime.iso8601>, and <string> elements.

• all ref types are opaque references, encoded as the XML-RPC’s <string> type. Users of the API should not make assumptions about the concrete form of these strings and should not expect them to remain valid after the client’s session with the server has terminated.

• fields named uuid of type string are mapped to the XML-RPC <string> type. The string itself is the OSF DCE UUID presentation format (as output by uuidgen).

• int is assumed to be 64-bit in our API and is encoded as a string of decimal digits (rather than using XML-RPC’s built-in 32-bit <i4> type).

• values of enum types are encoded as strings. For example, the value destroy of enum on_normal_exit, would be conveyed as:

    <value><string>destroy</string></value>

• for all our types, t, our type t set simply maps to XML-RPC’s <array> type, so, for example, a value of type string set would be transmitted like this:

    <array>
      <data>
        <value><string>CX8</string></value>
        <value><string>PSE36</string></value>
        <value><string>FPU</string></value>
      </data>
    </array>

• for types k and v, our type (k -> v) map maps onto an XML-RPC <struct>, with the key as the name of the struct. Note that the (k -> v) map type is only valid when k is a string, ref, or int, and in each case the keys of the maps are stringified as above. For example, the (string -> float) map containing the mappings Mike -> 2.3 and John -> 1.2 would be represented as:

    <value>
      <struct>
        <member>
          <name>Mike</name>
          <value><double>2.3</double></value>
        </member>
        <member>
          <name>John</name>
          <value><double>1.2</double></value>
        </member>
      </struct>
    </value>

• our void type is transmitted as an empty string.

XML-RPC Return Values and Status Codes

The return value of an RPC call is an XML-RPC <struct>.

• The first element of the struct is named Status; it contains a string value indicating whether the result of the call was a Success or a Failure.

If the Status is Success then the struct contains a second element named Value:

• The element of the struct named Value contains the function’s return value.

If the Status is Failure then the struct contains a second element named ErrorDescription:

• The element of the struct named ErrorDescription contains an array of string values. The first element of the array is an error code; the rest of the elements are strings representing error parameters relating to that code.

For example, an XML-RPC return value from the host.get_resident_VMs function may look like this:

    <struct>
       <member>
         <name>Status</name>
         <value>Success</value>
       </member>
       <member>
          <name>Value</name>
          <value>
            <array>
               <data>
                 <value>81547a35-205c-a551-c577-00b982c5fe00</value>
                 <value>61c85a22-05da-b8a2-2e55-06b0847da503</value>
                 <value>1d401ec4-3c17-35a6-fc79-cee6bd9811fe</value>
               </data>
            </array>
         </value>
       </member>
    </struct>

JSON-RPC Protocol

We specify the signatures of API functions in the following style:

(VM ref set)  VM.get_all()

This specifies that the function with name VM.get_all takes no parameters and returns a set of VM ref. These types are mapped onto JSON-RPC types in the following manner:

• the types float and bool map directly to the JSON types number and boolean, while datetime and string are represented as the JSON string type.

• all ref types are opaque references, encoded as the JSON string type. Users of the API should not make assumptions about the concrete form of these strings and should not expect them to remain valid after the client’s session with the server has terminated.

• fields named uuid of type string are mapped to the JSON string type. The string itself is the OSF DCE UUID presentation format (as output by uuidgen).

• int is assumed to be 64-bit in our API and is encoded as a JSON number without decimal point or exponent, preserved as a string.

• values of enum types are encoded as the JSON string type. For example, the value destroy of enum on_normal_exit, would be conveyed as:

  "destroy"

• for all our types, t, our type t set simply maps to the JSON array type, so, for example, a value of type string set would be transmitted like this:

  [ "CX8", "PSE36", "FPU" ]

• for types k and v, our type (k -> v) map maps onto a JSON object which contains members with name k and value v. Note that the (k -> v) map type is only valid when k is a string, ref, or int, and in each case the keys of the maps are stringified as above. For example, the (string -> float) map containing the mappings Mike -> 2.3 and John -> 1.2 would be represented as:

  {
    "Mike": 2.3,
    "John": 1.2
  }

• our void type is transmitted as an empty string.

Both versions 1.0 and 2.0 of the JSON-RPC wire format are recognised and, depending on your client library, you can use either of them.

JSON-RPC v1.0

JSON-RPC v1.0 Requests

An API call is represented by sending a single JSON object to the server, which contains the members method, params, and id.

• method: A JSON string containing the name of the function to be invoked.

• params: A JSON array of values, which represents the parameters of the function to be invoked.

• id: A JSON string or integer representing the call id. Note that, diverging from the JSON-RPC v1.0 specification the API does not accept notification requests (requests without responses), i.e. the id cannot be null.

For example, the body of a JSON-RPC v1.0 request to retrieve the resident VMs of a host may look like this:

  {
    "method": "host.get_resident_VMs",
    "params": [
      "OpaqueRef:74f1a19cd-b660-41e3-a163-10f03e0eae67",
      "OpaqueRef:08c34fc9-f418-4f09-8274-b9cb25cd8550"
    ],
    "id": "xyz"
  }

In the above example, the first element of the params array is the reference of the open session to the host, while the second is the host reference.

JSON-RPC v1.0 Return Values

The return value of a JSON-RPC v1.0 call is a single JSON object containing the members result, error, and id.

• result: If the call is successful, it is a JSON value (string, array etc.) representing the return value of the invoked function. If an error has occurred, it is null.

• error: If the call is successful, it is null. If the call has failed, it a JSON array of string values. The first element of the array is an error code; the remainder of the array are strings representing error parameters relating to that code.

• id: The call id. It is a JSON string or integer and it is the same id as the request it is responding to.

For example, a JSON-RPC v1.0 return value from the host.get_resident_VMs function may look like this:

  {
    "result": [
        "OpaqueRef:604f51e7-630f-4412-83fa-b11c6cf008ab",
        "OpaqueRef:670d08f5-cbeb-4336-8420-ccd56390a65f"
    ],
    "error": null,
    "id": "xyz"
  }

while the return value of the same call made on a logged out session may look like this:

  {
    "result": null,
    "error": [
        "SESSION_INVALID",
        "OpaqueRef:93f1a23cd-a640-41e3-b163-10f86e0eae67"
    ],
    "id": "xyz"
  }

JSON-RPC v2.0

JSON-RPC v2.0 Requests

An API call is represented by sending a single JSON object to the server, which contains the members jsonrpc, method, params, and id.

• jsonrpc: A JSON string specifying the version of the JSON-RPC protocol. It is exactly “2.0”.

• method: A JSON string containing the name of the function to be invoked.

• params: A JSON array of values, which represents the parameters of the function to be invoked. Although the JSON-RPC v2.0 specification allows this member to be omitted, in practice all API calls accept at least one parameter.

• id: A JSON string or integer representing the call id. Note that, diverging from the JSON-RPC v2.0 specification it cannot be null. Neither can it be omitted because the API does not accept notification requests (requests without responses).

For example, the body of a JSON-RPC v2.0 request to retrieve the VMs resident on a host may look like this:

  {
    "jsonrpc": "2.0",
    "method": "host.get_resident_VMs",
    "params": [
      "OpaqueRef:c90cd28f-37ec-4dbf-88e6-f697ccb28b39",
      "OpaqueRef:08c34fc9-f418-4f09-8274-b9cb25cd8550"
    ],
    "id": 3
 }

As before, the first element of the parameter array is the reference of the open session to the host, while the second is the host reference.

JSON-RPC v2.0 Return Values

The return value of a JSON-RPC v2.0 call is a single JSON object containing the members jsonrpc, either result or error depending on the outcome of the call, and id.

• jsonrpc: A JSON string specifying the version of the JSON-RPC protocol. It is exactly “2.0”.

• result: If the call is successful, it is a JSON value (string, array etc.) representing the return value of the invoked function. If an error has occurred, it does not exist.

• error: If the call is successful, it does not exist. If the call has failed, it is a single structured JSON object (see below).

• id: The call id. It is a JSON string or integer and it is the same id as the request it is responding to.

The error object contains the members code, message, and data.

• code: The API does not make use of this member and only retains it for compliance with the JSON-RPC v2.0 specification. It is a JSON integer which has a non-zero value.

• message: A JSON string representing an API error code.

• data: A JSON array of string values representing error parameters relating to the aforementioned API error code.

For example, a JSON-RPC v2.0 return value from the host.get_resident_VMs function may look like this:

  {
    "jsonrpc": "2.0",
    "result": [
        "OpaqueRef:604f51e7-630f-4412-83fa-b11c6cf008ab",
        "OpaqueRef:670d08f5-cbeb-4336-8420-ccd56390a65f"
    ],
    "id": 3
  }

while the return value of the same call made on a logged out session may look like this:

  {
    "jsonrpc": "2.0",
    "error": {
        "code": 1,
        "message": "SESSION_INVALID",
        "data": [
            "OpaqueRef:c90cd28f-37ec-4dbf-88e6-f697ccb28b39"
        ]
    },
    "id": 3
  }

Errors

When a low-level transport error occurs, or a request is malformed at the HTTP or RPC level, the server may send an HTTP 500 error response, or the client may simulate the same. The client must be prepared to handle these errors, though they may be treated as fatal.

For example, the following malformed request when using the XML-RPC protocol:

$curl -D - -X POST https://server -H 'Content-Type: application/xml' \
  -d '<?xml version="1.0"?>
  <methodCall>
    <methodName>session.logout</methodName>
  </methodCall>'

results to the following response:

HTTP/1.1 500 Internal Error
content-length: 297
content-type:text/html
connection:close
cache-control:no-cache, no-store

<html><body><h1>HTTP 500 internal server error</h1>An unexpected error occurred;
 please wait a while and try again. If the problem persists, please contact your
 support representative.<h1> Additional information </h1>Xmlrpc.Parse_error(&quo
t;close_tag&quot;, &quot;open_tag&quot;, _)</body></html>

When using the JSON-RPC protocol:

$curl -D - -X POST https://server/jsonrpc -H 'Content-Type: application/json' \
  -d '{
      "jsonrpc": "2.0",
      "method": "session.login_with_password",
      "id": 0
  }'

the response is:

HTTP/1.1 500 Internal Error
content-length: 308
content-type:text/html
connection:close
cache-control:no-cache, no-store

<html><body><h1>HTTP 500 internal server error</h1>An unexpected error occurred;
 please wait a while and try again. If the problem persists, please contact your
 support representative.<h1> Additional information </h1>Jsonrpc.Malformed_metho
d_request(&quot;{jsonrpc=...,method=...,id=...}&quot;)</body></html>

All other failures are reported with a more structured error response, to allow better automatic response to failures, proper internationalization of any error message, and easier debugging.

On the wire, these are transmitted like this when using the XML-RPC protocol:

<struct>
    <member>
        <name>Status</name>
        <value>Failure</value>
    </member>
    <member>
        <name>ErrorDescription</name>
        <value>
            <array>
                <data>
                    <value>MAP_DUPLICATE_KEY</value>
                    <value>Customer</value>
                    <value>eSpiel Inc.</value>
                    <value>eSpiel Incorporated</value>
                </data>
            </array>
        </value>
    </member>
</struct>

Note that ErrorDescription value is an array of string values. The first element of the array is an error code; the remainder of the array are strings representing error parameters relating to that code. In this case, the client has attempted to add the mapping Customer -> eSpiel Incorporated to a Map, but it already contains the mapping Customer -> eSpiel Inc., hence the request has failed.

When using the JSON-RPC protocol v2.0, the above error is transmitted as:

{
    "jsonrpc": "2.0",
    "error": {
        "code": 1,
        "message": "MAP_DUPLICATE_KEY",
        "data": [
            "Customer",
            "eSpiel Inc.",
            "eSpiel Incorporated"
        ]
    },
    "id": 3
}

Finally, when using the JSON-RPC protocol v1.0:

{
    "result": null,
    "error": [
        "MAP_DUPLICATE_KEY",
        "Customer",
        "eSpiel Inc.",
        "eSpiel Incorporated"
    ],
    "id": "xyz"
}

Each possible error code is documented in the last section of the API reference.

Note on References vs UUIDs

References are opaque types - encoded as XML-RPC and JSON-RPC strings on the wire - understood only by the particular server which generated them. Servers are free to choose any concrete representation they find convenient; clients should not make any assumptions or attempt to parse the string contents. References are not guaranteed to be permanent identifiers for objects; clients should not assume that references generated during one session are valid for any future session. References do not allow objects to be compared for equality. Two references to the same object are not guaranteed to be textually identical.

UUIDs are intended to be permanent identifiers for objects. They are guaranteed to be in the OSF DCE UUID presentation format (as output by uuidgen). Clients may store UUIDs on disk and use them to look up objects in subsequent sessions with the server. Clients may also test equality on objects by comparing UUID strings.

The API provides mechanisms for translating between UUIDs and opaque references. Each class that contains a UUID field provides:

• A get_by_uuid method that takes a UUID and returns an opaque reference to the server-side object that has that UUID;

• A get_uuid function (a regular “field getter” RPC) that takes an opaque reference and returns the UUID of the server-side object that is referenced by it.

Making RPC Calls

Transport Layer

The following transport layers are currently supported:

• HTTP/HTTPS for remote administration
• HTTP over Unix domain sockets for local administration

Session Layer

The RPC interface is session-based; before you can make arbitrary RPC calls you must login and initiate a session. For example:

   (session ref) session.login_with_password(string uname, string pwd,
                   string version, string originator)

where uname and password refer to your username and password, as defined by the Xen administrator, while version and originator are optional. The session ref returned by session.login_with_password is passed to subsequent RPC calls as an authentication token. Note that a session reference obtained by a login request to the XML-RPC backend can be used in subsequent requests to the JSON-RPC backend, and vice versa.

A session can be terminated with the session.logout function:

   void  session.logout(session ref session_id)

Synchronous and Asynchronous Invocation

Each method call (apart from methods on the Session and Task objects and “getters” and “setters” derived from fields) can be made either synchronously or asynchronously. A synchronous RPC call blocks until the return value is received; the return value of a synchronous RPC call is exactly as specified above.

Only synchronous API calls are listed explicitly in this document. All their asynchronous counterparts are in the special Async namespace. For example, the synchronous call VM.clone(...) has an asynchronous counterpart, Async.VM.clone(...), that is non-blocking.

Instead of returning its result directly, an asynchronous RPC call returns an identifier of type task ref which is subsequently used to track the status of a running asynchronous RPC.

Note that an asynchronous call may fail immediately, before a task has even been created. When using the XML-RPC wire protocol, this eventuality is represented by wrapping the returned task ref in an XML-RPC struct with a Status, ErrorDescription, and Value fields, exactly as specified above; the task ref is provided in the Value field if Status is set to Success. When using the JSON-RPC protocol, the task ref is wrapped in a response JSON object as specified above and it is provided by the value of the result member of a successful call.

The RPC call

    (task ref set)  Task.get_all(session ref session_id)

returns a set of all task identifiers known to the system. The status (including any returned result and error codes) of these can then be queried by accessing the fields of the Task object in the usual way. Note that, in order to get a consistent snapshot of a task’s state, it is advisable to call the get_record function.

Example interactive session

This section describes how an interactive session might look, using python XML-RPC and JSON-RPC client libraries.

First, initialise python:

$ python3
>>>

Using the XML-RPC Protocol

Import the library xmlrpc.client and create a python object referencing the remote server as shown below:

>>> import xmlrpc.client
>>> xen = xmlrpc.client.ServerProxy("https://localhost:443")

Note that you may need to disable SSL certificate validation to establish the connection, this can be done as follows:

>>> import ssl
>>> ctx = ssl._create_unverified_context()
>>> xen = xmlrpc.client.ServerProxy("https://localhost:443", context=ctx)

Acquire a session reference by logging in with a username and password; the session reference is returned under the key Value in the resulting dictionary (error-handling omitted for brevity):

>>> session = xen.session.login_with_password("user", "passwd",
...                                           "version", "originator")['Value']

This is what the call looks like when serialized

<?xml version='1.0'?>
<methodCall>
    <methodName>session.login_with_password</methodName>
    <params>
        <param><value><string>user</string></value></param>
        <param><value><string>passwd</string></value></param>
        <param><value><string>version</string></value></param>
        <param><value><string>originator</string></value></param>
    </params>
</methodCall>

Next, the user may acquire a list of all the VMs known to the system (note the call takes the session reference as the only parameter):

>>> all_vms = xen.VM.get_all(session)['Value']
>>> all_vms
['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ]

The VM references here have the form OpaqueRef:X (though they may not be that simple in reality) and you should treat them as opaque strings. Templates are VMs with the is_a_template field set to true. We can find the subset of template VMs using a command like the following:

>>> all_templates = filter(lambda x: xen.VM.get_is_a_template(session, x)['Value'],
                              all_vms)

Once a reference to a VM has been acquired, a lifecycle operation may be invoked:

>>> xen.VM.start(session, all_templates[0], False, False)
{'Status': 'Failure', 'ErrorDescription': ['VM_IS_TEMPLATE', 'OpaqueRef:X']}

In this case the start message has been rejected, because the VM is a template, and so an error response has been returned. These high-level errors are returned as structured data (rather than as XML-RPC faults), allowing them to be internationalized.

Rather than querying fields individually, whole records may be returned at once. To retrieve the record of a single object as a python dictionary:

>>> record = xen.VM.get_record(session, all_templates[0])['Value']
>>> record['power_state']
'Halted'
>>> record['name_label']
'Windows 10 (64-bit)'

To retrieve all the VM records in a single call:

>>> records = xen.VM.get_all_records(session)['Value']
>>> list(records.keys())
['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ]
>>> records['OpaqueRef:1']['name_label']
'Red Hat Enterprise Linux 7'

Using the JSON-RPC Protocol

For this example we are making use of the package jsonrpcclient and the requests library due to their simplicity, although other packages can also be used.

First, import the requests and jsonrpcclient libraries:

>>> import requests
>>> import jsonrpcclient

Now we construct a utility method to make using these libraries easier:

>>> def jsonrpccall(method, params):
...     r = requests.post("https://localhost:443/jsonrpc",
...                       json=jsonrpcclient.request(method, params=params),
...                       verify=False)
...     p = jsonrpcclient.parse(r.json())
...     if isinstance(p, jsonrpcclient.Ok):
...         return p.result
...     raise Exception(p.message, p.data)

Acquire a session reference by logging in with a username and password:

>>> session = jsonrpccall("session.login_with_password",
...                       ("user", "password", "version", "originator"))

jsonrpcclient uses the JSON-RPC protocol v2.0, so this is what the serialized request looks like:

  {
    "jsonrpc": "2.0",
    "method": "session.login_with_password",
    "params": ["user", "passwd", "version", "originator"],
    "id": 0
  }

Next, the user may acquire a list of all the VMs known to the system (note the call takes the session reference as the only parameter):

>>> all_vms = jsonrpccall("VM.get_all", (session,))
>>> all_vms
['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ]

The VM references here have the form OpaqueRef:X (though they may not be that simple in reality) and you should treat them as opaque strings. Templates are VMs with the is_a_template field set to true. We can find the subset of template VMs using a command like the following:

>>> all_templates = filter(
...     lambda x: jsonrpccall("VM.get_is_a_template", (session, x)),
...     all_vms)

Once a reference to a VM has been acquired, a lifecycle operation may be invoked:

>>> try:
...     jsonrpccall("VM.start", (session, next(all_templates), False, False))
... except Exception as e:
...     e
...
Exception('VM_IS_TEMPLATE', ['OpaqueRef:1', 'start'])

In this case the start message has been rejected because the VM is a template, hence an error response has been returned. These high-level errors are returned as structured data, allowing them to be internationalized.

Rather than querying fields individually, whole records may be returned at once. To retrieve the record of a single object as a python dictionary:

>>> record = jsonrpccall("VM.get_record", (session, next(all_templates)))
>>> record['power_state']
'Halted'
>>> record['name_label']
'Windows 10 (64-bit)'

To retrieve all the VM records in a single call:

>>> records = jsonrpccall("VM.get_all_records", (session,))
>>> records.keys()
['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ]
>>> records['OpaqueRef:1']['name_label']
'Red Hat Enterprise Linux 7'

Overview of the XenAPI

This chapter introduces the XenAPI and its associated object model. The API has the following key features:

• Management of all aspects of the XenServer Host. The API allows you to manage VMs, storage, networking, host configuration and pools. Performance and status metrics can also be queried from 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 (that is, 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 from 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 over 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.

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.

Authentication: acquiring a session reference

The first step is to call Session.login_with_password(, , , ). The API is session based, so before you can make other calls you will 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. You can continue to use the same session for any number of API calls. When you have finished the session, Citrix recommends that you call Session.logout(session) to clean up: see later.

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 from 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).

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 4 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.

• Next, we need to specify the UUID of the Storage Repository where the VM’s disks will be instantiated. We have to put this in the sr attribute in the disk provisioning XML stored under the “disks” key in the other_config map of the newly-created VM. This field can be updated by calling its getter (other_config <- VM.get_other_config(session, new_vm_ref)) and then its setter (VM.set_other_config(session, new_vm_ref, other_config)) with the modified other_config map.

• 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

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 also at this stage populated with a Debian root filesystem.

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.

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 cannot be used in subsequent API calls) and simultaneously deallocates server-side memory used to store the session object.

Although inactive sessions will eventually timeout, the server has a hardcoded limit of 500 concurrent sessions for each username or originator. Once this limit has been reached fresh logins will evict the session objects that have been used least recently, causing their associated session references to become invalid. For successful interoperability with other applications, concurrently accessing the server, the best policy is:

• Choose a string that identifies your application and its version.

• Create a single session at start-of-day, using that identifying string for the originator parameter to Session.login_with_password.

• Use this session throughout the application (note that sessions can be used across multiple separate client-server network connections) and then explicitly logout when possible.

If a poorly written client leaks sessions or otherwise exceeds the limit, then as long as the client uses an appropriate originator argument, it will be easily identifiable from the XenServer logs and XenServer will destroy the longest-idle sessions of the rogue client only; this may cause problems for that client but not for other clients. If the misbehaving client did not specify an originator, it would be harder to identify and would cause the premature destruction of sessions of any clients that also did not specify an originator

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.

• Four calls to install a VM from our chosen template: VM.clone(), followed by the getter and setter of the other_config field to specify where to create the disk images of the template, and then 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 while you study the next section which may, on first reading, appear a little daunting!

Object Model Overview

This section gives a high-level overview of the object model of the API. A more detailed description of the parameters and methods of each class outlined here can be found in the XenServer API Reference document.

We start by giving a brief outline of some of the core classes that make up the API. (Don’t worry if these definitions seem somewhat abstract in their initial presentation; the textual description in subsequent sections, and the code-sample walk through in the next Chapter will help make these concepts concrete.)

At this point, readers who are finding this enumeration of classes rather terse may wish to skip to the code walk-throughs of the next chapter: there are plenty of useful applications that can be written using only a subset of the classes already described! For those who wish to continue this description of classes in the abstract, read on.

On top of the classes listed above, there are 4 more that act as connectors, specifying relationships between VMs and Hosts, and Storage and Networks. The first 2 of these classes that we will consider, VBD and VIF, determine how VMs are attached to virtual disks and network objects respectively:

The second set of “connector classes” that we will consider determine how Hosts are attached to Networks and Storage.

The figure above presents a graphical overview of the API classes involved in managing VMs, Hosts, Storage and Networking. From this diagram, the symmetry between storage and network configuration, and also the symmetry between virtual machine and host configuration is plain to see.

Working with VIFs and VBDs

In this section we walk through a few more complex scenarios, describing informally how various tasks involving virtual storage and network devices can be accomplished using the API.

Creating disks and attaching them to VMs

Let’s start by considering how to make a new blank disk image and attach it to a running VM. We will assume that we already have ourselves a running VM, and we know its corresponding API object reference (e.g. we may have created this VM using the procedure described in the previous section, and had the server return its reference to us.) We will also assume that we have authenticated with the XenServer installation and have a corresponding session reference. Indeed in the rest of this chapter, for the sake of brevity, we will stop mentioning sessions altogether.

Creating a new blank disk image

The first step is to instantiate the disk image on physical storage. We do this by calling VDI.create(). The VDI.create call takes a number of parameters, including:

• name_label and name_description: a human-readable name/description for the disk (e.g. for convenient display in the UI etc.). These fields can be left blank if desired.

• SR: the object reference of the Storage Repository representing the physical storage in which the VDI’s bits will be placed.

• read_only: setting this field to true indicates that the VDI can only be attached to VMs in a read-only fashion. (Attempting to attach a VDI with its read_only field set to true in a read/write fashion results in error.)

Invoking the VDI.create call causes the XenServer installation to create a blank disk image on physical storage, create an associated VDI object (the datamodel instance that refers to the disk image on physical storage) and return a reference to this newly created VDI object.

The way in which the disk image is represented on physical storage depends on the type of the SR in which the created VDI resides. For example, if the SR is of type “lvm” then the new disk image will be rendered as an LVM volume; if the SR is of type “nfs” then the new disk image will be a sparse VHD file created on an NFS filer. (You can query the SR type through the API using the SR.get_type() call.)

Note

Some SR types might round up the virtual-size value to make it divisible by a configured block size.

Attaching the disk image to a VM

So far we have a running VM (that we assumed the existence of at the start of this example) and a fresh VDI that we just created. Right now, these are both independent objects that exist on the XenServer Host, but there is nothing linking them together. So our next step is to create such a link, associating the VDI with our VM.

The attachment is formed by creating a new “connector” object called a VBD (Virtual Block Device). To create our VBD we invoke the VBD.create() call. The VBD.create() call takes a number of parameters including:

• VM - the object reference of the VM to which the VDI is to be attached

• VDI - the object reference of the VDI that is to be attached

• mode - specifies whether the VDI is to be attached in a read-only or a read-write fashion

• userdevice - specifies the block device inside the guest through which applications running inside the VM will be able to read/write the VDI’s bits.

• type - specifies whether the VDI should be presented inside the VM as a regular disk or as a CD. (Note that this particular field has more meaning for Windows VMs than it does for Linux VMs, but we will not explore this level of detail in this chapter.)

Invoking VBD.create makes a VBD object on the XenServer installation and returns its object reference. However, this call in itself does not have any side-effects on the running VM (that is, if you go and look inside the running VM you will see that the block device has not been created). The fact that the VBD object exists but that the block device in the guest is not active, is reflected by the fact that the VBD object’s currently_attached field is set to false.

For expository purposes, the figure above presents a graphical example that shows the relationship between VMs, VBDs, VDIs and SRs. In this instance a VM object has 2 attached VDIs: there are 2 VBD objects that form the connections between the VM object and its VDIs; and the VDIs reside within the same SR.

Hotplugging the VBD

If we rebooted the VM at this stage then, after rebooting, the block device corresponding to the VBD would appear: on boot, XenServer queries all VBDs of a VM and actively attaches each of the corresponding VDIs.

Rebooting the VM is all very well, but recall that we wanted to attach a newly created blank disk to a running VM. This can be achieved by invoking the plug method on the newly created VBD object. When the plug call returns successfully, the block device to which the VBD relates will have appeared inside the running VM – i.e. from the perspective of the running VM, the guest operating system is led to believe that a new disk device has just been hot plugged. Mirroring this fact in the managed world of the API, the currently_attached field of the VBD is set to true.

Unsurprisingly, the VBD plug method has a dual called “unplug”. Invoking the unplug method on a VBD object causes the associated block device to be hot unplugged from a running VM, setting the currently_attached field of the VBD object to false accordingly.

Creating and attaching Network Devices to VMs

The API calls involved in configuring virtual network interfaces in VMs are similar in many respects to the calls involved in configuring virtual disk devices. For this reason we will not run through a full example of how one can create network interfaces using the API object-model; instead we will use this section just to outline briefly the symmetry between virtual networking device and virtual storage device configuration.

The networking analogue of the VBD class is the VIF class. Just as a VBD is the API representation of a block device inside a VM, a VIF (Virtual network InterFace) is the API representation of a network device inside a VM. Whereas VBDs associate VM objects with VDI objects, VIFs associate VM objects with Network objects. Just like VBDs, VIFs have a currently_attached field that determines whether or not the network device (inside the guest) associated with the VIF is currently active or not. And as we saw with VBDs, at VM boot-time the VIFs of the VM are queried and a corresponding network device for each created inside the booting VM. Similarly, VIFs also have plug and unplug methods for hot plugging/unplugging network devices in/out of running VMs.

Host configuration for networking and storage

We have seen that the VBD and VIF classes are used to manage configuration of block devices and network devices (respectively) inside VMs. To manage host configuration of storage and networking there are two analogous classes: PBD (Physical Block Device) and PIF (Physical [network] InterFace).

Host storage configuration: PBDs

Let us start by considering the PBD class. A PBD_create() call takes a number of parameters including:

For example, imagine we have an SR object s of type “nfs” (representing a directory on an NFS filer within which VDIs are stored as VHD files); and let’s say that we want a host, h, to be able to access s. In this case we invoke PBD.create() specifying host h, SR s, and a value for the device_config parameter that is the following map:

("server", "my_nfs_server.example.com"), ("serverpath", "/scratch/mysrs/sr1")

This tells the XenServer Host that SR s is accessible on host h, and further that to access SR s, the host needs to mount the directory /scratch/mysrs/sr1 on the NFS server named my_nfs_server.example.com.

Like VBD objects, PBD objects also have a field called currently_attached. Storage repositories can be attached and detached from a given host by invoking PBD.plug and PBD.unplug methods respectively.

Host networking configuration: PIFs

Host network configuration is specified by virtue of PIF objects. If a PIF object connects a network object, n, to a host object h, then the network corresponding to n is bridged onto a physical interface (or a physical interface plus a VLAN tag) specified by the fields of the PIF object.

For example, imagine a PIF object exists connecting host h to a network n, and that device field of the PIF object is set to eth0. This means that all packets on network n are bridged to the NIC in the host corresponding to host network device eth0.

XML-RPC notes

Datetimes

The API deviates from the XML-RPC specification in handling of datetimes. The API appends a “Z” to the end of datetime strings, which is meant to indicate that the time is expressed in UTC.

API evolution

All APIs evolve as bugs are fixed, new features added and features are removed

• the XenAPI is no exception. This document lists policies describing how the XenAPI evolves over time.

The goals of XenAPI evolution are:

• to allow bugs to be fixed efficiently;
• to allow new, innovative features to be added easily;
• to keep old, unmodified clients working as much as possible; and
• where backwards-incompatible changes are to be made, publish this information early to enable affected parties to give timely feedback.

Background

In this document, the term XenAPI refers to the XMLRPC-derived wire protocol used by xapi. The XenAPI has objects which each have fields and messages. The XenAPI is described in detail elsewhere.

XenAPI Lifecycle

graph LR
    Prototype -->|1| Published -->|4| Deprecated -->|5| Removed
    Published -->|2,3| Published

Each element of the XenAPI (objects, messages and fields) follows the lifecycle diagram above. When an element is newly created and being still in development, it is in the Prototype state. Elements in this state may be stubs: the interface is there and can be used by clients for prototyping their new features, but the actual implementation is not yet ready.

When the element subsequently becomes ready for use (the stub is replaced by a real implementation), it transitions to the Published state. This is the only state in which the object, message or field should be used. From this point onwards, the element needs to have clearly defined semantics that are available for reference in the XenAPI documentation.

If the XenAPI element becomes Deprecated, it will still function as it did before, but its use is discouraged. The final stage of the lifecycle is the Removed state, in which the element is not available anymore.

The numbered state changes in the diagram have the following meaning:

1. Publish: declare that the XenAPI element is ready for people to use.
2. Extend: a backwards-compatible extension of the XenAPI, for example an additional parameter in a message with an appropriate default value. If the API is used as before, it still has the same effect.
3. Change: a backwards-incompatible change. That is, the message now behaves differently, or the field has different semantics. Such changes are discouraged and should only be considered in special cases (always consider whether deprecation is a better solution). The use of a message can for example be restricted for security or efficiency reasons, or the behaviour can be changed simply to fix a bug.
4. Deprecate: declare that the use of this XenAPI element should be avoided from now on. Reasons for doing this include: the element is redundant (it duplicates functionality elsewhere), it is inconsistent with other parts of the XenAPI, it is insecure or inefficient. For examples of deprecation policies of other projects, see the policies of the eclipse and oval projects.
5. Remove: the element is taken out of the public API and can no longer be used.

Each lifecycle transition must be accompanied by an explanation describing the change and the reason for the change. This message should be enough to understand the semantics of the XenAPI element after the change, and in the case of backwards-incompatible changes or deprecation, it should give directions about how to modify a client to deal with the change (for example, how to avoid using the deprecated field or message).

Releases

Every release must be accompanied by release notes listing all objects, fields and messages that are newly prototyped, published, extended, changed, deprecated or removed in the release. Each item should have an explanation as implied above, documenting the new or changed XenAPI element. The release notes for every release shall be prominently displayed in the XenAPI HTML documentation.

Documentation

The XenAPI documentation will contain its complete lifecycle history for each XenAPI element. Only the elements described in the documentation are “official” and supported.

Each object, message and field in datamodel.ml will have lifecycle metadata attached to it, which is a list of transitions (transition type * release * explanation string) as described above. Release notes are automatically generated from this data.

Using the API

This chapter describes how to use the XenServer Management API from real programs to manage XenServer Hosts and VMs. The chapter begins with a walk-through of a typical client application and demonstrates how the API can be used to perform common tasks. Example code fragments are given in python syntax but equivalent code in the other programming languages would look very similar. The language bindings themselves are discussed afterwards and the chapter finishes with walk-throughs of two complete examples.

Anatomy of a typical application

This section describes the structure of a typical application using the XenServer Management API. Most client applications begin by connecting to a XenServer Host and authenticating (e.g. with a username and password). Assuming the authentication succeeds, the server will create a “session” object and return a reference to the client. This reference will be passed as an argument to all future API calls. Once authenticated, the client may search for references to other useful objects (e.g. XenServer Hosts, VMs, etc.) and invoke operations on them. Operations may be invoked either synchronously or asynchronously; special task objects represent the state and progress of asynchronous operations. These application elements are all described in detail in the following sections.

Choosing a low-level transport

API calls can be issued over two transports:

• SSL-encrypted TCP on port 443 (https) over an IP network

• plaintext over a local Unix domain socket: /var/xapi/xapi

The SSL-encrypted TCP transport is used for all off-host traffic while the Unix domain socket can be used from services running directly on the XenServer Host itself. In the SSL-encrypted TCP transport, all API calls should be directed at the Resource Pool master; failure to do so will result in the error HOST_IS_SLAVE, which includes the IP address of the master as an error parameter.

Because the master host of a pool can change, especially if HA is enabled on a pool, clients must implement the following steps to detect a master host change and connect to the new master as required:

Subscribe to updates in the list of hosts servers, and maintain a current list of hosts in the pool

If the connection to the pool master fails to respond, attempt to connect to all hosts in the list until one responds

The first host to respond will return the HOST_IS_SLAVE error message, which contains the identity of the new pool master (unless of course the host is the new master)

Connect to the new master

Note

As a special-case, all messages sent through the Unix domain socket are transparently forwarded to the correct node.

Authentication and session handling

The vast majority of API calls take a session reference as their first parameter; failure to supply a valid reference will result in a SESSION_INVALID error being returned. Acquire a session reference by supplying a username and password to the login_with_password function.

Note

As a special-case, if this call is executed over the local Unix domain socket then the username and password are ignored and the call always succeeds.

Every session has an associated “last active” timestamp which is updated on every API call. The server software currently has a built-in limit of 500 active sessions and will remove those with the oldest “last active” field if this limit is exceeded for a given username or originator. In addition all sessions whose “last active” field is older than 24 hours are also removed. Therefore it is important to:

• Specify an appropriate originator when logging in; and

• Remember to log out of active sessions to avoid leaking them; and

• Be prepared to log in again to the server if a SESSION_INVALID error is caught.

In the following Python fragment a connection is established over the Unix domain socket and a session is created:

import XenAPI

    session = XenAPI.xapi_local()
    try:
        session.xenapi.login_with_password("root", "", "2.3", "My Widget v0.1")
        ...
    finally:
        session.xenapi.session.logout()

Finding references to useful objects

Once an application has authenticated the next step is to acquire references to objects in order to query their state or invoke operations on them. All objects have a set of “implicit” messages which include the following:

• get_by_name_label : return a list of all objects of a particular class with a particular label;

• get_by_uuid : return a single object named by its UUID;

• get_all : return a set of references to all objects of a particular class; and

• get_all_records : return a map of reference to records for each object of a particular class.

For example, to list all hosts:

hosts = session.xenapi.host.get_all()

To find all VMs with the name “my first VM”:

vms = session.xenapi.VM.get_by_name_label('my first VM')

Note

Object name_label fields are not guaranteed to be unique and so the get_by_name_label API call returns a set of references rather than a single reference.

In addition to the methods of finding objects described above, most objects also contain references to other objects within fields. For example it is possible to find the set of VMs running on a particular host by calling:

vms = session.xenapi.host.get_resident_VMs(host)

Invoking synchronous operations on objects

Once object references have been acquired, operations may be invoked on them. For example to start a VM:

session.xenapi.VM.start(vm, False, False)

All API calls are by default synchronous and will not return until the operation has completed or failed. For example in the case of VM.start the call does not return until the VM has started booting.

Note

When the VM.start call returns the VM will be booting. To determine when the booting has finished, wait for the in-guest agent to report internal statistics through the VM_guest_metrics object.

Using Tasks to manage asynchronous operations

To simplify managing operations which take quite a long time (e.g. VM.clone and VM.copy) functions are available in two forms: synchronous (the default) and asynchronous. Each asynchronous function returns a reference to a task object which contains information about the in-progress operation including:

• whether it is pending

• whether it is has succeeded or failed

• progress (in the range 0-1)

• the result or error code returned by the operation

An application which wanted to track the progress of a VM.clone operation and display a progress bar would have code like the following:

vm = session.xenapi.VM.get_by_name_label('my vm')
task = session.xenapi.Async.VM.clone(vm)
while session.xenapi.task.get_status(task) == "pending":
        progress = session.xenapi.task.get_progress(task)
        update_progress_bar(progress)
        time.sleep(1)
session.xenapi.task.destroy(task)

Note

Note that a well-behaved client should remember to delete tasks created by asynchronous operations when it has finished reading the result or error. If the number of tasks exceeds a built-in threshold then the server will delete the oldest of the completed tasks.

Subscribing to and listening for events

With the exception of the task and metrics classes, whenever an object is modified the server generates an event. Clients can subscribe to this event stream on a per-class basis and receive updates rather than resorting to frequent polling. Events come in three types:

• add - generated when an object has been created;

• del - generated immediately before an object is destroyed; and

• mod - generated when an object’s field has changed.

Events also contain a monotonically increasing ID, the name of the class of object and a snapshot of the object state equivalent to the result of a get_record().

Clients register for events by calling event.register() with a list of class names or the special string “*”. Clients receive events by executing event.next() which blocks until events are available and returns the new events.

Note

Since the queue of generated events on the server is of finite length a very slow client might fail to read the events fast enough; if this happens an EVENTS_LOST error is returned. Clients should be prepared to handle this by re-registering for events and checking that the condition they are waiting for hasn’t become true while they were unregistered.

The following python code fragment demonstrates how to print a summary of every event generated by a system: (similar code exists in Xenserver-SDK/XenServerPython/samples/watch-all-events.py)

fmt = "%8s  %20s  %5s  %s"
session.xenapi.event.register(["*"])
while True:
    try:
        for event in session.xenapi.event.next():
            name = "(unknown)"
            if "snapshot" in event.keys():
                snapshot = event["snapshot"]
                if "name_label" in snapshot.keys():
                    name = snapshot["name_label"]
            print fmt % (event['id'], event['class'], event['operation'], name)           
    except XenAPI.Failure, e:
        if e.details == [ "EVENTS_LOST" ]:
            print "Caught EVENTS_LOST; should reregister"

Language bindings

C

The SDK includes the source to the C language binding in the directory XenServer-SDK/libxenserver/src together with a Makefile which compiles the binding into a library. Every API object is associated with a header file which contains declarations for all that object’s API functions; for example the type definitions and functions required to invoke VM operations are all contained in xen_vm.h.

C binding dependencies

The following simple examples are included with the C bindings:

• test_vm_async_migrate: demonstrates how to use asynchronous API calls to migrate running VMs from a slave host to the pool master.

• test_vm_ops: demonstrates how to query the capabilities of a host, create a VM, attach a fresh blank disk image to the VM and then perform various powercycle operations;

• test_failures: demonstrates how to translate error strings into enum_xen_api_failure, and vice versa;

• test_event_handling: demonstrates how to listen for events on a connection.

• test_enumerate: demonstrates how to enumerate the various API objects.

C#

The C# bindings are contained within the directory XenServer-SDK/XenServer.NET and include project files suitable for building under Microsoft Visual Studio. Every API object is associated with one C# file; for example the functions implementing the VM operations are contained within the file VM.cs.

C# binding dependencies

Three examples are included with the C# bindings in the directory XenServer-SDK/XenServer.NET/samples as separate projects of the XenSdkSample.sln solution:

• GetVariousRecords: logs into a XenServer Host and displays information about hosts, storage and virtual machines;

• GetVmRecords: logs into a XenServer Host and lists all the VM records;

• VmPowerStates: logs into a XenServer Host, finds a VM and takes it through the various power states. Requires a shut-down VM to be already installed.

Java

The Java bindings are contained within the directory XenServer-SDK/XenServerJava and include project files suitable for building under Microsoft Visual Studio. Every API object is associated with one Java file; for example the functions implementing the VM operations are contained within the file VM.java.

Java binding dependencies

Running the main file XenServer-SDK/XenServerJava/samples/RunTests.java will run a series of examples included in the same directory:

• AddNetwork: Adds a new internal network not attached to any NICs;

• SessionReuse: Demonstrates how a Session object can be shared between multiple Connections;

• AsyncVMCreate: Makes asynchronously a new VM from a built-in template, starts and stops it;

• VdiAndSrOps: Performs various SR and VDI tests, including creating a dummy SR;

• CreateVM: Creates a VM on the default SR with a network and DVD drive;

• DeprecatedMethod: Tests a warning is displayed wehn a deprecated API method is called;

• GetAllRecordsOfAllTypes: Retrieves all the records for all types of objects;

• SharedStorage: Creates a shared NFS SR;

• StartAllVMs: Connects to a host and tries to start each VM on it.

PowerShell

The PowerShell bindings are contained within the directory XenServer-SDK/XenServerPowerShell. We provide the PowerShell module XenServerPSModule and source code exposing the XenServer API as Windows PowerShell cmdlets.

PowerShell binding dependencies

These example scripts are included with the PowerShell bindings in the directory XenServer-SDK/XenServerPowerShell/samples:

• AutomatedTestCore.ps1: demonstrates how to log into a XenServer host, create a storage repository and a VM, and then perform various powercycle operations;

• HttpTest.ps1: demonstrates how to log into a XenServer host, create a VM, and then perform operations such as VM importing and exporting, patch upload, and retrieval of performance statistics.

Python

The python bindings are contained within a single file: XenServer-SDK/XenServerPython/XenAPI.py.

Python binding dependencies

|:–|:–| |Platform supported:|Linux| |Library:|XenAPI.py| |Dependencies:|None|

The SDK includes 7 python examples:

• fixpbds.py - reconfigures the settings used to access shared storage;

• install.py - installs a Debian VM, connects it to a network, starts it up and waits for it to report its IP address;

• license.py - uploads a fresh license to a XenServer Host;

• permute.py - selects a set of VMs and uses XenMotion to move them simultaneously between hosts;

• powercycle.py - selects a set of VMs and powercycles them;

• shell.py - a simple interactive shell for testing;

• vm_start_async.py - demonstrates how to invoke operations asynchronously;

• watch-all-events.py - registers for all events and prints details when they occur.

Command Line Interface (CLI)

Besides using raw XML-RPC or one of the supplied language bindings, third-party software developers may integrate with XenServer Hosts by using the XE command line interface xe. The xe CLI is installed by default on XenServer hosts; a stand-alone remote CLI is also available for Linux. On Windows, the xe.exe CLI executable is installed along with XenCenter.

CLI dependencies

|:–|:–| |Platform supported:|Linux and Windows| |Library:|None| |Binary:|xe (xe.exe on Windows)| |Dependencies:|None|

The CLI allows almost every API call to be directly invoked from a script or other program, silently taking care of the required session management. The XE CLI syntax and capabilities are described in detail in the XenServer Administrator’s Guide. For additional resources and examples, visit the Citrix Knowledge Center.

Note

When running the CLI from a XenServer Host console, tab-completion of both command names and arguments is available.

Complete application examples

This section describes two complete examples of real programs using the API.

Simultaneously migrating VMs using XenMotion

This python example (contained in XenServer-SDK/XenServerPython/samples/permute.py) demonstrates how to use XenMotion to move VMs simultaneously between hosts in a Resource Pool. The example makes use of asynchronous API calls and shows how to wait for a set of tasks to complete.

The program begins with some standard boilerplate and imports the API bindings module

import sys, time
import XenAPI

Next the commandline arguments containing a server URL, username, password and a number of iterations are parsed. The username and password are used to establish a session which is passed to the function main, which is called multiple times in a loop. Note the use of try: finally: to make sure the program logs out of its session at the end.

if __name__ == "__main__":
    if len(sys.argv) <> 5:
        print "Usage:"
        print sys.argv[0], " <url> <username> <password> <iterations>"
        sys.exit(1)
    url = sys.argv[1]
    username = sys.argv[2]
    password = sys.argv[3]
    iterations = int(sys.argv[4])
    # First acquire a valid session by logging in:
    session = XenAPI.Session(url)
    session.xenapi.login_with_password(username, password, "2.3",
                                       "Example migration-demo v0.1")
    try:
        for i in range(iterations):
            main(session, i)
    finally:
        session.xenapi.session.logout()

The main function examines each running VM in the system, taking care to filter out control domains (which are part of the system and not controllable by the user). A list of running VMs and their current hosts is constructed.

def main(session, iteration):
    # Find a non-template VM object
    all = session.xenapi.VM.get_all()
    vms = []
    hosts = []
    for vm in all:
        record = session.xenapi.VM.get_record(vm)
        if not(record["is_a_template"]) and \
           not(record["is_control_domain"]) and \
           record["power_state"] == "Running":
            vms.append(vm)
            hosts.append(record["resident_on"])
    print "%d: Found %d suitable running VMs" % (iteration, len(vms))

Next the list of hosts is rotated:

# use a rotation as a permutation
    hosts = [hosts[-1]] + hosts[:(len(hosts)-1)]

Each VM is then moved using XenMotion to the new host under this rotation (i.e. a VM running on host at position 2 in the list will be moved to the host at position 1 in the list etc.) In order to execute each of the movements in parallel, the asynchronous version of the VM.pool_migrate is used and a list of task references constructed. Note the live flag passed to the VM.pool_migrate; this causes the VMs to be moved while they are still running.

tasks = []
    for i in range(0, len(vms)):
        vm = vms[i]
        host = hosts[i]
        task = session.xenapi.Async.VM.pool_migrate(vm, host, { "live": "true" })
        tasks.append(task)

The list of tasks is then polled for completion:

finished = False
    records = {}
    while not(finished):
        finished = True
        for task in tasks:
            record = session.xenapi.task.get_record(task)
            records[task] = record
            if record["status"] == "pending":
                finished = False
        time.sleep(1)

Once all tasks have left the pending state (i.e. they have successfully completed, failed or been cancelled) the tasks are polled once more to see if they all succeeded:

allok = True
    for task in tasks:
        record = records[task]
        if record["status"] <> "success":
            allok = False

If any one of the tasks failed then details are printed, an exception is raised and the task objects left around for further inspection. If all tasks succeeded then the task objects are destroyed and the function returns.

if not(allok):
        print "One of the tasks didn't succeed at", \
            time.strftime("%F:%HT%M:%SZ", time.gmtime())
        idx = 0
        for task in tasks:
            record = records[task]
            vm_name = session.xenapi.VM.get_name_label(vms[idx])
            host_name = session.xenapi.host.get_name_label(hosts[idx])
            print "%s : %12s %s -> %s [ status: %s; result = %s; error = %s ]" % \
                  (record["uuid"], record["name_label"], vm_name, host_name,      \
                   record["status"], record["result"], repr(record["error_info"]))
            idx = idx + 1
        raise "Task failed"
    else:
        for task in tasks:
            session.xenapi.task.destroy(task)

Cloning a VM using the XE CLI

This example is a bash script which uses the XE CLI to clone a VM taking care to shut it down first if it is powered on.

The example begins with some boilerplate which first checks if the environment variable XE has been set: if it has it assumes that it points to the full path of the CLI, else it is assumed that the XE CLI is on the current path. Next the script prompts the user for a server name, username and password:

# Allow the path to the 'xe' binary to be overridden by the XE environment variable
if [ -z "${XE}" ]; then
  XE=xe
fi

if [ ! -e "${HOME}/.xe" ]; then
  read -p "Server name: " SERVER
  read -p "Username: " USERNAME
  read -p "Password: " PASSWORD
  XE="${XE} -s ${SERVER} -u ${USERNAME} -pw ${PASSWORD}"
fi

Next the script checks its commandline arguments. It requires exactly one: the UUID of the VM which is to be cloned:

# Check if there's a VM by the uuid specified
${XE} vm-list params=uuid | grep -q " ${vmuuid}$"
if [ $? -ne 0 ]; then
        echo "error: no vm uuid \"${vmuuid}\" found"
        exit 2
fi

The script then checks the power state of the VM and if it is running, it attempts a clean shutdown. The event system is used to wait for the VM to enter state “Halted”.

Note

The XE CLI supports a command-line argument --minimal which causes it to print its output without excess whitespace or formatting, ideal for use from scripts. If multiple values are returned they are comma-separated.

# Check the power state of the vm
name=$(${XE} vm-list uuid=${vmuuid} params=name-label --minimal)
state=$(${XE} vm-list uuid=${vmuuid} params=power-state --minimal)
wasrunning=0

# If the VM state is running, we shutdown the vm first
if [ "${state}" = "running" ]; then
        ${XE} vm-shutdown uuid=${vmuuid}
        ${XE} event-wait class=vm power-state=halted uuid=${vmuuid}
        wasrunning=1
fi

The VM is then cloned and the new VM has its name_label set to cloned_vm.

# Clone the VM
newuuid=$(${XE} vm-clone uuid=${vmuuid} new-name-label=cloned_vm)

Finally, if the original VM had been running and was shutdown, both it and the new VM are started.

# If the VM state was running before cloning, we start it again
# along with the new VM.
if [ "$wasrunning" -eq 1 ]; then
        ${XE} vm-start uuid=${vmuuid}
        ${XE} vm-start uuid=${newuuid}
fi

XenAPI Reference

XenAPI Classes

Click on a class to view the associated fields and messages.

Classes, Fields and Messages

Classes have both fields and messages. Messages are either implicit or explicit where an implicit message is one of:

• a constructor (usually called "create");
• a destructor (usually called "destroy");
• "get_by_name_label";
• "get_by_uuid";
• "get_record";
• "get_all"; and
• "get_all_records".

Explicit messages include all the rest, more class-specific messages (e.g. "VM.start", "VM.clone")

Every field has at least one accessor depending both on its type and whether it is read-only or read-write. Accessors for a field named "X" would be a proper subset of:

• set_X: change the value of field X (only if it is read-write);
• get_X: retrieve the value of field X;
• add_X: add a key/value pair (for fields of type set);
• remove_X: remove a key (for fields of type set);
• add_to_X: add a key/value pair (for fields of type map); and
• remove_from_X: remove a key (for fields of type map).