Citrix XenEnterprise Management API

Download

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

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

record

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

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

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

all

all records

RPC name: get

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

Overview:

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

Signature:

string get_name_label (session_id s, task ref self)

uuid

name label

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

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

RPC name: get resident on

Overview:

Get the resident

Signature:

(host ref) get_resident_on (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: host ref

value of the ﬁeld

on ﬁeld o f the given task.

RPC name: get

Overview:

Get the progress ﬁeld of the given task.

Signature:

float get_progress (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: float

value of the ﬁeld

RPC name: get

Overview:

Get the type ﬁeld of the given task.

Signature:

string get_type (session_id s, task ref self)

Arguments:

progress

type

type name description

task ref self reference to the object

Return Type: string

value of the ﬁeld

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

RPC name: get result

Overview:

Get the result ﬁeld of the given task.

Signature:

string get_result (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

Overview:

Get the error

Signature:

(string Set) get_error_info (session_id s, task ref self)

Arguments:

type name description

task ref self reference to the object

Return Type: string Set

value of the ﬁeld

RPC name: get

Overview:

Get the other

Signature:

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

Arguments:

error info

info ﬁeld of the given task.

other conﬁg

conﬁg ﬁeld of the given task.

type name description

task ref self reference to the object

Return Type: (string → string) Map

value of the ﬁeld

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

RPC name: set other conﬁg

Overview:

Set the other

conﬁg ﬁeld of the given task.

Signature:

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

Arguments:

type name description

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

Signature:

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

Arguments:

type name description

task ref self reference to the object

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 task. If

the key is no t in that Map, then do nothing.

Signature:

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

Arguments:

type name description

task ref self reference to the object

string key Key to remove

Return Type: void

2.5. CLASS: TASK CHAPTER 2. API REFERENCE

RPC name: get by uuid

Overview:

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

Signature:

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

Arguments:

type name description

string uuid UUID of object to return

Return Type: task ref

reference to the object

RPC name: get

Overview:

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

Signature:

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

Arguments:

type name description

task ref self reference to the object

Return Type: task record

all ﬁelds from the object

RPC name: get

Overview:

Get all the task instances with the given label.

Signature:

((task ref) Set) get_by_name_label (session_id s, string label)

Arguments:

record

by name label

type name description

string label label of object to return

Return Type: (task ref) Set

references to objects with matching names

2.6. CLASS: EVENT CHAPTER 2. API REFERENCE

2.6 Class: event

2.6.1 Fields for class: event

Name event Description Asynchronous event registration and handling. Quals Field Type Description

ins

2.6.2 RPCs associated w ith class: event

RPC name: register

Overview:

Registers this session with the event system. Specifying the empty list will register for all classes.

Signature:

id int An ID, monotonically increasing, and

local to the current session

timestamp datetime The time at which the event occurred class s tring The na me of the class of the object

that changed

operation event operation The operation that was performed ref string A reference to the object that

changed

obj uuid string The uuid of the object that changed

void register (session_id s, string Set classes)

Arguments:

type name description

string Set classes register for events for the indicated classes

Return Type: void

RPC name: unregister

Overview:

Unregisters this session with the event system.

Signature:

void unregister (session_id s, string Set classes)

Arguments:

type name description

string Set classes remove this session’s registration for the indi-

cated classes

Return Type: void

2.6. CLASS: EVENT CHAPTER 2. API REFERENCE

RPC name: next

Overview:

Blocking call which returns a (possibly empty) batch of events.

Signature:

((event record) Set) next (session_id s)

Return Type: (event record) Set

the batch of events

Possible Error Codes: SESSION

RPC name: get

Overview:

Return the I D of the next event to be generated by the system.

Signature:

int get_current_id (session_id s)

Return Type: int

the event ID

current id

NOT REGISTERED, EVENTS LOST

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

2.7 Class: pool

2.7.1 Fields for class: pool

Name pool Description Pool-wide information. Quals Field Type Description

run

RW name label string Short name RW name description string Description RO

run

RW default SR SR ref Default SR for VDIs RW suspend image SR SR ref The SR in which VDIs for suspend

RW crash dump SR SR ref The SR in which VDIs for cra sh

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

2.7.2 RPCs associated w ith class: pool

RPC name: join

uuid string unique identiﬁer/object reference

master host ref The host that is pool master

images are created

dumps are created

Overview:

Instruct host to join a new pool.

Signature:

void join (session_id s, string master_address, string master_username, string master_password)

Arguments:

type name description

string master address The hostname of the master of the pool to join string master username The username of the master (for initial au-

thentication)

string master password The password for the master (for initial au-

thentication)

Return Type: void

Possible Error Codes: JOINING HOST CANNOT CONTAIN SHARED SRS

RPC name: join

Overview:

Instruct host to join a new pool.

Signature:

void join_force (session_id s, string master_address, string master_username, string master_password)

Arguments:

force

type name description

string master address The hostname of the master of the pool to join string master username The username of the master (for initial au-

thentication)

string master password The password for the master (for initial au-

thentication)

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

Return Type: void

RPC name: eject

Overview:

Instruct a pool master to eject a host from the pool.

Signature:

void eject (session_id s, host ref host)

Arguments:

type name description

host ref host The host to eject

Return Type: void

RPC name: emergency

Overview:

Instruct host that’s currently a slave to transition to being master.

Signature:

void emergency_transition_to_master (session_id s)

Return Type: void

RPC name: emergency reset master

Overview:

Instruct a slave already in a pool that the master has changed.

Signature:

void emergency_reset_master (session_id s, string master_address)

Arguments:

type name description

string master address The hostname of the master

Return Type: void

transition to master

RPC name: recover

Overview:

Instruct a pool master, M, to try and contact its slaves and, if slaves are in emergency mode, reset their master addr ess to M.

Signature:

((host ref) Set) recover_slaves (session_id s)

slaves

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

Return Type: (host ref) Set

list of hosts whose master address were succesfully reset

RPC name: create

Overview:

Create PIFs, mapping a network to the same physical interface/VLAN o n each host.

Signature:

((PIF ref) Set) create_VLAN (session_id s, string device, network ref network, int VLAN)

Arguments:

type name description

string device physical interface on which to create the

network ref network network to which this interface should be con-

int VLAN VLAN tag for the new interface

Return Type: (PIF ref) Set

The references of the created PIF objects

Possible Error Codes: VLAN TAG INVALID

RPC name: enable

Overview:

Turn on High Availability mode.

Signature:

VLAN

VLAN interface

nected

void enable_ha (session_id s)

Return Type: void

RPC name: disable

Overview:

Turn oﬀ High Availability mode.

Signature:

void disable_ha (session_id s)

Return Type: void

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

RPC name: sync database

Overview:

Forcibly synchronise the database now.

Signature:

void sync_database (session_id s)

Return Type: void

RPC name: designate

Overview:

Perform an orderly handover of the role of master to the referenced host.

Signature:

void designate_new_master (session_id s, host ref host)

Arguments:

type name description

host ref host The host who should be c ome the new master

Return Type: void

RPC name: get

Overview:

Return a list of all the pools k nown to the system.

Signature:

((pool ref) Set) get_all (session_id s)

Return Type: (pool ref) Set

references to all objects

all

new master

RPC name: get

Overview:

Return a map of pool r e ferences to pool records for all pools known to the system.

Signature:

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

Return Type: (pool ref → pool record) Map

records of all objects

all records

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

RPC name: get uuid

Overview:

Get the uuid ﬁeld of the given pool.

Signature:

string get_uuid (session_id s, pool ref self)

Arguments:

type name description

pool ref self reference to the object

Return Type: string

value of the ﬁeld

RPC name: get

Overview:

Get the name

Signature:

string get_name_label (session_id s, pool ref self)

Arguments:

type name description

pool ref self reference to the object

Return Type: string

value of the ﬁeld

RPC name: set

Overview:

Set the name

Signature:

void set_name_label (session_id s, pool ref self, string value)

Arguments:

name label

label ﬁeld of the given pool.

name label

label ﬁeld of the given pool.

type name description

pool ref self reference to the object

string value New value to set

Return Type: void

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

RPC name: get name descriptio n

Overview:

Get the name

Signature:

string get_name_description (session_id s, pool ref self)

Arguments:

type name description

pool ref self reference to the object

Return Type: string

value of the ﬁeld

description ﬁeld of the given pool.

RPC name: set

Overview:

Set the name

Signature:

void set_name_description (session_id s, pool ref self, string value)

Arguments:

type name description

pool ref self reference to the object

string value New value to set

Return Type: void

RPC name: get

Overview:

Get the ma ster ﬁeld of the given pool.

Signature:

(host ref) get_master (session_id s, pool ref self)

Arguments:

name description

description ﬁeld of the given pool.

master

type name description

pool ref self reference to the object

Return Type: host ref

value of the ﬁeld

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

RPC name: get default SR

Overview:

Get the default

SR ﬁeld of the g iven pool.

Signature:

(SR ref) get_default_SR (session_id s, pool ref self)

Arguments:

type name description

pool ref self reference to the object

Return Type: SR ref

value of the ﬁeld

RPC name: set

default SR

Overview:

Set the default

SR ﬁeld of the g iven pool.

Signature:

void set_default_SR (session_id s, pool ref self, SR ref value)

Arguments:

type name description

pool ref self reference to the object

SR ref value New value to set

Return Type: void

RPC name: get

suspend image SR

Overview:

Get the suspend

image SR ﬁeld of the given pool.

Signature:

(SR ref) get_suspend_image_SR (session_id s, pool ref self)

Arguments:

type name description

pool ref self reference to the object

Return Type: SR ref

value of the ﬁeld

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

RPC name: set suspend image SR

Overview:

Set the s us pend

image SR ﬁeld of the given pool.

Signature:

void set_suspend_image_SR (session_id s, pool ref self, SR ref value)

Arguments:

type name description

pool ref self reference to the object

SR ref value New value to set

Return Type: void

RPC name: get

crash dump SR

Overview:

Get the crash

dump SR ﬁeld of the given pool.

Signature:

(SR ref) get_crash_dump_SR (session_id s, pool ref self)

Arguments:

type name description

pool ref self reference to the object

Return Type: SR ref

value of the ﬁeld

RPC name: set

crash dump SR

Overview:

Set the crash

dump SR ﬁeld of the given pool.

Signature:

void set_crash_dump_SR (session_id s, pool ref self, SR ref value)

Arguments:

type name description

pool ref self reference to the object

SR ref value New value to set

Return Type: void

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

RPC name: get other conﬁg

Overview:

Get the other

conﬁg ﬁeld of the given pool.

Signature:

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

Arguments:

type name description

pool ref self reference to the object

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

Signature:

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

Arguments:

type name description

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

Signature:

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

Arguments:

type name description

pool ref self reference to the object

string key Key to add string value Value to add

Return Type: void

2.7. CLASS: POOL CHAPTER 2. API REFERENCE

RPC name: remove from other conﬁg

Overview:

Remove the given key and its corresponding value from the other the key is no t in that Map, then do nothing.

Signature:

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

Arguments:

type name description

pool ref self reference to the object

string key Key to remove

Return Type: void

conﬁg ﬁeld of the given pool. If

RPC name: get

Overview:

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

Signature:

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

Arguments:

type name description

string uuid UUID of object to return

Return Type: pool ref

reference to the object

RPC name: get

Overview:

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

Signature:

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

Arguments:

by uuid

record

type name description

pool ref self reference to the object

Return Type: pool record

all ﬁelds from the object

2.8. CLASS: POOL PATCH CHAPTER 2. API REFERENCE

2.8 Class: pool patch

2.8.1 Fields for class: pool

patch

Name pool patch Description Pool-wide patches. Quals Field Type Description

RO RO RO

run

ins

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

readable description

RO RO RO RO

ins

run

version string Patch version number filename string Filename of the patch size int Size of the patch pool applied bool This patch should be applied across

the entire pool

RO RO

run

host patches (host patch ref) Set This hosts this patch is applied to. after apply guidance (after apply guidance) Set What the client should do after this

patch has be e n applied.

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

2.8.2 RPCs associated w ith class: pool patch

RPC name: apply

Overview:

Apply the se lec ted patch to a host and return its output.

Signature:

string apply (session_id s, pool_patch ref self, host ref host)

Arguments:

type name description

pool patch ref self The patch to apply

host ref host The host to apply the patch too

Return Type: string

the output of the patch application process

RPC name: pool

apply

Overview:

Apply the se lec ted patch to all hosts in the pool and return a map of host

Signature:

void pool_apply (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self The patch to apply

Return Type: void

ref -¿ pa tch output.

2.8. CLASS: POOL PATCH CHAPTER 2. API REFERENCE

RPC name: precheck

Overview:

Execute the precheck stage of the selected patch on a host and return its output.

Signature:

string precheck (session_id s, pool_patch ref self, host ref host)

Arguments:

type name description

pool patch ref self The patch whose prechecks will be run

host ref host The host to run the prechecks on

Return Type: string

the output of the patch prechecks

RPC name: clean

Overview:

Removes the patch’s ﬁles from all hosts in the pool, but do e s not remove the database entries.

Signature:

void clean (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self The patch to clean up

Return Type: void

RPC name: destroy

Overview:

Removes the patch’s ﬁles from all hosts in the pool, and removes the database entries. Only works on unapplied patches.

Signature:

void destroy (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self The patch to destroy

Return Type: void

2.8. CLASS: POOL PATCH CHAPTER 2. API REFERENCE

RPC name: get all

Overview:

Return a list of all the pool

patchs known to the system.

Signature:

((pool_patch ref) Set) get_all (session_id s)

Return Type: (pool

patch ref) Set

references to all objects

RPC name: get

all records

Overview:

Return a map of pool

patch references to pool patch records for all pool patchs known to the

system.

Signature:

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

Return Type: (pool

patch ref → pool patch record) Map

records of all objects

RPC name: get

uuid

Overview:

Get the uuid ﬁeld of the given pool

patch.

Signature:

string get_uuid (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: get

name label

Overview:

Get the name/label ﬁeld of the given pool

patch.

Signature:

string get_name_label (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self reference to the ob ject

2.8. CLASS: POOL PATCH CHAPTER 2. API REFERENCE

Return Type: string

value of the ﬁeld

RPC name: get

name description

Overview:

Get the name/description ﬁeld of the given p ool

patch.

Signature:

string get_name_description (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: get

version

Overview:

Get the version ﬁeld of the given pool

patch.

Signature:

string get_version (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: get

size

Overview:

Get the siz e ﬁeld of the given pool

patch.

Signature:

int get_size (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self reference to the ob ject

Return Type: int

value of the ﬁeld

2.8. CLASS: POOL PATCH CHAPTER 2. API REFERENCE

RPC name: get pool applied

Overview:

Get the pool

applied ﬁeld of the given pool patch.

Signature:

bool get_pool_applied (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self reference to the ob ject

Return Type: bool

value of the ﬁeld

RPC name: get

host patches

Overview:

Get the host

patches ﬁeld of the given pool patch.

Signature:

((host_patch ref) Set) get_host_patches (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self reference to the ob ject

Return Type: (host patch ref) Set

value of the ﬁeld

RPC name: get

after apply guidance

Overview:

Get the after

apply guidance ﬁeld of the given pool patch.

Signature:

((after_apply_guidance) Set) get_after_apply_guidance (session_id s, pool_patch ref self)

Arguments:

type name description

pool patch ref self reference to the ob ject

Return Type: (after apply guidance) Set

value of the ﬁeld

2.8. CLASS: POOL PATCH CHAPTER 2. API REFERENCE

RPC name: get other conﬁg

Overview:

Get the other

conﬁg ﬁeld of the given pool patch.

Signature:

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

Arguments:

type name description

pool patch ref self reference to the ob ject

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 pool patch.

Signature:

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

Arguments:

type name description

pool patch ref self reference to the ob ject

(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 pool patch.

Signature:

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

Arguments:

type name description

pool patch ref self reference to the ob ject

string key Key to add string value Value to add

Return Type: void

2.8. CLASS: POOL PATCH CHAPTER 2. API REFERENCE

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 pool patch.

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

Signature:

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

Arguments:

type name description

pool patch ref self reference to the ob ject

string key Key to remove

Return Type: void

RPC name: get

by uuid

Overview:

Get a r e ference to the poo l

patch instance with the speciﬁed UUID.

Signature:

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

Arguments:

type name description

string uuid UUID of object to return

Return Type: pool patch ref

reference to the object

RPC name: get

record

Overview:

Get a r e c ord containing the current state of the given poo l

patch.

Signature:

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

Arguments:

type name description

pool patch ref self reference to the ob ject

Return Type: pool patch record

all ﬁelds from the object

2.8. CLASS: POOL PATCH CHAPTER 2. API REFERENCE

RPC name: get by name label

Overview:

Get all the pool

Signature:

((pool_patch ref) Set) get_by_name_label (session_id s, string label)

Arguments:

type name description

string label label of object to return

Return Type: (pool patch ref) Set

references to objects with matching names

patch instances with the given label.

2.9. CLASS: VM CHAPTER 2. API REFERENCE

2.9 Class: VM

2.9.1 Fields for class: VM

Name VM Description A virtual machine (or ’guest’). Quals Field Type Description

run

RW name/label string a human-readable name RW name/description string a notes ﬁeld containg human-

RW user version int a user version number for this ma-

RW is a template bool true if this is a template. Template

run

RW affinity host ref a host which the VM has some aﬃn-

RW memory/static max int Statically-set (i.e. absolute) ma xi-

RW memory/dynamic max int Dynamic maximum (bytes) RW memory/dynamic min int Dynamic minimum (bytes) RW memory/static min int Statically-set (i.e. absolute) mininum

RW VCPUs/params (string → string) Map conﬁguration parameters for the se-

uuid string unique identiﬁer/object reference allowed operations (vm operations) Set list of the operations allowed in this

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

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

this object (by reference) to a cur-

operation enum which describes

rent the nature of the task.

power state vm power state Current power state of the machine

readable description

chine

VMs ca n never be started, they are used only fo r cloning other VMs

suspend VDI VDI ref The VDI tha t a suspend image is

stored on. (Only has meaning if VM is currently suspended)

resident on host ref the host the VM is currently resident

scheduled to be resident on host ref the host on which the VM is due to

be started/resumed/migrated. This acts as a memory reservation indicator

ity for (or NULL). This is used as a hint to the s tart call when it decides where to run the VM. Implementations are free to ignore this ﬁeld.

mum (bytes). The value of this ﬁeld at VM start time acts as a hard limit of the amount of memory a guest can use. New values only take eﬀect on reboot.

(bytes). The value of this ﬁeld indicates the least amount of memory this VM can boot with without crashing.

lected VCPU p olicy

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RW VCPUs/max int Max number of VCPUs RW VCPUs/at startup int Boot number of VCPUs RW actions/after shutdown on normal exit action to take after the guest has

shutdown itself

RW actions/after reboot on normal exit action to take after the guest has re-

booted itself

RW actions/after crash on cras h behaviour action to take if the guest crashes RO RO RO RO RO

run

consoles (console ref) Set virtual console devices VIFs (VIF ref) Set virtual network interfaces VBDs (VBD ref) Set virtual block devices crash dumps (crashdump ref) Set crash dumps as sociated with this VM VTPMs (VTPM ref) Set virtua l TPMs

RW PV/bootloader string name of or path to bootloader RW PV/kernel string path to the kernel RW PV/ramdisk string path to the initrd RW PV/args string kernel command-line arguments RW PV/bootloader args string miscellaneous arguments for the

bootloader

RW PV/legacy args string to make Zurich guests boot RW HVM/boot policy string HVM boot policy RW HVM/boot params (string → string) Map HVM boot params RW HVM/shadow multiplier ﬂoat multiplier applied to the amount of

shadow that will be made available to the guest

RW platform (string → s tring) Map platform-speciﬁc conﬁguration RW PCI bus string PCI bus path for pass-through de-

vices

RW other config (string → string) Map additional conﬁguratio n RO RO

run

domid int domain ID (if available, -1 otherwis e ) domarch string Domain architecture (if available,

null string otherwise)

run

last boot CPU flags (string → string) Map describes the CPU ﬂags on which the

VM was last booted

run

is control domain bool true if this is a control domain (do-

main 0 or a driver domain)

RO RO

run

metrics VM metrics ref metrics ass ociated with this VM guest metrics VM guest metrics ref metrics associated with the running

guest

run

last booted record string marshalled value c ontaining VM

record at time of last boot, updated dynamically to reﬂect the runtime state of the domain

RW recommendations string An XML speciﬁcation of recom-

mended values and ranges for properties of this VM

RW xenstore data (string → string) Map data to be inserted into the xenstore

tree (/local/domain/¡domid¿/vmdata) after the VM is created.

2.9.2 RPCs associated w ith class: VM

RPC name: clone

Overview:

2.9. CLASS: VM CHAPTER 2. API REFERENCE

Clones the speciﬁed VM, making a new VM. Clone automatically exploits the capabilities of the underlying storage repositor y in which the VM’s disk images are stored (e.g. Copy on Write). This function c an only be called when the VM is in the Halted State.

Signature:

(VM ref) clone (session_id s, VM ref vm, string new_name)

Arguments:

type name description

VM ref vm The VM to be cloned string new name The name of the cloned VM

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM

BAD POWER STATE, SR FULL, OPERATION NOT ALLOWED

RPC name: copy

Overview:

Copied the speciﬁed VM, making a new VM. Unlike clone, copy does not exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored. Instead, copy guarantees that the disk images of the newly created VM will be ’full disks’ - i.e. not part of a CoW chain. This function can only be called when the VM is in the Halted State.

Signature:

(VM ref) copy (session_id s, VM ref vm, string new_name, SR ref sr)

Arguments:

type name description

VM ref vm The VM to be copied string new name The name of the copied VM SR ref sr An SR to copy all the VM’s disks into (if an

invalid reference then it uses the existing SRs)

Return Type: VM ref

The reference of the newly created VM.

Possible Error Codes: VM BAD POWER STATE, SR FULL, OPERATION NOT ALLOWED

RPC name: provision

Overview:

Inspects the disk conﬁguration contained within the VM’s other conﬁg, creates VDIs and VBDs and then executes any applicable post-install script.

Signature:

void provision (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to be provisioned

2.9. CLASS: VM CHAPTER 2. API REFERENCE

Return Type: void

Possible Error Codes: VM

BAD POWER STATE, SR FULL, OPERATION NOT ALLOWED

RPC name: start

Overview:

Start the speciﬁed VM. This function can only be called with the VM is in the Halted State.

Signature:

void start (session_id s, VM ref vm, bool start_paused, bool force)

Arguments:

type name description

VM ref vm T he VM to start

bool start paused Instantiate VM in paused state if set to true. bool force Attempt to force the VM to start. If this ﬂag

is false then the VM may fail pre-boot safety checks (e.g. if the CPU the VM last booted on looks substantially diﬀerent to the current one)

Return Type: void

Possible Error Codes: VM BAD POWER STATE, VM HVM REQUIRED, VM IS TEMPLATE, OTHER OPERATION IN PROGRESS,

OPERATION NOT ALLOWED, BOOTLOADER FAILED, UNKNOWN BOOTLOADER, NO HOSTS AVAILABLE, LICENCE RESTRICTION

RPC name: start

Overview:

Start the speciﬁed VM on a particular host. This function can only be called with the VM is in the Halted State.

Signature:

void start_on (session_id s, VM ref vm, host ref host, bool start_paused, bool force)

Arguments:

type name description

VM ref vm The VM to start

host ref host The Host on which to start the VM

bool start paused Instantiate VM in paused state if set to true. bool force Attempt to force the VM to start. If this ﬂag

is false then the VM may fail pre-boot safety checks (e.g. if the CPU the VM last booted on looks substantially diﬀerent to the curr e nt one)

Return Type: void

Possible Error Codes: VM BAD POWER STATE, VM IS TEMPLATE, OTHER OPERATION IN PROGRESS,

OPERATION NOT ALLOWED, BOOTLOADER FAILED, UNKNOWN BOOTLOADER

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: pause

Overview:

Pause the speciﬁed VM. This can only be called when the speciﬁed VM is in the Running state.

Signature:

void pause (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to pa use

Return Type: void

Possible Error Codes: VM

BAD POWER STATE, OTHER OPERATION IN PROGRESS, OPERATION NOT ALLOWED,

VM IS TEMPLATE

RPC name: unpause

Overview:

Resume the speciﬁed VM. This can only b e called when the speciﬁed VM is in the Paused state.

Signature:

void unpause (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to unpause

Return Type: void

Possible Error Codes: VM

RPC name: clean

shutdown

BAD POWER STATE, OPERATION NOT ALLOWED, VM IS TEMPLATE

Overview:

Attempt to cleanly shutdown the spec iﬁed VM. (Note: this may not be supported—e.g. if a guest agent is not installed). This can only be called when the speciﬁed VM is in the Running state.

Signature:

void clean_shutdown (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to shutdown

Return Type: void

Possible Error Codes: VM

IS TEMPLATE

BAD POWER STATE, OTHER OPERATION IN PROGRESS, OPERATION NOT ALLOWED,

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: clean reboot

Overview:

Attempt to cleanly shutdown the speciﬁed VM (Note: this may not be supp orted—e.g. if a guest agent is not installed). This can only be called when the speciﬁed VM is in the Running state.

Signature:

void clean_reboot (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to shutdown

Return Type: void

Possible Error Codes: VM BAD POWER STATE, OTHER OPERATION IN PROGRESS, OPERATION NOT ALLOWED,

VM IS TEMPLATE

RPC name: hard

shutdown

Overview:

Stop executing the speciﬁed VM without attempting a clean shutdown.

Signature:

void hard_shutdown (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to destroy

Return Type: void

Possible Error Codes: VM BAD POWER STATE, OTHER OPERATION IN PROGRESS, OPERATION NOT ALLOWED,

VM IS TEMPLATE

RPC name: power

state reset

Overview:

Reset the power-state of the VM to halted in the database only. (Used to recover from slave failures in poo ling scenarios by re setting the power-states of VMs running on dead slaves to halted.) This is a potentially dangerous operation; use with care.

Signature:

void power_state_reset (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to reset

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: hard reboot

Overview:

Stop executing the speciﬁed VM without attempting a clean shutdown and immediately restart the VM.

Signature:

void hard_reboot (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to reboot

Return Type: void

Possible Error Codes: VM BAD POWER STATE, OTHER OPERATION IN PROGRESS, OPERATION NOT ALLOWED,

VM IS TEMPLATE

RPC name: suspend

Overview:

Suspend the speciﬁed VM to disk. This can only be called when the speciﬁed VM is in the Running state.

Signature:

void suspend (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to suspend

Return Type: void

Possible Error Codes: VM BAD POWER STATE, OTHER OPERATION IN PROGRESS, OPERATION NOT ALLOWED,

VM IS TEMPLATE

RPC name: resume

Overview:

Awaken the speciﬁed VM and resume it. This can only be called when the speciﬁed VM is in the Suspended state.

Signature:

void resume (session_id s, VM ref vm, bool start_paused, bool force)

Arguments:

type name description

VM ref vm T he VM to resume

bool start paused Resume VM in paused state if set to true. bool force Attempt to force the VM to resume. If this

ﬂag is false then the VM may fail pre -resume safety checks (e.g. if the CPU the VM was running on looks substantially diﬀerent to the current one)

2.9. CLASS: VM CHAPTER 2. API REFERENCE

Return Type: void

Possible Error Codes: VM

RPC name: resume

BAD POWER STATE, OPERATION NOT ALLOWED, VM IS TEMPLATE

Overview:

Awaken the speciﬁed VM and resume it on a particular Host. This can only be ca lled when the speciﬁed VM is in the Suspe nded state.

Signature:

void resume_on (session_id s, VM ref vm, host ref host, bool start_paused, bool force)

Arguments:

type name description

VM ref vm The VM to resume

host ref host The Host on which to resume the VM

bool start paused Resume VM in paused state if set to true. bool force Attempt to force the VM to resume. If this

ﬂag is false then the VM may fail pre -resume safety checks (e.g. if the CPU the VM was running on looks substantially diﬀerent to the current one)

Return Type: void

Possible Error Codes: VM

BAD POWER STATE, OPERATION NOT ALLOWED, VM IS TEMPLATE

RPC name: pool

migrate

Overview:

Migrate a VM to another Host. This can only be called when the speciﬁed VM is in the Running state.

Signature:

void pool_migrate (session_id s, VM ref vm, host ref host, (string -> string) Map options)

Arguments:

type name description

VM ref vm The VM to migrate

host ref host The target host

(string → string) Map options Extra conﬁguration operations

Return Type: void

Possible Error Codes: VM BAD POWER STATE, OTHER OPERATION IN PROGRESS, VM IS TEMPLATE,

OPERATION NOT ALLOWED, VM MIGRATE FAILED, VM MISSING PV DRIVERS

RPC name: set

VCPUs number live

Overview:

Set this VM’s VCPUs/at

startup value, and set the same value on the VM, if running.

Signature:

2.9. CLASS: VM CHAPTER 2. API REFERENCE

void set_VCPUs_number_live (session_id s, VM ref self, int nvcpu)

Arguments:

type name description

VM ref self The VM

int nvcpu The number of VCPUs

Return Type: void

RPC name: add

to VCPUs params live

Overview:

Add the g iven key-value pair to VM.VCPUs

params, and apply that value on the running VM.

Signature:

void add_to_VCPUs_params_live (session_id s, VM ref self, string key, string value)

Arguments:

type name description

VM ref self The VM string key The key string value The value

Return Type: void

RPC name: set

memory target live

Overview:

Set the balloon driver’s targ et on a running VM.

Signature:

void set_memory_target_live (session_id s, VM ref self, int target)

Arguments:

type name description

VM ref self The VM

int target The target in bytes

Return Type: void

RPC name: set

shadow multiplier live

Overview:

Set the s hadow memory on a running VM with the new shadow multiplier.

Signature:

void set_shadow_multiplier_live (session_id s, VM ref self, float multiplier)

2.9. CLASS: VM CHAPTER 2. API REFERENCE

Arguments:

type name description

VM ref self The VM

float multiplier The new shadow multiplier to set

Return Type: void

RPC name: send

sysrq

Overview:

Send the given key as a sysrq to this VM. The key is speciﬁed as a single character (a String of length 1). This can only be called when the speciﬁed VM is in the Running state.

Signature:

void send_sysrq (session_id s, VM ref vm, string key)

Arguments:

type name description

VM ref vm The VM string key The key to send

Return Type: void

Possible Error Codes: VM BAD POWER STATE

RPC name: send

trigger

Overview:

Send the named trigger to this VM. This can only be called when the speciﬁed VM is in the Running state.

Signature:

void send_trigger (session_id s, VM ref vm, string trigger)

Arguments:

type name description

VM ref vm The VM string trigger The trigger to send

Return Type: void

Possible Error Codes: VM BAD POWER STATE

RPC name: maximise

memory

Overview:

Returns the maximum amount of guest memory which will ﬁt, together with overheads, in the supplied amount of physical memory. If ’exact’ is true then an exact calculation is performed using the VM’s current settings. If ’exact’ is false then a more conservative approximation is used.

Signature:

2.9. CLASS: VM CHAPTER 2. API REFERENCE

int maximise_memory (session_id s, VM ref self, int total, bool approximate)

Arguments:

type name description

VM ref self The VM

int total Total amount of physical RAM to ﬁt within

bool approximate If false the limit is calculated with the guest’s

current exact conﬁguration. Otherwise a more approximate calculation is performed

Return Type: int

The maximum possible static-max

RPC name: get

Overview:

Returns a record describing the VM’s dynamic state, initialised when the VM boots and updated to reﬂect runtime conﬁguration changes e.g. CPU hotplug.

Signature:

(VM record) get_boot_record (session_id s, VM ref self)

Arguments:

type name description

VM ref self The VM whose boot-time state to return

Return Type: VM record

A record describing the VM

RPC name: assert

Overview:

Check to see whether this operation is acceptable in the current state of the system, raising an error if the operation is invalid for some reason.

Signature:

void assert_operation_valid (session_id s, VM ref self, vm_operations op)

boot record

operation valid

Arguments:

type name description

VM ref self reference to the object

vm operations op proposed operation

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: update allowed operations

Overview:

Recomputes the list of acc e pta ble operations.

Signature:

void update_allowed_operations (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: void

RPC name: get

allowed VBD devices

Overview:

Returns a list of the allowed values that a VBD device ﬁeld can take.

Signature:

(string Set) get_allowed_VBD_devices (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to query

Return Type: string Set

The allowed values

RPC name: get

allowed VIF devices

Overview:

Returns a list of the allowed values that a VIF device ﬁeld can take.

Signature:

(string Set) get_allowed_VIF_devices (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM to query

Return Type: string Set

The allowed values

RPC name: get

possible hosts

Overview:

Return the list of hosts on which this VM may run.

Signature:

2.9. CLASS: VM CHAPTER 2. API REFERENCE

((host ref) Set) get_possible_hosts (session_id s, VM ref vm)

Arguments:

type name description

VM ref vm The VM

Return Type: (host ref) Set

The pos sible hosts

RPC name: assert

can boot here

Overview:

Returns an e rror if the VM could not boot on this host for some reason.

Signature:

void assert_can_boot_here (session_id s, VM ref self, host ref host)

Arguments:

type name description

VM ref self The VM

host ref host The host

Return Type: void

Possible Error Codes: HOST

RPC name: atomic

set resident on

NOT ENOUGH FREE MEMORY, VM REQUIRES SR

Overview:

Signature:

void atomic_set_resident_on (session_id s, VM ref vm, host ref host)

Arguments:

type name description

VM ref vm The VM to modify

host ref host The host to set resident on to

Return Type: void

RPC name: get

all

Overview:

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

Signature:

((VM ref) Set) get_all (session_id s)

2.9. CLASS: VM CHAPTER 2. API REFERENCE

Return Type: (VM ref) Set

references to all objects

RPC name: get

Overview:

Return a map of VM references to VM records for all VMs known to the system.

Signature:

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

Return Type: (VM ref → VM record) Map

records of all objects

RPC name: get

Overview:

Get the uuid ﬁeld of the given VM.

Signature:

string get_uuid (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

all records

uuid

RPC name: get

Overview:

Get the allowed

Signature:

((vm_operations) Set) get_allowed_operations (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (vm operations) Set

value of the ﬁeld

allowed operations

operations ﬁeld of the given VM.

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get current operations

Overview:

Get the current

Signature:

((string -> vm_operations) Map) get_current_operations (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (string → vm operations) Map

value of the ﬁeld

operations ﬁeld of the given VM.

RPC name: get

Overview:

Get the power

Signature:

(vm_power_state) get_power_state (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: vm power state

value of the ﬁeld

RPC name: get

Overview:

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

Signature:

string get_name_label (session_id s, VM ref self)

Arguments:

power state

state ﬁeld of the given VM.

name label

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set name label

Overview:

Set the name/label ﬁeld of the given VM.

Signature:

void set_name_label (session_id s, VM ref self, string value)

Arguments:

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

RPC name: get

Overview:

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

Signature:

string get_name_description (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: set

Overview:

Set the name/description ﬁeld of the given VM.

Signature:

void set_name_description (session_id s, VM ref self, string value)

Arguments:

name description

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get user version

Overview:

Get the user

version ﬁeld of the given VM.

Signature:

int get_user_version (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: int

value of the ﬁeld

RPC name: set

user version

Overview:

Set the user

version ﬁeld of the given VM.

Signature:

void set_user_version (session_id s, VM ref self, int value)

Arguments:

type name description

VM ref self reference to the ob ject

int value New value to set

Return Type: void

RPC name: get

is a template

Overview:

Get the is

a template ﬁeld of the given VM.

Signature:

bool get_is_a_template (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: bool

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set is a template

Overview:

Set the is

a template ﬁeld of the given VM.

Signature:

void set_is_a_template (session_id s, VM ref self, bool value)

Arguments:

type name description

VM ref self reference to the ob ject

bool value New value to set

Return Type: void

RPC name: get

suspend VDI

Overview:

Get the suspend

VDI ﬁeld of the given VM.

Signature:

(VDI ref) get_suspend_VDI (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: VDI ref

value of the ﬁeld

RPC name: get

resident on

Overview:

Get the resident

on ﬁeld o f the given VM.

Signature:

(host ref) get_resident_on (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: host ref

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get aﬃnity

Overview:

Get the aﬃnity ﬁeld of the given VM.

Signature:

(host ref) get_affinity (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: host ref

value of the ﬁeld

RPC name: set

Overview:

Set the aﬃnity ﬁeld of the given VM.

Signature:

void set_affinity (session_id s, VM ref self, host ref value)

Arguments:

type name description

VM ref self r e ference to the object

host ref value New value to set

Return Type: void

RPC name: get

Overview:

Get the memory/static

Signature:

int get_memory_static_max (session_id s, VM ref self)

Arguments:

aﬃnity

memory static max

max ﬁeld of the given VM.

type name description

VM ref self reference to the ob ject

Return Type: int

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set memory static max

Overview:

Set the memory/static

max ﬁeld of the given VM.

Signature:

void set_memory_static_max (session_id s, VM ref self, int value)

Arguments:

type name description

VM ref self reference to the ob ject

int value New value to set

Return Type: void

RPC name: get

memory dynamic max

Overview:

Get the memory/dynamic

max ﬁeld of the given VM.

Signature:

int get_memory_dynamic_max (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: int

value of the ﬁeld

RPC name: set

memory dynamic max

Overview:

Set the memory/dynamic

max ﬁeld of the given VM.

Signature:

void set_memory_dynamic_max (session_id s, VM ref self, int value)

Arguments:

type name description

VM ref self reference to the ob ject

int value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get memory dynamic min

Overview:

Get the memory/dynamic

min ﬁeld of the given VM.

Signature:

int get_memory_dynamic_min (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: int

value of the ﬁeld

RPC name: set

memory dynamic min

Overview:

Set the memory/dynamic

min ﬁeld of the given VM.

Signature:

void set_memory_dynamic_min (session_id s, VM ref self, int value)

Arguments:

type name description

VM ref self reference to the ob ject

int value New value to set

Return Type: void

RPC name: get

memory static min

Overview:

Get the memory/static

min ﬁeld of the given VM.

Signature:

int get_memory_static_min (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: int

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set memory static min

Overview:

Set the memory/static

Signature:

void set_memory_static_min (session_id s, VM ref self, int value)

Arguments:

type name description

VM ref self reference to the ob ject

int value New value to set

Return Type: void

min ﬁeld of the given VM.

RPC name: get

Overview:

Get the VCPUs/params ﬁeld of the given VM.

Signature:

((string -> string) Map) get_VCPUs_params (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (string → string) Map

value of the ﬁeld

RPC name: set

Overview:

Set the VCPUs/params ﬁeld of the given VM.

Signature:

void set_VCPUs_params (session_id s, VM ref self, (string -> string) Map value)

Arguments:

VCPUs params

type name description

VM ref self reference to the object

(string → string) Map value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: add to VCPUs params

Overview:

Add the g iven key-value pair to the VCPUs/params ﬁeld of the given VM.

Signature:

void add_to_VCPUs_params (session_id s, VM ref self, string key, string value)

Arguments:

type name description

VM ref self reference to the ob ject string key Key to add string value Value to add

Return Type: void

RPC name: remove

Overview:

Remove the given key and its corresponding value from the VCPUs/params ﬁeld of the given VM. If the key is not in that Map, then do nothing.

Signature:

void remove_from_VCPUs_params (session_id s, VM ref self, string key)

Arguments:

type name description

VM ref self reference to the ob ject string key Key to remove

Return Type: void

RPC name: get

Overview:

Get the VCPUs/max ﬁeld of the given VM.

Signature:

int get_VCPUs_max (session_id s, VM ref self)

from VCPUs params

VCPUs max

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: int

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set VCPUs max

Overview:

Set the VCPUs/max ﬁeld of the given VM.

Signature:

void set_VCPUs_max (session_id s, VM ref self, int value)

Arguments:

type name description

VM ref self reference to the ob ject

int value New value to set

Return Type: void

RPC name: get

Overview:

Get the VCPUs/at

Signature:

int get_VCPUs_at_startup (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: int

value of the ﬁeld

RPC name: set

Overview:

Set the VCPUs/at

Signature:

void set_VCPUs_at_startup (session_id s, VM ref self, int value)

Arguments:

VCPUs at startup

startup ﬁeld o f the given VM.

VCPUs at startup

startup ﬁeld o f the given VM.

type name description

VM ref self reference to the ob ject

int value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get actions after shutdown

Overview:

Get the actions/after

shutdown ﬁeld of the given VM.

Signature:

(on_normal_exit) get_actions_after_shutdown (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: on normal exit

value of the ﬁeld

RPC name: set

actions after shutdown

Overview:

Set the actions/after

shutdown ﬁeld of the given VM.

Signature:

void set_actions_after_shutdown (session_id s, VM ref self, on_normal_exit value)

Arguments:

type name description

VM ref self reference to the object

on normal exit value New value to set

Return Type: void

RPC name: get

actions after reboot

Overview:

Get the actions/after

reboot ﬁeld of the given VM.

Signature:

(on_normal_exit) get_actions_after_reboot (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: on normal exit

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set actions after reboot

Overview:

Set the actions/after

reboot ﬁeld of the given VM.

Signature:

void set_actions_after_reboot (session_id s, VM ref self, on_normal_exit value)

Arguments:

type name description

VM ref self reference to the object

on normal exit value New value to set

Return Type: void

RPC name: get

actions after crash

Overview:

Get the actions/after

crash ﬁeld of the given VM.

Signature:

(on_crash_behaviour) get_actions_after_crash (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: on crash behaviour

value of the ﬁeld

RPC name: set

actions after crash

Overview:

Set the actions/after

crash ﬁeld of the given VM.

Signature:

void set_actions_after_crash (session_id s, VM ref self, on_crash_behaviour value)

Arguments:

type name description

VM ref self reference to the object

on crash behaviour value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get consoles

Overview:

Get the consoles ﬁeld of the given VM.

Signature:

((console ref) Set) get_consoles (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (console ref) Set

value of the ﬁeld

RPC name: get

Overview:

Get the VIFs ﬁeld of the given VM.

Signature:

((VIF ref) Set) get_VIFs (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (VIF ref) Set

value of the ﬁeld

RPC name: get

Overview:

Get the VBDs ﬁeld of the given VM.

Signature:

((VBD ref) Set) get_VBDs (session_id s, VM ref self)

Arguments:

VIFs

VBDs

type name description

VM ref self reference to the ob ject

Return Type: (VBD ref) Set

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get crash dumps

Overview:

Get the crash

Signature:

((crashdump ref) Set) get_crash_dumps (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (crashdump ref) Set

value of the ﬁeld

dumps ﬁeld of the given VM.

RPC name: get

Overview:

Get the VTPMs ﬁeld of the given VM.

Signature:

((VTPM ref) Set) get_VTPMs (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (VTPM ref) Set

value of the ﬁeld

RPC name: get

Overview:

Get the PV/bootloader ﬁeld of the given VM.

Signature:

string get_PV_bootloader (session_id s, VM ref self)

Arguments:

VTPMs

PV bootloader

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set PV bootloader

Overview:

Set the PV/bootloader ﬁeld of the given VM.

Signature:

void set_PV_bootloader (session_id s, VM ref self, string value)

Arguments:

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

RPC name: get

Overview:

Get the PV/kernel ﬁeld of the given VM.

Signature:

string get_PV_kernel (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: set

Overview:

Set the PV/kernel ﬁeld of the given VM.

Signature:

void set_PV_kernel (session_id s, VM ref self, string value)

Arguments:

PV kernel

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get PV ramdis k

Overview:

Get the PV/ramdisk ﬁeld of the given VM.

Signature:

string get_PV_ramdisk (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: set

Overview:

Set the PV/ramdisk ﬁeld of the given VM.

Signature:

void set_PV_ramdisk (session_id s, VM ref self, string value)

Arguments:

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

RPC name: get

Overview:

Get the PV/args ﬁeld of the given VM.

Signature:

string get_PV_args (session_id s, VM ref self)

Arguments:

PV ramdisk

PV args

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set PV args

Overview:

Set the PV/args ﬁeld of the given VM.

Signature:

void set_PV_args (session_id s, VM ref self, string value)

Arguments:

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

RPC name: get

Overview:

Get the PV/bootloader

Signature:

string get_PV_bootloader_args (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: set

Overview:

Set the PV/bootloader

Signature:

void set_PV_bootloader_args (session_id s, VM ref self, string value)

Arguments:

PV bootloader args

args ﬁeld of the given VM.

PV bootloader args

args ﬁeld of the given VM.

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get PV l egacy args

Overview:

Get the PV/legacy

args ﬁeld of the given VM.

Signature:

string get_PV_legacy_args (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: set

PV legacy args

Overview:

Set the PV/legacy

args ﬁeld of the given VM.

Signature:

void set_PV_legacy_args (session_id s, VM ref self, string value)

Arguments:

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

RPC name: get

HVM boot policy

Overview:

Get the HVM/boot

policy ﬁeld of the given VM.

Signature:

string get_HVM_boot_policy (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set HVM boot policy

Overview:

Set the HVM/boot

policy ﬁeld of the given VM.

Signature:

void set_HVM_boot_policy (session_id s, VM ref self, string value)

Arguments:

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

RPC name: get

HVM boot params

Overview:

Get the HVM/boot

params ﬁeld o f the given VM.

Signature:

((string -> string) Map) get_HVM_boot_params (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (string → string) Map

value of the ﬁeld

RPC name: set

HVM boot params

Overview:

Set the HVM/boot

params ﬁeld o f the given VM.

Signature:

void set_HVM_boot_params (session_id s, VM ref self, (string -> string) Map value)

Arguments:

type name description

VM ref self reference to the object

(string → string) Map value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: add to HVM boot params

Overview:

Add the g iven key-value pair to the HVM/boot

params ﬁeld o f the given VM.

Signature:

void add_to_HVM_boot_params (session_id s, VM ref self, string key, string value)

Arguments:

type name description

VM ref self reference to the ob ject string key Key to add string value Value to add

Return Type: void

RPC name: remove

from HVM boot params

Overview:

Remove the given key and its corresponding value fr om the HVM/boot

params ﬁeld o f the given

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

Signature:

void remove_from_HVM_boot_params (session_id s, VM ref self, string key)

Arguments:

type name description

VM ref self reference to the ob ject string key Key to remove

Return Type: void

RPC name: get

HVM shadow multiplier

Overview:

Get the HVM/shadow

multiplier ﬁeld of the given VM.

Signature:

float get_HVM_shadow_multiplier (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: float

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set HVM shadow multiplier

Overview:

Set the HVM/shadow

Signature:

void set_HVM_shadow_multiplier (session_id s, VM ref self, float value)

Arguments:

type name description

VM ref self reference to the ob ject

float value New value to set

Return Type: void

multiplier ﬁeld of the given VM.

RPC name: get

Overview:

Get the pla tform ﬁeld of the given VM.

Signature:

((string -> string) Map) get_platform (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (string → string) Map

value of the ﬁeld

RPC name: set

Overview:

Set the pla tform ﬁeld of the given VM.

Signature:

void set_platform (session_id s, VM ref self, (string -> string) Map value)

Arguments:

platform

type name description

VM ref self reference to the object

(string → string) Map value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: add to platform

Overview:

Add the g iven key-value pair to the platform ﬁeld of the given VM.

Signature:

void add_to_platform (session_id s, VM ref self, string key, string value)

Arguments:

type name description

VM ref self reference to the ob ject string key Key to add string value Value to add

Return Type: void

RPC name: remove

from platform

Overview:

Remove the given key and its corresponding value from the platform ﬁeld of the given VM. If the key is not in that Map, then do nothing.

Signature:

void remove_from_platform (session_id s, VM ref self, string key)

Arguments:

type name description

VM ref self reference to the ob ject string key Key to remove

Return Type: void

RPC name: get

PCI bus

Overview:

Get the PCI

bus ﬁeld of the given VM.

Signature:

string get_PCI_bus (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set PCI bus

Overview:

Set the PCI

bus ﬁeld of the given VM.

Signature:

void set_PCI_bus (session_id s, VM ref self, string value)

Arguments:

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

RPC name: get

other conﬁg

Overview:

Get the other

conﬁg ﬁeld of the given VM.

Signature:

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

Arguments:

type name description

VM ref self reference to the ob ject

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

Signature:

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

Arguments:

type name description

VM ref self reference to the object

(string → string) Map value New value to set

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: add to other conﬁg

Overview:

Add the g iven key-value pair to the other

conﬁg ﬁeld of the given VM.

Signature:

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

Arguments:

type name description

VM ref self reference to the ob ject 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 VM. If

the key is no t in that Map, then do nothing.

Signature:

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

Arguments:

type name description

VM ref self reference to the ob ject string key Key to remove

Return Type: void

RPC name: get

domid

Overview:

Get the domid ﬁeld of the given VM.

Signature:

int get_domid (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: int

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get domarch

Overview:

Get the domarch ﬁeld of the given VM.

Signature:

string get_domarch (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: get

Overview:

Get the last

Signature:

((string -> string) Map) get_last_boot_CPU_flags (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: (string → string) Map

value of the ﬁeld

RPC name: get

Overview:

Get the is

Signature:

bool get_is_control_domain (session_id s, VM ref self)

Arguments:

control domain ﬁeld of the given VM.

last boot CPU ﬂags

boot CPU ﬂags ﬁeld of the given VM.

is control domain

type name description

VM ref self reference to the ob ject

Return Type: bool

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get metrics

Overview:

Get the metrics ﬁeld of the given VM.

Signature:

(VM_metrics ref) get_metrics (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: VM metrics ref

value of the ﬁeld

RPC name: get

Overview:

Get the guest

Signature:

(VM_guest_metrics ref) get_guest_metrics (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: VM guest metrics ref

value of the ﬁeld

RPC name: get

Overview:

Get the last

Signature:

string get_last_booted_record (session_id s, VM ref self)

Arguments:

guest metrics

metrics ﬁeld of the given VM.

last booted record

booted record ﬁeld of the given VM.

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get recommendations

Overview:

Get the recommendations ﬁeld of the given VM.

Signature:

string get_recommendations (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: set

Overview:

Set the recommendations ﬁeld of the given VM.

Signature:

void set_recommendations (session_id s, VM ref self, string value)

Arguments:

type name description

VM ref self reference to the ob ject string value New value to set

Return Type: void

RPC name: get

Overview:

Get the xe ns tore

Signature:

((string -> string) Map) get_xenstore_data (session_id s, VM ref self)

Arguments:

recommendations

xenstore data

data ﬁeld of the given VM.

type name description

VM ref self reference to the ob ject

Return Type: (string → string) Map

value of the ﬁeld

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: set xenstore data

Overview:

Set the xe ns tore

data ﬁeld of the given VM.

Signature:

void set_xenstore_data (session_id s, VM ref self, (string -> string) Map value)

Arguments:

type name description

VM ref self reference to the object

(string → string) Map value New value to set

Return Type: void

RPC name: add

to xenstore data

Overview:

Add the g iven key-value pair to the xenstore

data ﬁeld of the given VM.

Signature:

void add_to_xenstore_data (session_id s, VM ref self, string key, string value)

Arguments:

type name description

VM ref self reference to the ob ject string key Key to add string value Value to add

Return Type: void

RPC name: remove

from xenstore data

Overview:

Remove the given key and its corresponding value from the xenstore

data ﬁeld of the given VM.

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

Signature:

void remove_from_xenstore_data (session_id s, VM ref self, string key)

Arguments:

type name description

VM ref self reference to the ob ject string key Key to remove

Return Type: void

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: create

Overview:

Create a new VM instance, and return its handle.

Signature:

(VM ref) create (session_id s, VM record args)

Arguments:

type name description

VM record args All constructor arguments

Return Type: VM ref

reference to the newly cr e ated object

RPC name: destroy

Overview:

Destroy the speciﬁed VM. The VM is completely removed from the system. This function can only be called when the VM is in the Halted State.

Signature:

void destroy (session_id s, VM ref self)

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: void

RPC name: get

Overview:

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

Signature:

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

Arguments:

type name description

string uuid UUID of object to return

Return Type: VM ref

reference to the object

by uuid

2.9. CLASS: VM CHAPTER 2. API REFERENCE

RPC name: get record

Overview:

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

Signature:

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

Arguments:

type name description

VM ref self reference to the ob ject

Return Type: VM record

all ﬁelds from the object

RPC name: get

Overview:

Get all the VM instances with the given label.

Signature:

((VM ref) Set) get_by_name_label (session_id s, string label)

Arguments:

type name description

string label label of object to return

Return Type: (VM ref) Set

references to objects with matching names

by name label

2.10. CLASS: VM METRICS CHAPTER 2. API REFERENCE

2.10 Class: VM metrics

2.10.1 Fields for class: VM

metrics

Name VM metrics Description

The metrics associated with a VM.

Quals Field Type Description

RO RO RO RO

run

uuid string unique identiﬁer/object reference memory/actual int Guest’s actual memory (bytes) VCPUs/number int Current number of VCPUs VCPUs/utilisation (int → ﬂoat) Map Utilisation for all of guest’s current

VCPUs

RO RO

run

VCPUs/CPU (int → int) Map VCPU to PCPU map VCPUs/params (string → string ) Map The live eq uivalent to

VM.VCPUs params

RO RO

run

VCPUs/flags (int → string Set) Map CPU ﬂags (blocked,online,running) state string Set The state of the guest, eg blocked,

dying etc

run

start time datetime Time at which this VM was last

booted

RO RO

run

install time datetime Time at which the VM was installed last updated datetime Time at which this information was

last updated

2.10.2 RPCs associated with class: VM metrics

RPC name: get

all

Overview:

Return a list of all the VM

metrics instances known to the s ystem.

Signature:

((VM_metrics ref) Set) get_all (session_id s)

Return Type: (VM

metrics ref) Set

references to all objects

RPC name: get

all records

Overview:

Return a map of VM

metrics references to VM metrics records for all VM metr ic s instances known

to the system.

Signature:

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

Return Type: (VM

metrics ref → VM metrics record) Map

records of all objects

2.10. CLASS: VM METRICS CHAPTER 2. API REFERENCE

RPC name: get uuid

Overview:

Get the uuid ﬁeld of the given VM

metrics.

Signature:

string get_uuid (session_id s, VM_metrics ref self)

Arguments:

type name description

VM metrics ref self reference to the ob ject

Return Type: string

value of the ﬁeld

RPC name: get

memory actual

Overview:

Get the memory/actual ﬁeld of the given VM

metrics.

Signature:

int get_memory_actual (session_id s, VM_metrics ref self)

Arguments:

type name description

VM metrics ref self reference to the ob ject

Return Type: int

value of the ﬁeld

RPC name: get

VCPUs number

Overview:

Get the VCPUs/number ﬁeld of the given VM

metrics.

Signature:

int get_VCPUs_number (session_id s, VM_metrics ref self)

Arguments:

type name description

VM metrics ref self reference to the ob ject

Return Type: int

value of the ﬁeld

100

Citrix XenEnterprise Management API

Specifications and Main Features

Frequently Asked Questions

User Manual