XenSource XenEnterprise Management API User Manual

XenEnterprise Management API API Revision 1.1

XenEnterprise Management API

Version: API Revision 1.1

Date: 16th August 2007

Contents

1 Introduction 5

1.1 RPCs associated with ﬁelds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 Refere nce s 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 ﬁelds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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: ta sk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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: p ool . . . . . . . . . . . . . . . . . . . . . . . . 37

2.8 Class: pool

2.8.1 Fields for class: pool patch . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

2.8.2 RPCs associated with class: p ool 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

2.10.1 Fields for class: VM

patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

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 . . . . . . . . . . . . . . . . . . . . . . 1 54

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 . . . . . . . . . . . . . . . . . . . . 1 88

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

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 6

Chapter 1

Introduction

This document deﬁnes the XenEnterprise Management API—an API for remotely conﬁguring 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 speciﬁc language bindings are prescribed, although examples will be given in the python programming language. Although we adopt some terminology from object-oriented pro gramming, 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 ﬁelds set to speciﬁc values. Objects are persistent and exist on the server-side. Clients may obtain opaque references to these server-side objects and then access their ﬁelds via get/set RPCs. For each class we specify a list of ﬁelds along with their types and qualiﬁers. A qualiﬁer is one of:

• RO

• RW : the ﬁeld 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 tha t require explicit mention:

• t Ref : signiﬁes a reference to an object of type t.

• t Set: signiﬁes a set containing values of type t.

• (t1, t2) Map: signiﬁes 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 ﬁeld called VIFs of type (VIF Ref ) Set ; this ﬁeld lists the network interfaces attached to a particular VM. Similarly, the VIF class has a ﬁeld called VM of type (VM Ref ) which references the VM to which the interface is connected. These two ﬁelds are bound together, in the sense that creating a new VIF causes the VIFs ﬁeld of the corresponding VM object to be updated automatically. The API reference explicitly lists the ﬁelds that are bound together in this way. It also contains a diagram that shows relationships between classes. In this dia gram an edge signiﬁes the existance of a pair of ﬁelds tha t are bound together, using standard crows-foot notation to signify the type of relationship (e.g. one-many, many-many).

: the ﬁeld is Read Only. Furthermore, its value is automatically computed at runtime.

run

For example: current CPU load and disk IO throughput.

: the ﬁeld must be manually set when a new o b ject is created, but is then Read Only

ins

for the dur ation of the object’s life. For example, the maximum memory addressable by a guest is set before the guest boots.

1.1. RPCS ASSOCIATED WITH FIELDS CHAPTER 1. INTRODUCTION

1.1 RPCs associated with ﬁelds

Each ﬁeld, 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 ﬁeld, f, with attribute RW and whose outermost type is Set has the following additional RPCs associated with it:

• an “add

• a “remove

to f(Ref x, v)” RPC adds a new element v to the set1;

from f(Ref x, v)” RPC removes element v from the set;

Each ﬁeld, 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 f in

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 k from the mapping stored in f in object x.

Each ﬁeld 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/W rite), a “set

f(Ref x, v)” RPC function is also provided. This sets ﬁeld

f on object x to value v.

1.2 RPCs associated with classes

• Each c lass has a constructor RPC named “create” that takes as parameters all ﬁelds marked RW and RO

server-side with the speciﬁed ﬁeld values.

. The result of this RPC is that a new persistent object is created on the

ins

• Each class has a get

by uuid(uuid) RPC that returns the object of that class that has the

speciﬁed uuid.

• Each class that has a name

label ﬁeld has a “get by name label(name)” RPC that returns

a set of objects of that class that have the speciﬁed label.

• Each class has a “destroy(Ref x)” RPC that explicitly deletes the persistent object spec- iﬁed by x 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.

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 clo ning, suspending, starting etc. Such additional RPCs are described explicitly in the API reference.

Since sets cannot contain duplicate values this operation has no action in the case that v was already in the

set.

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 speciﬁes that the function with name VM.get 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 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.

