XenSource DL385 - ProLiant - G5 User manual

XenEnterprise Management API API Revision 1.1
XenEnterprise Management API
Version: API Revision 1.1
Date: 16th August 2007
Copyright c 2007 XenSource Inc, All Rights Reserved.

Contents
1 Introduction 5
1.1 RPCs associated with fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 RPCs associated with classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.1 Additional RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Wire Protocol for Remote API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.1 Note on References vs UUIDs . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.2 Return Values/Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 Making XML-RPC Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.1 Transport Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.2 Session Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.3 Synchronous and Asynchronous invocation . . . . . . . . . . . . . . . . . . 9
1.5 Example interactive session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.6 VM Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.7 VM boot parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2 API Reference 14
2.1 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.2 Relationships Between Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2.1 List of bound fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.3 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.3.1 Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.3.2 Higher order types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.3.3 Enumeration types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.4 Class: session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.4.1 Fields for class: session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.4.2 RPCs associated with class: session . . . . . . . . . . . . . . . . . . . . . . 21
2.5 Class: task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.5.1 Fields for class: task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.5.2 RPCs associated with class: task . . . . . . . . . . . . . . . . . . . . . . . . 27
2.6 Class: event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.6.1 Fields for class: event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.6.2 RPCs associated with class: event . . . . . . . . . . . . . . . . . . . . . . . 35
2.7 Class: pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.7.1 Fields for class: pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.7.2 RPCs associated with class: pool . . . . . . . . . . . . . . . . . . . . . . . . 37
2.8 Class: pool patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
2.8.1 Fields for class: pool patch . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
2.8.2 RPCs associated with class: pool patch . . . . . . . . . . . . . . . . . . . . 47
2.9 Class: VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
2.9.1 Fields for class: VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
2.9.2 RPCs associated with class: VM . . . . . . . . . . . . . . . . . . . . . . . . 56
2.10 Class: VM metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
2.10.1 Fields for class: VM metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
2

CONTENTS CONTENTS
2.10.2 RPCs associated with class: VM metrics . . . . . . . . . . . . . . . . . . . . 99
2.11 Class: VM guest metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
2.11.1 Fields for class: VM guest metrics . . . . . . . . . . . . . . . . . . . . . . . 105
2.11.2 RPCs associated with class: VM guest metrics . . . . . . . . . . . . . . . . 105
2.12 Class: host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
2.12.1 Fields for class: host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
2.12.2 RPCs associated with class: host . . . . . . . . . . . . . . . . . . . . . . . . 111
2.13 Class: host crashdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
2.13.1 Fields for class: host crashdump . . . . . . . . . . . . . . . . . . . . . . . . 133
2.13.2 RPCs associated with class: host crashdump . . . . . . . . . . . . . . . . . 133
2.14 Class: host patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
2.14.1 Fields for class: host patch . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
2.14.2 RPCs associated with class: host patch . . . . . . . . . . . . . . . . . . . . 138
2.15 Class: host metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
2.15.1 Fields for class: host metrics . . . . . . . . . . . . . . . . . . . . . . . . . . 145
2.15.2 RPCs associated with class: host metrics . . . . . . . . . . . . . . . . . . . 145
2.16 Class: host cpu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
2.16.1 Fields for class: host cpu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
2.16.2 RPCs associated with class: host cpu . . . . . . . . . . . . . . . . . . . . . 148
2.17 Class: network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
2.17.1 Fields for class: network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
2.17.2 RPCs associated with class: network . . . . . . . . . . . . . . . . . . . . . . 154
2.18 Class: VIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
2.18.1 Fields for class: VIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
2.18.2 RPCs associated with class: VIF . . . . . . . . . . . . . . . . . . . . . . . . 162
2.19 Class: VIF metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
2.19.1 Fields for class: VIF metrics . . . . . . . . . . . . . . . . . . . . . . . . . . 173
2.19.2 RPCs associated with class: VIF metrics . . . . . . . . . . . . . . . . . . . 173
2.20 Class: PIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
2.20.1 Fields for class: PIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
2.20.2 RPCs associated with class: PIF . . . . . . . . . . . . . . . . . . . . . . . . 176
2.21 Class: PIF metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
2.21.1 Fields for class: PIF metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
2.21.2 RPCs associated with class: PIF metrics . . . . . . . . . . . . . . . . . . . . 188
2.22 Class: Bond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
2.22.1 Fields for class: Bond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
2.22.2 RPCs associated with class: Bond . . . . . . . . . . . . . . . . . . . . . . . 194
2.23 Class: VLAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
2.23.1 Fields for class: VLAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
2.23.2 RPCs associated with class: VLAN . . . . . . . . . . . . . . . . . . . . . . . 199
2.24 Class: SM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
2.24.1 Fields for class: SM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
2.24.2 RPCs associated with class: SM . . . . . . . . . . . . . . . . . . . . . . . . 204
2.25 Class: SR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
2.25.1 Fields for class: SR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
2.25.2 RPCs associated with class: SR . . . . . . . . . . . . . . . . . . . . . . . . . 211
2.26 Class: VDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
2.26.1 Fields for class: VDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
2.26.2 RPCs associated with class: VDI . . . . . . . . . . . . . . . . . . . . . . . . 227
2.27 Class: VBD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
2.27.1 Fields for class: VBD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
2.27.2 RPCs associated with class: VBD . . . . . . . . . . . . . . . . . . . . . . . 245
2.28 Class: VBD metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
2.28.1 Fields for class: VBD metrics . . . . . . . . . . . . . . . . . . . . . . . . . . 261
3