• ﬁelds 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

• 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>

</array>

” types are opaque references, enco ded as the XML-RPC’s String type. Use rs of

normal exit, would be conveyed as:

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

<data>

</data>

all takes no parameters and returns a Set of

• 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 stringiﬁed as above. For example, the (String, double) Map containing a the mappings Mike → 2.3 and J ohn → 1.2 would be represented as :

<value>

1.3. WIRE PROTOCOL FOR REMOTE API CALLS CHAPTER 1. INTRODUCTION

</struct>

</value>

• our Void type is transmitted as an empty string.

1.3.1 Note on References vs UUIDs

References are opaque types — e ncoded as XML-RPC strings on the wire — understood only by the par ticula r server which generated them. Servers are free to choose any concrete representation they ﬁnd convenient; clients should not make any assumptions or attempt to parse the string contents. References are not guaranteed to be permanent identiﬁers 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 eq uality on objects by compar ing UUID strings. The API provides mechanisms for translating between UUIDs and opaque references. Each class that contains a UUID ﬁeld provides:

• A “get server-side object that has UUID=u;

• A get returns the UUID of the server-side object that is referenced by r.

by uuid” method that takes a UUID, u, and returns an opaque reference to the

uuid function (a regular “ﬁeld getter” RPC) that takes an opaque reference, r, and

1.3.2 Return Values/Status Codes

The return value of an RPC ca ll is an XML-RPC Struct.

• The ﬁrst 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 ﬁrst 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 look like this:

resident VMs function above may

<name>Status</name> <value>Success</value>

</member>

1.4. MAKING XML-RPC CALLS CHAPTER 1. INTRODUCTION

<name>Value</name> <value>

<array>

<data>

</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 s e ssion-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 deﬁned 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 “setters” derived from ﬁelds) 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 s peciﬁed 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 co unterpart, Async.VM.clone(...), that is non-blocking. Instead of returning its result directly, an asynchronous RPC call returns a task-id; this identiﬁer 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 ﬁelds, exactly as speciﬁed in Section 1.3.2. The task-id is provided in the Value ﬁeld if Status is set to Success. The RPC call

(ref_task Set) Task.get_all(session_id s)

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 ﬁelds 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 logg ing 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>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 a s 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 ﬁeld set to true. We can ﬁnd the subset of template VMs using a command like the following:

a template

>>> 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’]}

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 err ors are returned as structured data (rather than as XML-RPC faults), allowing them to be internationalised. Rather than querying ﬁelds individually, whole records may be returned at once. To retrieve the record of a single object as a python dictio nary:

>>> 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’

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 s tates.

1.7 VM boot parameters

The VM class contains a number of ﬁelds that control the way in which the VM is booted. With reference to the ﬁelds deﬁned in the VM class (see later in this document), this section outlines the boot options available and the mechanisms provided for controlling them. VM b ooting is controlled by setting one of the two mutually exclusive groups: “PV”, and “HVM”. If HVM.boot 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 ﬁeld 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 ﬁelds, PV/kernel, PV/ramdisk, PV/args and PV/bootloader interpretation of those ﬁelds is then speciﬁc 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 ﬂag set). There may be zero, one or many boota ble disks; the bootloader decides which disk (if any) to boot from. If the bootloader is pygrub, then the menu.lst is parsed if pres e nt in the guest’s ﬁlesystem, otherwise the speciﬁed kernel and ramdisk ar e used, or an autodetected kernel is used if nothing is speciﬁed and autodetection is possible. PV/args is appended to the kernel command line, no matter which mechanism is used fo r ﬁnding the kernel. If PV/bootloader is empty but PV/kernel is speciﬁed, 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 speciﬁed as “pygrub”. When using HVM booting, HVM/boot

policy is the empty string, then paravirtual domain building and booting will be used;

args will be passed to the bootloader unmodiﬁed, and

policy and HVM/boot params spec ify the boot handling.