CONTENTS CONTENTS
2.28.2 RPCs associated with class: VBD metrics . . . . . . . . . . . . . . . . . . . 261
2.29 Class: PBD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
2.29.1 Fields for class: PBD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
2.29.2 RPCs associated with class: PBD . . . . . . . . . . . . . . . . . . . . . . . 264
2.30 Class: crashdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
2.30.1 Fields for class: crashdump . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
2.30.2 RPCs associated with class: crashdump . . . . . . . . . . . . . . . . . . . . 270
2.31 Class: VTPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
2.31.1 Fields for class: VTPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
2.31.2 RPCs associated with class: VTPM . . . . . . . . . . . . . . . . . . . . . . 274
2.32 Class: console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
2.32.1 Fields for class: console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
2.32.2 RPCs associated with class: console . . . . . . . . . . . . . . . . . . . . . . 277
2.33 Class: user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
2.33.1 Fields for class: user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
2.33.2 RPCs associated with class: user . . . . . . . . . . . . . . . . . . . . . . . . 282
2.34 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
2.34.1 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
4

Chapter 1
Introduction
This document defines the XenEnterprise Management API—an API for remotely configuring and
controlling virtualised guests running on a Xen-enabled cluster.
The API is presented here as a set of Remote Procedure Calls, with a wire format based upon
XML-RPC. No specific language bindings are prescribed, although examples will be 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:
•ROrun : the field is Read Only. Furthermore, its value is automatically computed at runtime.
For example: current CPU load and disk IO throughput.
•ROins : 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.
A full list of types is given in Chapter 2. However, there are three types that require explicit
mention:
•tRef : signifies a reference to an object of type t.
•tSet: signifies a set containing values of type t.
•(t1, t2)Map: signifies a mapping from values of type t1to values of type t2.
Note that there are a number of cases where Refs are doubly linked—e.g. 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 explicitly lists 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 existance
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).
5

1.1. RPCS ASSOCIATED WITH FIELDS CHAPTER 1. INTRODUCTION
1.1 RPCs associated with fields
Each field, f, has an RPC accessor associated with it that returns f’s value:
•“get f(Ref x)”: takes a Ref that refers to an object and returns the value of f.
Each field, f, with attribute RW and whose outermost type is Set has the following additional
RPCs associated with it:
•an “add to f(Ref x, v)” RPC adds a new element v to the set1;
•a “remove from f(Ref x, v)” RPC removes element vfrom the set;
Each field, f, with attribute RW and whose outermost type is Map has the following additional
RPCs associated with it:
•an “add to f(Ref x, k, v)” RPC adds new pair (k, v) to the mapping stored in fin
object x. Adding a new pair for duplicate key, k, overwrites any previous mapping for k.
•a “remove from f(Ref x, k)” RPC removes the pair with key kfrom the mapping stored
in fin object x.
Each field whose outermost type is neither Set nor Map, but whose attribute is RW has an RPC
acessor associated with it that sets its value:
•For RW (Read/Write), a “set f(Ref x, v)” RPC function is also provided. This sets field
fon object xto value v.
1.2 RPCs associated with classes
•Each class has a constructor RPC named “create” that takes as parameters all fields marked
RW and ROins . 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)” RPC that returns
a set of objects of that class that have the specified label.
•Each class has a “destroy(Ref x)” RPC that explicitly deletes the persistent object spec-
ified by xfrom the system. This is a non-cascading delete – if the object being removed is
referenced by another object then the destroy call will fail.
1.2.1 Additional RPCs
As well as the RPCs enumerated above, some 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.
1Since sets cannot contain duplicate values this operation has no action in the case that vwas already in the
set.
6

1.3. WIRE PROTOCOL FOR REMOTE API CALLS CHAPTER 1. INTRODUCTION
1.3 Wire Protocol for Remote API Calls
API calls are sent over a network to a Xen-enabled host using the XML-RPC protocol. In this
Section we describe how the higher-level types used in our API Reference are mapped to primitive
XML-RPC types.
In our API Reference we specify the signatures of API functions in the following style:
(ref_vm Set) VM.get_all()
This specifies that the function with name VM.get all takes no parameters and returns a Set of
ref vms. These types are mapped onto XML-RPC types in a straight-forward manner:
•Floats, Bools, DateTimes and Strings 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, etc).
•ints are all assumed to be 64-bit in our API and are 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, a value of destroy of type
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 kand 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 kis a String,
Ref, or Int, and in each case the keys of the maps are stringified as above. For example,
the (String, double) Map containing a 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>
7

1.3. WIRE PROTOCOL FOR REMOTE API CALLS CHAPTER 1. INTRODUCTION
<name>John</name>
<value><double>1.2</double></value>
</member>
</struct>
</value>
•our Void type is transmitted as an empty string.
1.3.1 Note on References vs UUIDs
References are opaque types — encoded as XML-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 names 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 lookup 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, u, and returns an opaque reference to the
server-side object that has UUID=u;
•Aget uuid function (a regular “field getter” RPC) that takes an opaque reference, r, and
returns the UUID of the server-side object that is referenced by r.
1.3.2 Return Values/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 Status was set to Success then the Struct contains a second element named Value:
•The element of the struct named Value contains the function’s return value.
In the case where Status is set to 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 remainder of the array are strings representing
error parameters relating to that code.
For example, an XML-RPC return value from the host.get resident VMs function above may
look like this:
<struct>
<member>
<name>Status</name>
<value>Success</value>
</member>
8