1.7. VM BOOT PARAMETERS CHAPTER 1. INTRODUCTION

Only one policy is currently deﬁned: “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.

Chapter 2

API Reference

2.1 Classes

The following classes a re deﬁned:

Name Description

session A session task A long-running asynchronous ta sk event Asynchronous event reg istration 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 re ported 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

2.2. RELATIONSHIPS BETWEEN CLASSES CHAPTER 2. API REFERENCE

session

host

user

VM_metrics

VM_guest_metrics

console

PBD

host_metrics

host_cpu

network

VIF

VIF_metrics

PIF

PIF_metrics

VDI

VBD

VBD_metrics

PBD_metrics

VTPM

2.2 Relationships Between Classes

Fields that are bound together are shown in the following table:

object.ﬁeld object.ﬁeld 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 C PUs 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 ﬁelds (as speciﬁed above) diagramatically, using crows-foot notation to specify one-to-one, one-to-many or many-to-many relationships:

2.3. TYPES CHAPTER 2. API REFERENCE

2.2.1 List of bound ﬁelds

2.3 Types

2.3.1 P rimitives

The following primitive types are used to specify methods and ﬁelds in the API Reference:

Type Description String text strings Int 64-bit integers Float IEEE double-precision ﬂoating-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 E numeration types

The following enumeration types are used:

enum event operation

add An object has been cr e ated del An object has been deleted mod An object has been modiﬁed

enum console protocol

vt100 VT100 terminal rfb Remote FrameBuﬀer 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

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 ab out 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

2.3. TYPES CHAPTER 2. API REFERENCE

Halted VM is oﬄine 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 dis ks 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 P V 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 operatio n “cancel”

enum vm operations

clone refers to the operatio n “clone” copy refers to the operatio n “copy” provision refers to the operatio n “provision” start refers to the operatio n “start” start on refers to the operatio n “start on” pause refers to the operatio n “pause” unpause refers to the operatio n “unpause” clean shutdown refers to the operation “clean shutdown” clean reboot refers to the operatio n “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 operatio n “hard rebo ot” suspend refers to the operatio n “suspend” csvm refers to the operatio n “csvm” resume refers to the operatio n “resume” resume on refers to the operatio n “resume on” pool migrate refers to the operatio n “pool migrate”

2.3. TYPES CHAPTER 2. API REFERENCE

migrate refers to the operatio n “migrate” statistics refers to the operatio n “statistics” get boot record refers to the operation “get boot r e c ord” send sysrq refers to the operatio n “send sysrq” send trigger refers to the operatio n “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 s tate 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 conﬁguration

enum vdi type

system a disk that may be replaced on upgra de 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

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

2.4. CLASS: SESSION CHAPTER 2. API REFERENCE

2.4 Class: session

2.4.1 Fields for class: session

Name session Description Quals Field Type Description

run

RW other config (string → string) Map additional conﬁguration

2.4.2 RPCs associated w ith class: session

A session.

uuid string unique identiﬁer/object reference this host host ref Currently connected host this user user ref Currently connected user last active datetime Timestamp for last time session was

active

pool bool True if this session relates to a intra-

pool login, false otherwise

RPC name: login

with password

Overview:

Attempt to authenticate the user, returning a session reference if successful.

Signature:

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

Arguments:

type name description

string uname Username for login. string pwd Password for login. string version Client API version.

Return Type: session ref

reference of newly created session

Possible Error Codes: SESSION

AUTHENTICATION FAILED

RPC name: logout

Overview:

Log out o f a sess ion.

Signature:

void logout (session_id s)

Return Type: void

RPC name: change

password

Overview:

Change the account password; if your session is authenticated with root priviledges then the

pwd is validated and the new pwd is set regardless.

old

Signature:

2.4. CLASS: SESSION CHAPTER 2. API REFERENCE

void change_password (session_id s, string old_pwd, string new_pwd)

Arguments:

type name description

string old pwd Old password for account string new pwd New password for account

Return Type: void

RPC name: get