1.4. MAKING XML-RPC CALLS CHAPTER 1. INTRODUCTION
<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>
1.4 Making XML-RPC Calls
1.4.1 Transport Layer
The following transport layers are currently supported:
•HTTP/S for remote administration
•HTTP over Unix domain sockets for local administration
1.4.2 Session Layer
The XML-RPC interface is session-based; before you can make arbitrary RPC calls you must login
and initiate a session. For example:
session_id session.login_with_password(string uname, string pwd)
Where uname and password refer to your username and password respectively, as defined by the
Xen administrator. The session id returned by session.login with password is passed to
subequent RPC calls as an authentication token.
A session can be terminated with the session.logout function:
void session.logout(session_id session)
1.4.3 Synchronous and Asynchronous invocation
Each method call (apart from methods on “Session” and “Task” objects and “getters” and “set-
ters” 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 in Section 1.3.2.
Only synchronous API calls are listed explicitly in this document. All asynchronous versions are
in the special Async namespace. For example, synchronous call VM.clone(...) (described in
Chapter 2) has an asynchronous counterpart, Async.VM.clone(...), that is non-blocking.
Instead of returning its result directly, an asynchronous RPC call returns a task-id; this identifier
is subsequently used to track the status of a running asynchronous RPC. Note that an asychronous
call may fail immediately, before a task-id has even been created—to represent this eventuality,
the returned task-id is wrapped in an XML-RPC struct with a Status,ErrorDescription and
Value fields, exactly as specified in Section 1.3.2.
The task-id is provided in the Value field if Status is set to Success.
The RPC call
(ref_task Set) Task.get_all(session_id s)
9

1.5. EXAMPLE INTERACTIVE SESSION CHAPTER 1. INTRODUCTION
returns a set of all task IDs known to the system. The status (including any returned result and
error codes) of these tasks 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.
1.5 Example interactive session
This section describes how an interactive session might look, using the python XML-RPC client
library.
First, initialise python and import the library xmlrpclib:
\$ python2.4
...
>>> import xmlrpclib
Create a python object referencing the remote server:
>>> xen = xmlrpclib.Server("https://localhost:443")
Acquire a session reference by logging in with a username and password (error-handling ommitted
for brevity; the session reference is returned under the key ’Value’ in the resulting dictionary)
>>> session = xen.session.login_with_password("user", "passwd")[’Value’]
When serialised, this call looks like the following:
<?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>
</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 the
future, 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’]}
10

1.5. EXAMPLE INTERACTIVE SESSION CHAPTER 1. INTRODUCTION
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 internationalised.
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’]
’XenSource P2V Server’
To retrieve all the VM records in a single call:
>>> records = xen.VM.get_all_records(session)[’Value’]
>>> records.keys()
[’OpaqueRef:1’, ’OpaqueRef:2’, ’OpaqueRef:3’, ’OpaqueRef:4’ ]
>>> records[’OpaqueRef:1’][’name_label’]
’RHEL 4.1 Autoinstall Template’
11

1.6. VM LIFECYCLE CHAPTER 1. INTRODUCTION
powered down
paused
start(paused=true)
running
start(paused=false)
resume
suspended
suspend
cleanShutdown /
hardShutdown
pause
suspend
resume(paused=true)
resume(paused=false)
Figure 1.1: VM Lifecycle
1.6 VM Lifecycle
Figure 1.1 shows the states that a VM can be in and the API calls that can be used to move the
VM between these states.
1.7 VM boot parameters
The VM class contains a number of fields that control the way in which the VM is booted. With
reference to the fields defined in the VM class (see later in this document), this section outlines
the boot options available and the mechanisms provided for controlling them.
VM booting is controlled by setting one of the two mutually exclusive groups: “PV”, and “HVM”.
If HVM.boot policy is the empty string, then paravirtual domain building and booting will be used;
otherwise the VM will be loaded as an HVM domain, and booted using an emulated BIOS.
When paravirtual booting is in use, the PV/bootloader field indicates the bootloader to use. It
may be “pygrub”, in which case the platform’s default installation of pygrub will be used, or
a full path within the control domain to some other bootloader. The other fields, PV/kernel,
PV/ramdisk, PV/args and PV/bootloader args will be passed to the bootloader unmodified, and
interpretation of those fields is then specific to the bootloader itself, including the possibility that
the bootloader will ignore some or all of those given values. Finally the paths of all bootable disks
are added to the bootloader commandline (a disk is bootable if its VBD has the bootable flag
set). There may be zero, one or many bootable disks; the bootloader decides which disk (if any)
to boot from.
If the bootloader is pygrub, then the menu.lst is parsed if present in the guest’s filesystem, otherwise
the specified kernel and ramdisk are used, or an autodetected kernel is used if nothing is specified
and autodetection is possible. PV/args is appended to the kernel command line, no matter which
mechanism is used for finding the kernel.
If PV/bootloader is empty but PV/kernel is specified, then the kernel and ramdisk values will be
treated as paths within the control domain. If both PV/bootloader and PV/kernel are empty,
then the behaviour is as if PV/bootloader was specified as “pygrub”.
When using HVM booting, HVM/boot policy and HVM/boot params specify the boot handling.
12