uuid

Overview:

Get the uuid ﬁeld of the given session.

Signature:

string get_uuid (session_id s, session ref self)

Arguments:

type name description

session ref self reference to the o bject

Return Type: string

value of the ﬁeld

RPC name: get

this host

Overview:

Get the this

host ﬁeld of the given session.

Signature:

(host ref) get_this_host (session_id s, session ref self)

Arguments:

type name description

session ref self reference to the o bject

Return Type: host ref

value of the ﬁeld

RPC name: get

this user

Overview:

Get the this

user ﬁeld of the given session.

Signature:

(user ref) get_this_user (session_id s, session ref self)

2.4. CLASS: SESSION CHAPTER 2. API REFERENCE

Arguments:

type name description

session ref self reference to the o bject

Return Type: user ref

value of the ﬁeld

RPC name: get

last active

Overview:

Get the last

active ﬁeld of the given session.

Signature:

datetime get_last_active (session_id s, session ref self)

Arguments:

type name description

session ref self reference to the o bject

Return Type: datetime

value of the ﬁeld

RPC name: get

pool

Overview:

Get the pool ﬁeld of the given session.

Signature:

bool get_pool (session_id s, session ref self)

Arguments:

type name description

session ref self reference to the o bject

Return Type: bool

value of the ﬁeld

RPC name: get

other conﬁg

Overview:

Get the other

conﬁg ﬁeld of the given sess ion.

Signature:

((string -> string) Map) get_other_config (session_id s, session ref self)

Arguments:

type name description

session ref self reference to the o bject

2.4. CLASS: SESSION CHAPTER 2. API REFERENCE

Return Type: (string → string) Map

value of the ﬁeld

RPC name: set

other conﬁg

Overview:

Set the other

conﬁg ﬁeld of the given sess ion.

Signature:

void set_other_config (session_id s, session ref self, (string -> string) Map value)

Arguments:

type name description

session ref self reference to the object

(string → string) Map value New value to set

Return Type: void

RPC name: add

to other conﬁg

Overview:

Add the g iven key-value pair to the other

conﬁg ﬁeld of the given sess ion.

Signature:

void add_to_other_config (session_id s, session ref self, string key, string value)

Arguments:

type name description

session ref self reference to the o bject

string key Key to add string value Value to add

Return Type: void

RPC name: remove

from other conﬁg

Overview:

Remove the given key and its corresponding value from the other

conﬁg ﬁeld of the given session.

If the key is not in that Map, then do nothing.

Signature:

void remove_from_other_config (session_id s, session ref self, string key)

Arguments:

type name description

session ref self reference to the o bject

string key Key to remove

Return Type: void

2.4. CLASS: SESSION CHAPTER 2. API REFERENCE

RPC name: get by uuid

Overview:

Get a r e ference to the session instance with the speciﬁed UUID.

Signature:

(session ref) get_by_uuid (session_id s, string uuid)

Arguments:

type name description

string uuid UUID of object to retur n

Return Type: session ref

reference to the object

RPC name: get

record

Overview:

Get a r e c ord containing the current state of the given session.

Signature:

(session record) get_record (session_id s, session ref self)

Arguments:

type name description

session ref self reference to the o bject

Return Type: session record

all ﬁelds from the object

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

2.5 Class: task

2.5.1 Fields for class: task

Name task Description A long-running asynchronous task. Quals Field Type Description

RO RO RO

RO RO

RO RO RO RO

run

uuid string unique identiﬁer/ob ject reference name/label string a human-readable name name/description string a notes ﬁeld containg human-

readable description

allowed operations (task allowed operations) Set list of the operations allowed in this

state. This list is advisory only and the server state may have changed by the time this ﬁeld is read by a client.

current operations (string → task allowed operations) Map links each of the running tasks using

this object (by reference) to a current operation enum which describes the nature of the task.

created datetime Time task was created finished datetime Time task ﬁnished (i.e. succeeded

or failed). If task-status is pending, then the value of this ﬁeld has no meaning