1.7. VM BOOT PARAMETERS CHAPTER 1. INTRODUCTION
Only one policy is currently defined: “BIOS order”. In this case, HVM/boot params should
contain one key-value pair “order” = “N” where N is the string that will be passed to QEMU.
13

Chapter 2
API Reference
2.1 Classes
The following classes are defined:
Name Description
session A session
task A long-running asynchronous task
event Asynchronous event registration and handling
pool Pool-wide information
pool patch Pool-wide patches
VM A virtual machine (or ’guest’)
VM metrics The metrics associated with a VM
VM guest metrics The metrics reported by the guest (as opposed to inferred from
outside)
host A physical host
host crashdump Represents a host crash dump
host patch Represents a patch stored on a server
host metrics The metrics associated with a host
host cpu A physical CPU
network A virtual network
VIF A virtual network interface
VIF metrics The metrics associated with a virtual network device
PIF A physical network interface (note separate VLANs are repre-
sented as several PIFs)
PIF metrics The metrics associated with a physical network interface
Bond
VLAN A VLAN mux/demux
SM A storage manager plugin
SR A storage repository
VDI A virtual disk image
VBD A virtual block device
VBD metrics The metrics associated with a virtual block device
PBD The physical block devices through which hosts access SRs
crashdump A VM crashdump
VTPM A virtual TPM device
console A console
user A user of the system
14

2.2. RELATIONSHIPS BETWEEN CLASSES CHAPTER 2. API REFERENCE
2.2 Relationships Between Classes
Fields that are bound together are shown in the following table:
object.field object.field relationship
PIF.bond slave of Bond.slaves one-to-many
PIF.bond master of Bond.master many-to-one
PIF.VLAN slave of VLAN.tagged PIF many-to-one
host.PBDs PBD.host many-to-one
SR.PBDs PBD.SR many-to-one
VDI.VBDs VBD.VDI many-to-one
VDI.crash dumps crashdump.VDI many-to-one
VBD.VM VM.VBDs one-to-many
crashdump.VM VM.crash dumps one-to-many
VIF.VM VM.VIFs one-to-many
VIF.network network.VIFs one-to-many
PIF.host host.PIFs one-to-many
PIF.network network.PIFs one-to-many
SR.VDIs VDI.SR many-to-one
VTPM.VM VM.VTPMs one-to-many
console.VM VM.consoles one-to-many
host.resident VMs VM.resident on many-to-one
host.host CPUs host cpu.host many-to-one
host.crashdumps host crashdump.host many-to-one
host.patches host patch.host many-to-one
pool patch.host patches host patch.pool patch many-to-one
The following represents bound fields (as specified above) diagramatically, using crows-foot nota-
tion to specify one-to-one, one-to-many or many-to-many relationships:
session
host
user
VM
VM_metrics
VM_guest_metrics
console
PBD
host_metrics
host_cpu
network VIF
VIF_metrics
PIF
PIF_metrics
SR
VDI
VBD
VBD_metrics
PBD_metrics
VTPM
15

2.3. TYPES CHAPTER 2. API REFERENCE
2.2.1 List of bound fields
2.3 Types
2.3.1 Primitives
The following primitive types are used to specify methods and fields in the API Reference:
Type Description
String text strings
Int 64-bit integers
Float IEEE double-precision floating-point numbers
Bool boolean
DateTime date and timestamp
Ref (object name) reference to an object of class name
2.3.2 Higher order types
The following type constructors are used:
Type Description
List (t) an arbitrary-length list of elements of type t
Map (a →b) a table mapping values of type a to values of type b
2.3.3 Enumeration types
The following enumeration types are used:
enum event operation
add An object has been created
del An object has been deleted
mod An object has been modified
enum console protocol
vt100 VT100 terminal
rfb Remote FrameBuffer protocol (as used in VNC)
rdp Remote Desktop Protocol
enum vbd operations
attach Attempting to attach this VBD to a VM
eject Attempting to eject the media from this VBD
insert Attempting to insert new media into this VBD
plug Attempting to hotplug this VBD
unplug Attempting to hot unplug this VBD
unplug force Attempting to forcibly unplug this VBD
16

2.3. TYPES CHAPTER 2. API REFERENCE
enum vdi operations
scan Scanning backends for new or deleted VDIs
clone Cloning the VDI
copy Copying the VDI
resize Resizing the VDI
snapshot Snapshotting the VDI
destroy Destroying the VDI
forget Forget about the VDI
force unlock Forcibly unlocking the VDI
enum storage operations
scan Scanning backends for new or deleted VDIs
destroy Destroying the SR
forget Forgetting about SR
plug Plugging a PBD into this SR
unplug Unplugging a PBD from this SR
vdi create Creating a new VDI
vdi introduce Introducing a new VDI
vdi destroy Destroying a VDI
vdi resize Resizing a VDI
vdi clone Cloneing a VDI
vdi snapshot Snapshotting a VDI
enum vif operations
attach Attempting to attach this VIF to a VM
plug Attempting to hotplug this VIF
unplug Attempting to hot unplug this VIF
enum network operations
attaching Indicates this network is attaching to a VIF or PIF
enum host allowed operations
provision Indicates this host is able to provision another VM
evacuate Indicates this host is evacuating
enum vm power state
17

2.3. TYPES CHAPTER 2. API REFERENCE
Halted VM is offline and not using any resources
Paused All resources have been allocated but the VM itself is paused and its vCPUs are not running
Running Running
Suspended VM state has been saved to disk and it is nolonger running. Note that disks remain in-use while the
Unknown Some other unknown state
enum after apply guidance
restartHVM This patch requires HVM guests to be restarted once applied.
restartPV This patch requires PV guests to be restarted once applied.
restartHost This patch requires the host to be restarted once applied.
restartXAPI This patch requires XAPI to be restarted once applied.
enum task status type
pending task is in progress
success task was completed successfully
failure task has failed
cancelling task is being cancelled
cancelled task has been cancelled
enum task allowed operations
cancel refers to the operation “cancel”
enum vm operations
clone refers to the operation “clone”
copy refers to the operation “copy”
provision refers to the operation “provision”
start refers to the operation “start”
start on refers to the operation “start on”
pause refers to the operation “pause”
unpause refers to the operation “unpause”
clean shutdown refers to the operation “clean shutdown”
clean reboot refers to the operation “clean reboot”
hard shutdown refers to the operation “hard shutdown”
power state reset refers to the operation “power state reset”
hard reboot refers to the operation “hard reboot”
suspend refers to the operation “suspend”
csvm refers to the operation “csvm”
resume refers to the operation “resume”
resume on refers to the operation “resume on”
pool migrate refers to the operation “pool migrate”
18

2.3. TYPES CHAPTER 2. API REFERENCE
migrate refers to the operation “migrate”
statistics refers to the operation “statistics”
get boot record refers to the operation “get boot record”
send sysrq refers to the operation “send sysrq”
send trigger refers to the operation “send trigger”
changing memory live Changing the memory settings
changing shadow memory live Changing the shadow memory settings
changing VCPUs live Changing either the VCPUs number or VCPUs params
assert operation valid
update allowed operations
make into template Turning this VM into a template
import importing a VM from a network stream
export exporting a VM to a network stream
destroy refers to the act of uninstalling the VM
enum on normal exit
destroy destroy the VM state
restart restart the VM
enum on crash behaviour
destroy destroy the VM state
coredump and destroy record a coredump and then destroy the VM state
restart restart the VM
coredump and restart record a coredump and then restart the VM
preserve leave the crashed VM paused
rename restart rename the crashed VM and start a new copy
enum ip configuration mode
None Do not acquire an IP address
DHCP Acquire an IP address by DHCP
Static Static IP address configuration
enum vdi type
system a disk that may be replaced on upgrade
user a disk that is always preserved on upgrade
ephemeral a disk that may be reformatted on upgrade
suspend a disk that stores a suspend image
crashdump a disk that stores VM crashdump information
19

2.3. TYPES CHAPTER 2. API REFERENCE
enum vbd mode
RO only read-only access will be allowed
RW read-write access will be allowed
enum vbd type
CD VBD will appear to guest as CD
Disk VBD will appear to guest as disk
20