status task status type current status of the task session session ref the session that created the task resident on host ref the host on which the task is running progress ﬂoat if the task is still pending, this ﬁeld

contains the estimated fraction complete (0.-1.). If task has c ompleted (successfully or unsuccessfully) this should be 1.

externalpid int If the task has spawned a program,

the ﬁeld record the PID of the process that the task is waiting on. (-1 if no waiting completion of an external program )

stunnelpid int If the task has been forwarded, this

ﬁeld records the pid of the stunnel process spawned to manage the forwarding connection

forwarded bool True if this task has been forwarded

to a slave

forwarded to host ref The host to which the task has been

forwarded

type string if the task has completed successfully,

this ﬁeld contains the type of the encoded result (i.e. name of the class whose reference is in the result ﬁeld). Undeﬁned otherwise.

result string if the task has completed successfully,

this ﬁeld contains the result value (either Void or an object refer ence). Undeﬁned otherwise.

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

run

error info string Set if the task has failed, this ﬁeld

contains the set of as sociated error strings. Undeﬁned otherwise.

RW other config (string → string) Map additional conﬁguration

2.5.2 RPCs associated w ith class: task

RPC name: create

Overview:

Create a new task o bject which must be ma nually destroyed.

Signature:

(task ref) create (session_id s, string label, string description)

Arguments:

type name description

string label short label for the new task string description longer description for the new task

Return Type: task ref

The reference of the created task object

RPC name: destroy

Overview:

Destroy the task object.

Signature:

void destroy (session_id s, task ref self)

Arguments:

type name description

task ref self Reference to the task object

Return Type: void

RPC name: cancel

Overview:

Request that a task be cancelled. Note that a task may fail to be cancelled and may complete or fail normally and note that, even when a task does cancel, it might take an arbitrary amount of time.

Signature:

void cancel (session_id s, task ref task)

Arguments:

type name description

task ref tas k The task

Return Type: void

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

Possible Error Codes: OPERATION NOT ALLOWED

RPC name: get

all

Overview:

Return a list of all the tasks known to the system.

Signature:

((task ref) Set) get_all (session_id s)

Return Type: (task ref) Set

references to all objects

RPC name: get

all records

Overview:

Return a map of task references to task records for all tas ks known to the system.

Signature:

((task ref -> task record) Map) get_all_records (session_id s)

Return Type: (task ref → task record) Map

records of all objects

RPC name: get

uuid

Overview:

Get the uuid ﬁeld of the given task.

Signature:

string get_uuid (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: string

value of the ﬁeld

RPC name: get

name label

Overview:

Get the name/label ﬁeld of the given task.

Signature:

string get_name_label (session_id s, task ref self)

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

Arguments:

type name description

task ref self reference to the object

Return Type: string

value of the ﬁeld

RPC name: get

name description

Overview:

Get the name/description ﬁeld of the given task.

Signature:

string get_name_description (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: string

value of the ﬁeld

RPC name: get

allowed operations

Overview:

Get the allowed

operations ﬁeld of the given task.

Signature:

((task_allowed_operations) Set) get_allowed_operations (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: (task allowed operations) Set

value of the ﬁeld

RPC name: get

current operations

Overview:

Get the current

operations ﬁeld of the given task.

Signature:

((string -> task_allowed_operations) Map) get_current_operations (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

Return Type: (string → task allowed operations) Map

value of the ﬁeld

RPC name: get

created

Overview:

Get the created ﬁeld of the given task.

Signature:

datetime get_created (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: datetime

value of the ﬁeld

RPC name: get

ﬁnished

Overview:

Get the ﬁnished ﬁeld of the given task.

Signature:

datetime get_finished (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: datetime

value of the ﬁeld

RPC name: get

status

Overview:

Get the status ﬁeld of the given task.

Signature:

(task_status_type) get_status (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: task status type

value of the ﬁeld

+ 283 hidden pages

XenSource XenEnterprise Management API User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual