Xen Management API Revision 1.0.6, 13 Oct. 2008, PDF

Xen Management API Revision 1.0.6, 13 Oct. 2008, PDF
Xen Management API
API Revision 1.0.6
Xen Management API
Version: API Revision 1.0.6
Date: 24th July 2008
Stable Release
Ewan Mellor: ewan@xensource.com
Richard Sharp: richard.sharp@xensource.com
David Scott: david.scott@xensource.com
Contributors:
Stefan Berger, IBM
Daniel Berrangé, Red Hat
Gareth Bestor, IBM
Hollis Blanchard, IBM
Mike Day, IBM
Jim Fehlig, Novell
Jon Harrop, XenSource
Vincent Hanquez, XenSource
John Levon, Sun Microsystems
Jon Ludlam, XenSource
Alastair Tse, XenSource
Daniel Veillard, Red Hat
Tom Wilkie, University of Cambridge
Yosuke Iwamatsu, NEC
c 2006-2007 XenSource, Inc.
Copyright Permission is granted to copy, distribute and/or modify this document under the terms of the
GNU Free Documentation License, Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy
of the license is included in the section entitled ”GNU Free Documentation License”.
Revision History
1.0.0
27th April 07
Xensource et al.
Initial Revision
1.0.1
10th Dec. 07
S. Berger
1.0.2
1.0.3
25th Jan. 08
11th Feb. 08
J. Fehlig
S. Berger
1.0.4
1.0.5
23rd March 08
17th Apr. 08
S. Berger
S. Berger
1.0.6
24th Jul. 08
Y. Iwamatsu
Added XSPolicy.reset xspolicy,
VTPM.get other config,
VTPM.set otherconfig.
ACMPolicy.get enforced binary methods.
Added Crashed VM power state.
Added table of contents and hyperlink cross
reference.
Added XSPolicy.can run
Added undocumented fields and methods for
default netmask and default gateway to the
Network class. Removed an unimplemented
method from the XSPolicy class and removed
the ’optional’ from ’oldlabel’ parameters.
Added definitions of new classes DPCI and
PPCI. Updated the table and the diagram
representing relationships between classes.
Added host.PPCIs and VM.DPCIs fields.
2
Contents
1 Introduction
1.1 RPCs associated with fields . . . . . .
1.2 RPCs associated with classes . . . . .
1.2.1 Additional RPCs . . . . . . . .
1.3 Wire Protocol for Remote API Calls .
1.3.1 Note on References vs UUIDs .
1.3.2 Return Values/Status Codes .
1.4 Making XML-RPC Calls . . . . . . . .
1.4.1 Transport Layer . . . . . . . .
1.4.2 Session Layer . . . . . . . . . .
1.4.3 Synchronous and Asynchronous
1.5 Example interactive session . . . . . .
1.6 VM Lifecycle . . . . . . . . . . . . . .
1.7 VM boot parameters . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4
5
5
5
6
7
7
8
8
8
8
9
11
11
2 API Reference
2.1 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Relationships Between Classes . . . . . . . . . . . . . .
2.2.1 List of bound fields . . . . . . . . . . . . . . . .
2.3 Types . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Primitives . . . . . . . . . . . . . . . . . . . . .
2.3.2 Higher order types . . . . . . . . . . . . . . . .
2.3.3 Enumeration types . . . . . . . . . . . . . . . .
2.4 Error Handling . . . . . . . . . . . . . . . . . . . . . .
2.4.1 Error Codes . . . . . . . . . . . . . . . . . . . .
2.5 Class: session . . . . . . . . . . . . . . . . . . . . . . .
2.5.1 Fields for class: session . . . . . . . . . . . . .
2.5.2 RPCs associated with class: session . . . . . .
2.6 Class: task . . . . . . . . . . . . . . . . . . . . . . . .
2.6.1 Fields for class: task . . . . . . . . . . . . . . .
2.6.2 RPCs associated with class: task . . . . . . . .
2.7 Class: event . . . . . . . . . . . . . . . . . . . . . . . .
2.7.1 Fields for class: event . . . . . . . . . . . . . .
2.7.2 RPCs associated with class: event . . . . . . .
2.8 Class: VM . . . . . . . . . . . . . . . . . . . . . . . . .
2.8.1 Fields for class: VM . . . . . . . . . . . . . . .
2.8.2 RPCs associated with class: VM . . . . . . . .
2.9 Class: VM metrics . . . . . . . . . . . . . . . . . . . .
2.9.1 Fields for class: VM metrics . . . . . . . . . . .
2.9.2 RPCs associated with class: VM metrics . . . .
2.10 Class: VM guest metrics . . . . . . . . . . . . . . . . .
2.10.1 Fields for class: VM guest metrics . . . . . . .
2.10.2 RPCs associated with class: VM guest metrics
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
13
13
14
14
14
15
15
17
18
22
22
22
25
25
25
30
30
30
32
32
33
62
62
62
67
67
67
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
invocation
. . . . . . .
. . . . . . .
. . . . . . .
3
.
.
.
.
.
.
.
.
.
.
.
.
.
CONTENTS
2.11 Class:
2.11.1
2.11.2
2.12 Class:
2.12.1
2.12.2
2.13 Class:
2.13.1
2.13.2
2.14 Class:
2.14.1
2.14.2
2.15 Class:
2.15.1
2.15.2
2.16 Class:
2.16.1
2.16.2
2.17 Class:
2.17.1
2.17.2
2.18 Class:
2.18.1
2.18.2
2.19 Class:
2.19.1
2.19.2
2.20 Class:
2.20.1
2.20.2
2.21 Class:
2.21.1
2.21.2
2.22 Class:
2.22.1
2.22.2
2.23 Class:
2.23.1
2.23.2
2.24 Class:
2.24.1
2.24.2
2.25 Class:
2.25.1
2.25.2
2.26 Class:
2.26.1
2.26.2
2.27 Class:
2.27.1
2.27.2
2.28 Class:
2.28.1
2.28.2
CONTENTS
host . . . . . . . . . . . . . . . . . . . . .
Fields for class: host . . . . . . . . . . . .
RPCs associated with class: host . . . . .
host metrics . . . . . . . . . . . . . . . . .
Fields for class: host metrics . . . . . . .
RPCs associated with class: host metrics
host cpu . . . . . . . . . . . . . . . . . . .
Fields for class: host cpu . . . . . . . . .
RPCs associated with class: host cpu . .
network . . . . . . . . . . . . . . . . . . .
Fields for class: network . . . . . . . . . .
RPCs associated with class: network . . .
VIF . . . . . . . . . . . . . . . . . . . . .
Fields for class: VIF . . . . . . . . . . . .
RPCs associated with class: VIF . . . . .
VIF metrics . . . . . . . . . . . . . . . . .
Fields for class: VIF metrics . . . . . . .
RPCs associated with class: VIF metrics
PIF . . . . . . . . . . . . . . . . . . . . . .
Fields for class: PIF . . . . . . . . . . . .
RPCs associated with class: PIF . . . . .
PIF metrics . . . . . . . . . . . . . . . . .
Fields for class: PIF metrics . . . . . . . .
RPCs associated with class: PIF metrics .
SR . . . . . . . . . . . . . . . . . . . . . .
Fields for class: SR . . . . . . . . . . . . .
RPCs associated with class: SR . . . . . .
VDI . . . . . . . . . . . . . . . . . . . . .
Fields for class: VDI . . . . . . . . . . . .
RPCs associated with class: VDI . . . . .
VBD . . . . . . . . . . . . . . . . . . . . .
Fields for class: VBD . . . . . . . . . . .
RPCs associated with class: VBD . . . .
VBD metrics . . . . . . . . . . . . . . . .
Fields for class: VBD metrics . . . . . . .
RPCs associated with class: VBD metrics
PBD . . . . . . . . . . . . . . . . . . . . .
Fields for class: PBD . . . . . . . . . . .
RPCs associated with class: PBD . . . .
crashdump . . . . . . . . . . . . . . . . . .
Fields for class: crashdump . . . . . . . .
RPCs associated with class: crashdump .
VTPM . . . . . . . . . . . . . . . . . . . .
Fields for class: VTPM . . . . . . . . . .
RPCs associated with class: VTPM . . .
console . . . . . . . . . . . . . . . . . . . .
Fields for class: console . . . . . . . . . .
RPCs associated with class: console . . .
DPCI . . . . . . . . . . . . . . . . . . . .
Fields for class: DPCI . . . . . . . . . . .
RPCs associated with class: DPCI . . . .
PPCI . . . . . . . . . . . . . . . . . . . . .
Fields for class: PPCI . . . . . . . . . . .
RPCs associated with class: PPCI . . . .
4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
71
71
71
85
85
85
88
88
88
93
93
93
100
100
100
110
110
110
113
113
113
119
119
119
122
122
122
128
128
128
137
137
137
147
147
147
150
150
150
154
154
154
157
157
157
161
161
161
165
165
165
170
170
170
CONTENTS
2.29 Class:
2.29.1
2.29.2
2.30 Class:
2.30.1
2.30.2
2.30.3
2.30.4
2.31 Class:
2.31.1
2.31.2
2.32 Class:
2.32.1
2.32.2
CONTENTS
user . . . . . . . . . . . . . . . . . . . . . . . . .
Fields for class: user . . . . . . . . . . . . . . . .
RPCs associated with class: user . . . . . . . . .
XSPolicy . . . . . . . . . . . . . . . . . . . . . . .
Fields for class: XSPolicy . . . . . . . . . . . . .
Semantics of the class: XSPolicy . . . . . . . . .
Structure and datatypes of class: XSPolicy . . .
Additional RPCs associated with class: XSPolicy
ACMPolicy . . . . . . . . . . . . . . . . . . . . .
Fields for class: ACMPolicy . . . . . . . . . . . .
Structure and datatypes of class: ACMPolicy . .
debug . . . . . . . . . . . . . . . . . . . . . . . .
Fields for class: debug . . . . . . . . . . . . . . .
RPCs associated with class: debug . . . . . . . .
3 GNU Free Documentation License
1. APPLICABILITY AND DEFINITIONS . . . . . . . . .
2. VERBATIM COPYING . . . . . . . . . . . . . . . . . .
3. COPYING IN QUANTITY . . . . . . . . . . . . . . . .
4. MODIFICATIONS . . . . . . . . . . . . . . . . . . . . .
5. COMBINING DOCUMENTS . . . . . . . . . . . . . . .
6. COLLECTIONS OF DOCUMENTS . . . . . . . . . . .
7. AGGREGATION WITH INDEPENDENT WORKS . .
8. TRANSLATION . . . . . . . . . . . . . . . . . . . . . .
9. TERMINATION . . . . . . . . . . . . . . . . . . . . . .
10. FUTURE REVISIONS OF THIS LICENSE . . . . . .
ADDENDUM: How to use this License for your documents
5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
177
177
177
180
180
180
180
181
185
185
185
189
189
189
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
191
191
192
192
193
194
195
195
195
195
195
196
Chapter 1
Introduction
This document contains a description of the Xen Management API—an interface for remotely
configuring and controlling virtualised guests running on a Xen-enabled host.
The API is presented here as a set of Remote Procedure Calls, with a wire format based upon
XML-RPC. No specific language bindings are prescribed, although examples will be given in the
python programming language.
Although we adopt some terminology from object-oriented programming, future client language
bindings may or may not be object oriented. The API reference uses the terminology classes and
objects. For our purposes a class is simply a hierarchical namespace; an object is an instance of
a class with its fields set to specific values. Objects are persistent and exist on the server-side.
Clients may obtain opaque references to these server-side objects and then access their fields via
get/set RPCs.
For each class we specify a list of fields along with their types and qualifiers. A qualifier is one of:
• RO run : the field is Read Only. Furthermore, its value is automatically computed at runtime.
For example: current CPU load and disk IO throughput.
• RO ins : the field must be manually set when a new object is created, but is then Read Only
for the duration of the object’s life. For example, the maximum memory addressable by a
guest is set before the guest boots.
• RW : the field is Read/Write. For example, the name of a VM.
A full list of types is given in Chapter 2. However, there are three types that require explicit
mention:
• t Ref : signifies a reference to an object of type t.
• t Set : signifies a set containing values of type t.
• (t1 , t2 ) Map: signifies a mapping from values of type t1 to values of type t2 .
Note that there are a number of cases where Refs are doubly linked —e.g. a VM has a field called
VIFs of type (VIF Ref ) Set ; this field lists the network interfaces attached to a particular VM.
Similarly, the VIF class has a field called VM of type (VM Ref) which references the VM to which
the interface is connected. These two fields are bound together , in the sense that creating a new
VIF causes the VIFs field of the corresponding VM object to be updated automatically.
The API reference explicitly lists the fields that are bound together in this way. It also contains a
diagram that shows relationships between classes. In this diagram an edge signifies the existence
of a pair of fields that are bound together, using standard crows-foot notation to signify the type
of relationship (e.g. one-many, many-many).
6
1.1. RPCS ASSOCIATED WITH FIELDS
1.1
CHAPTER 1. INTRODUCTION
RPCs associated with fields
Each field, f, has an RPC accessor associated with it that returns f’s value:
• “get f(Ref x)”: takes a Ref that refers to an object and returns the value of f.
Each field, f, with attribute RW and whose outermost type is Set has the following additional
RPCs associated with it:
• an “add to f(Ref x, v)” RPC adds a new element v to the set1 ;
• a “remove from f(Ref x, v)” RPC removes element v from the set;
Each field, f, with attribute RW and whose outermost type is Map has the following additional
RPCs associated with it:
• an “add to f(Ref x, k, v)” RPC adds new pair (k, v) to the mapping stored in 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 field whose outermost type is neither Set nor Map, but whose attribute is RW has an RPC
acessor associated with it that sets its value:
• For RW (Read/W rite), a “set f(Ref x, v)” RPC function is also provided. This sets field
f on object x to value v.
1.2
RPCs associated with classes
• Each class has a constructor RPC named “create” that takes as parameters all fields marked
RW and RO ins . The result of this RPC is that a new persistent object is created on the
server-side with the specified field values.
• Each class has a get by uuid(uuid) RPC that returns the object of that class that has the
specified uuid.
• Each class that has a name label field has a “get by name label(name)” RPC that returns
a set of objects of that class that have the specified label.
• Each class has a “destroy(Ref x)” RPC that explicitly deletes the persistent object specified 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 cloning, suspending, starting etc. Such additional RPCs
are described explicitly in the API reference.
1
Since sets cannot contain duplicate values this operation has no action in the case that v was already in the
set.
7
1.3. WIRE PROTOCOL FOR REMOTE API CALLS
1.3
CHAPTER 1. INTRODUCTION
Wire Protocol for Remote API Calls
API calls are sent over a network to a Xen-enabled host using the XML-RPC protocol. In this
Section we describe how the higher-level types used in our API Reference are mapped to primitive
XML-RPC types.
In our API Reference we specify the signatures of API functions in the following style:
(ref_vm Set)
VM.get_all()
This specifies that the function with name VM.get all takes no parameters and returns a Set of
ref vms. These types are mapped onto XML-RPC types in a straight-forward manner:
• Floats, Bools, DateTimes and Strings map directly to the XML-RPC double, boolean,
dateTime.iso8601, and string elements.
• all “ref ” types are opaque references, encoded as the XML-RPC’s String type. Users of
the API should not make assumptions about the concrete form of these strings and should
not expect them to remain valid after the client’s session with the server has terminated.
• fields named “uuid” of type “String” are mapped to the XML-RPC String type. The
string itself is the OSF DCE UUID presentation format (as output by uuidgen, etc).
• ints are all assumed to be 64-bit in our API and are encoded as a string of decimal digits
(rather than using XML-RPC’s built-in 32-bit i4 type).
• values of enum types are encoded as strings. For example, a value of destroy of type
on normal exit, would be conveyed as:
<value><string>destroy</string></value>
• for all our types, t, our type t Set simply maps to XML-RPC’s Array type, so for example
a value of type cpu feature Set would be transmitted like this:
<array>
<data>
<value><string>CX8</string></value>
<value><string>PSE36</string></value>
<value><string>FPU</string></value>
</data>
</array>
• for types k and v, our type (k, v) Map maps onto an XML-RPC struct, with the key as
the name of the struct. Note that the (k, v) Map type is only valid when k is a String,
Ref, or Int, and in each case the keys of the maps are stringified as above. For example,
the (String, double) Map containing a the mappings Mike → 2.3 and John → 1.2 would
be represented as:
<value>
<struct>
<member>
<name>Mike</name>
<value><double>2.3</double></value>
</member>
<member>
8
1.3. WIRE PROTOCOL FOR REMOTE API CALLS
CHAPTER 1. INTRODUCTION
<name>John</name>
<value><double>1.2</double></value>
</member>
</struct>
</value>
• our Void type is transmitted as an empty string.
1.3.1
Note on References vs UUIDs
References are opaque types — encoded as XML-RPC strings on the wire — understood only by
the particular server which generated them. Servers are free to choose any concrete representation
they find convenient; clients should not make any assumptions or attempt to parse the string
contents. References are not guaranteed to be permanent identifiers for objects; clients should not
assume that references generated during one session are valid for any future session. References
do not allow objects to be compared for equality. Two references to the same object are not
guaranteed to be textually identical.
UUIDs are intended to be permanent names for objects. They are guaranteed to be in the OSF
DCE UUID presentation format (as output by uuidgen. Clients may store UUIDs on disk and
use them to lookup objects in subsequent sessions with the server. Clients may also test equality
on objects by comparing UUID strings.
The API provides mechanisms for translating between UUIDs and opaque references. Each class
that contains a UUID field provides:
• A “get by uuid” method that takes a UUID, u, and returns an opaque reference to the
server-side object that has UUID=u;
• A get uuid function (a regular “field getter” RPC) that takes an opaque reference, r, and
returns the UUID of the server-side object that is referenced by r.
1.3.2
Return Values/Status Codes
The return value of an RPC call is an XML-RPC Struct.
• The first element of the struct is named Status; it contains a string value indicating whether
the result of the call was a “Success” or a “Failure”.
If Status was set to Success then the Struct contains a second element named Value:
• The element of the struct named Value contains the function’s return value.
In the case where Status is set to Failure then the struct contains a second element named
ErrorDescription:
• The element of the struct named ErrorDescription contains an array of string values. The
first element of the array is an error code; the remainder of the array are strings representing
error parameters relating to that code.
For example, an XML-RPC return value from the host.get resident VMs function above may
look like this:
<struct>
<member>
<name>Status</name>
<value>Success</value>
</member>
9
1.4. MAKING XML-RPC CALLS
CHAPTER 1. INTRODUCTION
<member>
<name>Value</name>
<value>
<array>
<data>
<value>81547a35-205c-a551-c577-00b982c5fe00</value>
<value>61c85a22-05da-b8a2-2e55-06b0847da503</value>
<value>1d401ec4-3c17-35a6-fc79-cee6bd9811fe</value>
</data>
</array>
</value>
</member>
</struct>
1.4
Making XML-RPC Calls
1.4.1
Transport Layer
The following transport layers are currently supported:
• HTTP/S for remote administration
• HTTP over Unix domain sockets for local administration
1.4.2
Session Layer
The XML-RPC interface is session-based; before you can make arbitrary RPC calls you must login
and initiate a session. For example:
session_id
session.login_with_password(string uname, string pwd)
Where uname and password refer to your username and password respectively, as defined by the
Xen administrator. The session id returned by session.login with password is passed to
subsequent RPC calls as an authentication token.
A session can be terminated with the session.logout function:
void
1.4.3
session.logout(session_id session)
Synchronous and Asynchronous invocation
Each method call (apart from methods on “Session” and “Task” objects and “getters” and “setters” derived from fields) can be made either synchronously or asynchronously. A synchronous
RPC call blocks until the return value is received; the return value of a synchronous RPC call is
exactly as specified in Section 1.3.2.
Only synchronous API calls are listed explicitly in this document. All asynchronous versions are
in the special Async namespace. For example, synchronous call VM.clone(...) (described in
Chapter 2) has an asynchronous counterpart, Async.VM.clone(...), that is non-blocking.
Instead of returning its result directly, an asynchronous RPC call returns a task-id; this identifier
is subsequently used to track the status of a running asynchronous RPC. Note that an asynchronous
call may fail immediately, before a task-id has even been created—to represent this eventuality,
the returned task-id is wrapped in an XML-RPC struct with a Status, ErrorDescription and
Value fields, exactly as specified in Section 1.3.2.
The task-id is provided in the Value field if Status is set to Success.
The RPC call
(ref_task Set)
Task.get_all(session_id s)
10
1.5. EXAMPLE INTERACTIVE SESSION
CHAPTER 1. INTRODUCTION
returns a set of all task IDs known to the system. The status (including any returned result and
error codes) of these tasks can then be queried by accessing the fields of the Task object in the
usual way. Note that, in order to get a consistent snapshot of a task’s state, it is advisable to call
the “get record” function.
1.5
Example interactive session
This section describes how an interactive session might look, using the python XML-RPC client
library.
First, initialise python and import the library xmlrpclib:
\$ python2.4
...
>>> import xmlrpclib
Create a python object referencing the remote server:
>>> xen = xmlrpclib.Server("http://test:4464")
Acquire a session token by logging in with a username and password (error-handling omitted for
brevity; the session token is pointed to by the key ’Value’ in the returned dictionary)
>>> session = session.login_with_password("user", "passwd")[’Value’]
When serialised, this call looks like the following:
<?xml version=’1.0’?>
<methodCall>
<methodName>session.login_with_password</methodName>
<params>
<param>
<value><string>user</string></value>
</param>
<param>
<value><string>passwd</string></value>
</param>
</params>
</methodCall>
Next, the user may acquire a list of all the VMs known to the host: (Note the call takes the session
token as the only parameter)
>>> all_vms = host.get_resident_VMs(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. Once a reference to a VM has been acquired
a lifecycle operation may be invoked:
>>> xen.VM.start(session, all_vms[3], False)
{’Status’: ’Failure’, ’ErrorDescription’: [’VM_BAD_POWER_STATE’, ’Halted’, ’Running’]}
In this case the start message has been rejected, because the VM is already running, and so an
error response has been returned. These high-level errors are returned as structured data (rather
than as XML-RPC faults), allowing them to be internationalised. Finally, here are some examples
of using accessors for object fields:
11
1.5. EXAMPLE INTERACTIVE SESSION
CHAPTER 1. INTRODUCTION
>>> xen.VM.get_name_label(session, all_vms[3])[’Value’]
’SMP’
>>> xen.VM.get_name_description(session, all_vms[3])[’Value’]
’Debian for Xen’
12
1.6. VM LIFECYCLE
CHAPTER 1. INTRODUCTION
powered down
start(paused=true)
start(paused=false)
cleanShutdown /
hardShutdown
paused
resume pause
hardShutdown
suspend resume(paused=true) running
suspend resume(paused=false)
suspended
guest OS crash
crashed
Figure 1.1: VM Lifecycle
1.6
VM Lifecycle
Figure 1.1 shows the states that a VM can be in and the API calls that can be used to move the
VM between these states. The crashed state indicates that the guest OS running within the VM
has crashed. There is no API to explicitly move to the crashed state, however a hardShutdown
will move the VM to the powered down state.
1.7
VM boot parameters
The VM class contains a number of fields that control the way in which the VM is booted. With
reference to the fields defined in the VM class (see later in this document), this section outlines
the boot options available and the mechanisms provided for controlling them.
VM booting is controlled by setting one of the two mutually exclusive groups: “PV”, and “HVM”.
If HVM.boot policy is the empty string, then paravirtual domain building and booting will be used;
otherwise the VM will be loaded as an HVM domain, and booted using an emulated BIOS.
When paravirtual booting is in use, the PV/bootloader field indicates the bootloader to use. It
may be “pygrub”, in which case the platform’s default installation of pygrub will be used, or
a full path within the control domain to some other bootloader. The other fields, PV/kernel,
PV/ramdisk, PV/args and PV/bootloader args will be passed to the bootloader unmodified, and
interpretation of those fields is then specific to the bootloader itself, including the possibility that
the bootloader will ignore some or all of those given values. Finally the paths of all bootable disks
are added to the bootloader commandline (a disk is bootable if its VBD has the bootable flag
set). There may be zero, one or many bootable disks; the bootloader decides which disk (if any)
to boot from.
If the bootloader is pygrub, then the menu.lst is parsed if present in the guest’s filesystem, otherwise
the specified kernel and ramdisk are used, or an autodetected kernel is used if nothing is specified
and autodetection is possible. PV/args is appended to the kernel command line, no matter which
mechanism is used for finding the kernel.
If PV/bootloader is empty but PV/kernel is specified, then the kernel and ramdisk values will be
treated as paths within the control domain. If both PV/bootloader and PV/kernel are empty,
13
1.7. VM BOOT PARAMETERS
CHAPTER 1. INTRODUCTION
then the behaviour is as if PV/bootloader was specified as “pygrub”.
When using HVM booting, HVM/boot policy and HVM/boot params specify the boot handling.
Only one policy is currently defined: “BIOS order”. In this case, HVM/boot params should
contain one key-value pair “order” = “N” where N is the string that will be passed to QEMU.
14
Chapter 2
API Reference
2.1
Classes
The following classes are defined:
Name
session
task
event
VM
VM metrics
VM guest metrics
host
host metrics
host cpu
network
VIF
VIF metrics
PIF
PIF metrics
SR
VDI
VBD
VBD metrics
PBD
crashdump
VTPM
console
DPCI
PPCI
user
debug
XSPolicy
ACMPolicy
2.2
Description
A session
A long-running asynchronous task
Asynchronous event registration and handling
A virtual machine (or ’guest’)
The metrics associated with a VM
The metrics reported by the guest (as opposed to inferred from
outside)
A physical host
The metrics associated with a host
A physical CPU
A virtual network
A virtual network interface
The metrics associated with a virtual network device
A physical network interface (note separate VLANs are represented as several PIFs)
The metrics associated with a physical network interface
A storage repository
A virtual disk image
A virtual block device
The metrics associated with a virtual block device
The physical block devices through which hosts access SRs
A VM crashdump
A virtual TPM device
A console
A pass-through PCI device
A physical PCI device
A user of the system
A basic class for testing
A class for handling Xen Security Policies
A class for handling ACM-type policies
Relationships Between Classes
Fields that are bound together are shown in the following table:
15
2.3. TYPES
CHAPTER 2. API REFERENCE
object.field
host.PBDs
SR.PBDs
VDI.VBDs
VDI.crash dumps
VBD.VM
crashdump.VM
VIF.VM
VIF.network
PIF.host
PIF.network
SR.VDIs
VTPM.VM
console.VM
DPCI.VM
PPCI.host
host.resident VMs
host.host CPUs
object.field
PBD.host
PBD.SR
VBD.VDI
crashdump.VDI
VM.VBDs
VM.crash dumps
VM.VIFs
network.VIFs
host.PIFs
network.PIFs
VDI.SR
VM.VTPMs
VM.consoles
VM.DPCIs
host.PPCIs
VM.resident on
host cpu.host
relationship
many-to-one
many-to-one
many-to-one
many-to-one
one-to-many
one-to-many
one-to-many
one-to-many
one-to-many
one-to-many
many-to-one
one-to-many
one-to-many
one-to-many
one-to-many
many-to-one
many-to-one
The following represents bound fields (as specified above) diagrammatically, using crows-foot notation to specify one-to-one, one-to-many or many-to-many relationships:
VIF_metrics
PIF_metrics
VM_guest_metrics
VTPM
network
VIF
host_cpu
console
PIF
VM
VM_metrics
DPCI
host_metrics
PPCI
host
VBD
user
session
XSPolicy
PBD
VBD_metrics
SR
VDI
ACMPolicy
PBD_metrics
2.2.1
2.3
2.3.1
List of bound fields
Types
Primitives
The following primitive types are used to specify methods and fields in the API Reference:
16
2.3. TYPES
CHAPTER 2. API REFERENCE
Type
String
Int
Float
Bool
DateTime
Ref (object name)
2.3.2
Description
text strings
64-bit integers
IEEE double-precision floating-point numbers
boolean
date and timestamp
reference to an object of class name
Higher order types
The following type constructors are used:
Type
List (t)
Map (a → b)
2.3.3
Description
an arbitrary-length list of elements of type t
a table mapping values of type a to values of type b
Enumeration types
The following enumeration types are used:
enum event operation
add
del
mod
enum console protocol
vt100
rfb
rdp
enum vdi type
system
user
ephemeral
suspend
crashdump
a
a
a
a
a
An object has been created
An object has been deleted
An object has been modified
VT100 terminal
Remote FrameBuffer protocol (as used in VNC)
Remote Desktop Protocol
disk
disk
disk
disk
disk
that
that
that
that
that
enum vm power state
Halted
Paused
Running
Suspended
Crashed
Unknown
may be replaced on upgrade
is always preserved on upgrade
may be reformatted on upgrade
stores a suspend image
stores VM crashdump information
Halted
Paused
Running
Suspended
Crashed
Some other unknown state
17
2.3. TYPES
CHAPTER 2. API REFERENCE
enum task allowed operations
Cancel
enum task status type
pending
success
failure
cancelling
cancelled
task
task
task
task
task
enum on normal exit
destroy
restart
enum on crash behaviour
destroy
coredump and destroy
restart
coredump and restart
preserve
rename restart
Cancel
is in progress
was completed successfully
has failed
is being cancelled
has been cancelled
destroy the VM state
restart the VM
destroy the VM state
record a coredump and then destroy the VM state
restart the VM
record a coredump and then restart the VM
leave the crashed VM as-is
rename the crashed VM and start a new copy
enum vbd mode
RO
RW
enum vbd type
CD
Disk
disk is mounted read-only
disk is mounted read-write
VBD will appear to guest as CD
VBD will appear to guest as disk
18
2.4. ERROR HANDLING
2.4
CHAPTER 2. API REFERENCE
Error Handling
When a low-level transport error occurs, or a request is malformed at the HTTP or XML-RPC
level, the server may send an XML-RPC Fault response, or the client may simulate the same. The
client must be prepared to handle these errors, though they may be treated as fatal. On the wire,
these are transmitted in a form similar to this:
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value><int>-1</int></value>
</member>
<member>
<name>faultString</name>
<value><string>Malformed request</string></value>
</member>
</struct>
</value>
</fault>
</methodResponse>
All other failures are reported with a more structured error response, to allow better automatic
response to failures, proper internationalisation of any error message, and easier debugging. On
the wire, these are transmitted like this:
<struct>
<member>
<name>Status</name>
<value>Failure</value>
</member>
<member>
<name>ErrorDescription</name>
<value>
<array>
<data>
<value>MAP_DUPLICATE_KEY</value>
<value>Customer</value>
<value>eSpeil Inc.</value>
<value>eSpeil Incorporated</value>
</data>
</array>
</value>
</member>
</struct>
Note that ErrorDescription value is an array of string values. The first element of the array
is an error code; the remainder of the array are strings representing error parameters relating
to that code. In this case, the client has attempted to add the mapping Customer → eSpiel
Incorporated to a Map, but it already contains the mapping Customer → eSpiel Inc., and so
the request has failed.
The reference below lists each possible error returned by each method. As well as the errors
explicitly listed, any method may return low-level errors as described above, or any of the following
generic errors:
19
2.4. ERROR HANDLING
CHAPTER 2. API REFERENCE
• HANDLE INVALID
• INTERNAL ERROR
• MAP DUPLICATE KEY
• MESSAGE METHOD UNKNOWN
• MESSAGE PARAMETER COUNT MISMATCH
• OPERATION NOT ALLOWED
• PERMISSION DENIED
• SESSION INVALID
Each possible error code is documented in the following section.
2.4.1
Error Codes
HANDLE INVALID
You gave an invalid handle. The object may have recently been deleted. The class parameter
gives the type of reference given, and the handle parameter echoes the bad value given.
Signature:
HANDLE_INVALID(class, handle)
INTERNAL ERROR
The server failed to handle your request, due to an internal error. The given message may give
details useful for debugging the problem.
Signature:
INTERNAL_ERROR(message)
MAP DUPLICATE KEY
You tried to add a key-value pair to a map, but that key is already there. The key, current value,
and the new value that you tried to set are all echoed.
Signature:
MAP_DUPLICATE_KEY(key, current value, new value)
MESSAGE METHOD UNKNOWN
You tried to call a method that does not exist. The method name that you used is echoed.
Signature:
MESSAGE_METHOD_UNKNOWN(method)
20
2.4. ERROR HANDLING
CHAPTER 2. API REFERENCE
MESSAGE PARAMETER COUNT MISMATCH
You tried to call a method with the incorrect number of parameters. The fully-qualified method
name that you used, and the number of received and expected parameters are returned.
Signature:
MESSAGE_PARAMETER_COUNT_MISMATCH(method, expected, received)
NETWORK ALREADY CONNECTED
You tried to create a PIF, but the network you tried to attach it to is already attached to some
other PIF, and so the creation failed.
Signature:
NETWORK_ALREADY_CONNECTED(network, connected PIF)
OPERATION NOT ALLOWED
You attempted an operation that was not allowed.
No parameters.
PERMISSION DENIED
You do not have the required permissions to perform the operation.
No parameters.
PIF IS PHYSICAL
You tried to destroy a PIF, but it represents an aspect of the physical host configuration, and so
cannot be destroyed. The parameter echoes the PIF handle you gave.
Signature:
PIF_IS_PHYSICAL(PIF)
SESSION AUTHENTICATION FAILED
The credentials given by the user are incorrect, so access has been denied, and you have not been
issued a session handle.
No parameters.
21
2.4. ERROR HANDLING
CHAPTER 2. API REFERENCE
SESSION INVALID
You gave an invalid session handle. It may have been invalidated by a server restart, or timed
out. You should get a new session handle, using one of the session.login calls. This error does
not invalidate the current connection. The handle parameter echoes the bad value given.
Signature:
SESSION_INVALID(handle)
SESSION NOT REGISTERED
This session is not registered to receive events. You must call event.register before event.next.
The session handle you are using is echoed.
Signature:
SESSION_NOT_REGISTERED(handle)
VALUE NOT SUPPORTED
You attempted to set a value that is not supported by this implementation. The fully-qualified
field name and the value that you tried to set are returned. Also returned is a developer-only
diagnostic reason.
Signature:
VALUE_NOT_SUPPORTED(field, value, reason)
VLAN TAG INVALID
You tried to create a VLAN, but the tag you gave was invalid – it must be between 0 and 4095.
The parameter echoes the VLAN tag you gave.
Signature:
VLAN_TAG_INVALID(VLAN)
VM BAD POWER STATE
You attempted an operation on a VM that was not in an appropriate power state at the time; for
example, you attempted to start a VM that was already running. The parameters returned are
the VM’s handle, and the expected and actual VM state at the time of the call.
Signature:
VM_BAD_POWER_STATE(vm, expected, actual)
22
2.4. ERROR HANDLING
CHAPTER 2. API REFERENCE
VM HVM REQUIRED
HVM is required for this operation
Signature:
VM_HVM_REQUIRED(vm)
SECURITY ERROR
A security error occurred. The parameter provides the xen security error code and a message
describing the error.
Signature:
SECURITY_ERROR(xserr, message)
23
2.5. CLASS: SESSION
2.5
CHAPTER 2. API REFERENCE
Class: session
2.5.1
Fields for class: session
Name
Description
Quals
RO run
RO run
RO run
RO run
2.5.2
session
A session.
Field
uuid
this host
this user
last active
Type
string
host ref
user ref
int
Description
unique identifier/object reference
Currently connected host
Currently connected user
Timestamp for last time session was
active
RPCs associated with class: session
RPC name: login with password
Overview: Attempt to authenticate the user, returning a session id if successful.
Signature:
(session ref) login_with_password (string uname, string pwd)
Arguments:
type
string
string
name
uname
pwd
description
Username for login.
Password for login.
Return Type: session ref
ID of newly created session
Possible Error Codes: SESSION AUTHENTICATION FAILED
RPC name: logout
Overview: Log out of a session.
Signature:
void logout (session_id s)
Return Type: void
RPC name: get uuid
Overview: Get the uuid field of the given session.
Signature:
string get_uuid (session_id s, session ref self)
Arguments:
type
session ref
name
self
description
reference to the object
24
2.5. CLASS: SESSION
CHAPTER 2. API REFERENCE
Return Type: string
value of the field
RPC name: get this host
Overview: Get the this host field of the given session.
Signature:
(host ref) get_this_host (session_id s, session ref self)
Arguments:
type
session ref
name
self
description
reference to the object
Return Type: host ref
value of the field
RPC name: get this user
Overview: Get the this user field of the given session.
Signature:
(user ref) get_this_user (session_id s, session ref self)
Arguments:
type
session ref
name
self
description
reference to the object
Return Type: user ref
value of the field
RPC name: get last active
Overview: Get the last active field of the given session.
Signature:
int get_last_active (session_id s, session ref self)
Arguments:
type
session ref
name
self
description
reference to the object
Return Type: int
value of the field
25
2.5. CLASS: SESSION
CHAPTER 2. API REFERENCE
RPC name: get by uuid
Overview: Get a reference to the session instance with the specified UUID.
Signature:
(session ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: session ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given session.
Signature:
(session record) get_record (session_id s, session ref self)
Arguments:
type
session ref
name
self
description
reference to the object
Return Type: session record
all fields from the object
26
2.6. CLASS: TASK
2.6
2.6.1
CHAPTER 2. API REFERENCE
Class: task
Fields for class: task
Name
Description
Quals
RO run
RO run
RO run
task
A long-running asynchronous task.
Field
Type
uuid
string
name/label
string
name/description
string
RO run
RO run
RO run
status
session
progress
task status type
session ref
int
RO run
type
string
RO run
result
string
RO run
error info
string Set
RO run
allowed operations
(task allowed operations) Set
2.6.2
Description
unique identifier/object reference
a human-readable name
a notes field containg humanreadable description
current status of the task
the session that created the task
if the task is still pending, this
field contains the estimated percentage complete (0-100). If task has
completed (successfully or unsuccessfully) this should be 100.
if the task has completed successfully,
this field contains the type of the encoded result (i.e. name of the class
whose reference is in the result field).
Undefined otherwise.
if the task has completed successfully,
this field contains the result value (either Void or an object reference). Undefined otherwise.
if the task has failed, this field
contains the set of associated error
strings. Undefined otherwise.
Operations allowed on this task
RPCs associated with class: task
RPC name: cancel
Overview: Cancel this task. If task.allowed operations does not contain Cancel, then this will fail
with OPERATION NOT ALLOWED. The task will show the status ’cancelling’, and you should
continue to check its status until it shows ’cancelled’. There is no guarantee as to the time within
which this task will be cancelled.
Signature:
void cancel (session_id s, task ref task)
Arguments:
type
task ref
name
task
description
The task
Return Type: void
Possible Error Codes: OPERATION NOT ALLOWED
27
2.6. CLASS: TASK
CHAPTER 2. API REFERENCE
RPC name: get all
Overview: Return a list of all the tasks known to the system.
Signature:
((task ref) Set) get_all (session_id s)
Return Type: (task ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given task.
Signature:
string get_uuid (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get name label
Overview: Get the name/label field of the given task.
Signature:
string get_name_label (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get name description
Overview: Get the name/description field of the given task.
Signature:
string get_name_description (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: string
28
2.6. CLASS: TASK
CHAPTER 2. API REFERENCE
value of the field
RPC name: get status
Overview: Get the status field of the given task.
Signature:
(task_status_type) get_status (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: task status type
value of the field
RPC name: get session
Overview: Get the session field of the given task.
Signature:
(session ref) get_session (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: session ref
value of the field
RPC name: get progress
Overview: Get the progress field of the given task.
Signature:
int get_progress (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: int
value of the field
29
2.6. CLASS: TASK
CHAPTER 2. API REFERENCE
RPC name: get type
Overview: Get the type field of the given task.
Signature:
string get_type (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get result
Overview: Get the result field of the given task.
Signature:
string get_result (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get error info
Overview: Get the error info field of the given task.
Signature:
(string Set) get_error_info (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: string Set
value of the field
RPC name: get allowed operations
Overview: Get the allowed operations field of the given task.
Signature:
((task_allowed_operations) Set) get_allowed_operations (session_id s, task ref self)
30
2.6. CLASS: TASK
CHAPTER 2. API REFERENCE
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: (task allowed operations) Set
value of the field
RPC name: get by uuid
Overview: Get a reference to the task instance with the specified UUID.
Signature:
(task ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: task ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given task.
Signature:
(task record) get_record (session_id s, task ref self)
Arguments:
type
task ref
name
self
description
reference to the object
Return Type: task record
all fields from the object
RPC name: get by name label
Overview: Get all the task instances with the given label.
Signature:
((task ref) Set) get_by_name_label (session_id s, string label)
Arguments:
type
string
name
label
description
label of object to return
Return Type: (task ref) Set
references to objects with match names
31
2.7. CLASS: EVENT
2.7
CHAPTER 2. API REFERENCE
Class: event
2.7.1
Fields for class: event
Name
Description
Quals
RO ins
event
Asynchronous event registration and handling.
Field
Type
Description
id
int
An ID, monotonically increasing, and
local to the current session
timestamp datetime
The time at which the event occurred
class
string
The name 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
RO ins
RO ins
RO ins
RO ins
RO ins
2.7.2
RPCs associated with class: event
RPC name: register
Overview: Registers this session with the event system. Specifying the empty list will register
for all classes.
Signature:
void register (session_id s, string Set classes)
Arguments:
type
string Set
name
classes
description
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
string Set
name
classes
description
remove this session’s registration for the indicated classes
Return Type: void
RPC name: next
Overview: Blocking call which returns a (possibly empty) batch of events.
Signature:
32
2.7. CLASS: EVENT
CHAPTER 2. API REFERENCE
((event record) Set) next (session_id s)
Return Type: (event record) Set
the batch of events
Possible Error Codes: SESSION NOT REGISTERED
33
2.8. CLASS: VM
2.8
2.8.1
CHAPTER 2. API REFERENCE
Class: VM
Fields for class: VM
Name
Description
Quals
RO run
RO run
RW
RW
VM
A virtual machine (or ’guest’).
Field
Type
uuid
string
power state
vm power state
name/label
string
name/description
string
RW
user version
int
RW
is a template
bool
RW
auto power on
bool
RO run
suspend VDI
VDI ref
RO run
resident on
host ref
RW
memory/static max
int
RW
RW
RW
memory/dynamic max
memory/dynamic min
memory/static min
int
int
int
RW
VCPUs/params
(string → string) Map
RW
RW
RW
VCPUs/max
VCPUs/at startup
actions/after shutdown
int
int
on normal exit
RW
actions/after reboot
on normal exit
RW
RO run
RO run
RO run
RO run
RO run
RO run
RW
RW
RW
RW
RW
actions/after crash
consoles
VIFs
VBDs
crash dumps
VTPMs
DPCIs
PV/bootloader
PV/kernel
PV/ramdisk
PV/args
PV/bootloader args
on crash behaviour
(console ref) Set
(VIF ref) Set
(VBD ref) Set
(crashdump ref) Set
(VTPM ref) Set
(DPCI ref) Set
string
string
string
string
string
RW
RW
RW
HVM/boot policy
HVM/boot params
platform
string
(string → string) Map
(string → string) Map
34
Description
unique identifier/object reference
Current power state of the machine
a human-readable name
a notes field containg humanreadable description
a user version number for this machine
true if this is a template. Template
VMs can never be started, they are
used only for cloning other VMs
true if this VM should be started automatically after host boot
The VDI that a suspend image is
stored on. (Only has meaning if VM
is currently suspended)
the host the VM is currently resident
on
Statically-set (i.e. absolute) maximum (bytes)
Dynamic maximum (bytes)
Dynamic minimum (bytes)
Statically-set (i.e. absolute) minimum (bytes)
configuration parameters for the selected VCPU policy
Max number of VCPUs
Boot number of VCPUs
action to take after the guest has
shutdown itself
action to take after the guest has rebooted itself
action to take if the guest crashes
virtual console devices
virtual network interfaces
virtual block devices
crash dumps associated with this VM
virtual TPMs
pass-through PCI devices
name of or path to bootloader
path to the kernel
path to the initrd
kernel command-line arguments
miscellaneous arguments for the
bootloader
HVM boot policy
HVM boot params
platform-specific configuration
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RW
PCI bus
string
RW
RO run
RO run
other config
domid
is control domain
(string → string) Map
int
bool
RO run
RO run
metrics
guest metrics
VM metrics ref
VM guest metrics ref
RO run
security/label
string
2.8.2
PCI bus path for pass-through devices
additional configuration
domain ID (if available, -1 otherwise)
true if this is a control domain (domain 0 or a driver domain)
metrics associated with this VM
metrics associated with the running
guest
the VM’s security label
RPCs associated with class: VM
RPC name: clone
Overview: Clones the specified VM, making a new VM. Clone automatically exploits the capabilities of the underlying storage repository in which the VM’s disk images are stored (e.g. Copy
on Write). This function can 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
VM ref
string
name
vm
new name
description
The VM to be cloned
The name of the cloned VM
Return Type: VM ref
The ID of the newly created VM.
Possible Error Codes: VM BAD POWER STATE
RPC name: start
Overview: Start the specified 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)
Arguments:
type
VM ref
bool
name
vm
start paused
description
The VM to start
Instantiate VM in paused state if set to true.
Return Type: void
Possible Error Codes: VM BAD POWER STATE, VM HVM REQUIRED
RPC name: pause
Overview: Pause the specified VM. This can only be called when the specified VM is in the
Running state.
Signature:
35
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
void pause (session_id s, VM ref vm)
Arguments:
type
VM ref
name
vm
description
The VM to pause
Return Type: void
Possible Error Codes: VM BAD POWER STATE
RPC name: unpause
Overview: Resume the specified VM. This can only be called when the specified VM is in the
Paused state.
Signature:
void unpause (session_id s, VM ref vm)
Arguments:
type
VM ref
name
vm
description
The VM to unpause
Return Type: void
Possible Error Codes: VM BAD POWER STATE
RPC name: clean shutdown
Overview: Attempt to cleanly shutdown the specified VM. (Note: this may not be supported—
e.g. if a guest agent is not installed).
Once shutdown has been completed perform poweroff action specified in guest configuration.
This can only be called when the specified VM is in the Running state.
Signature:
void clean_shutdown (session_id s, VM ref vm)
Arguments:
type
VM ref
name
vm
description
The VM to shutdown
Return Type: void
Possible Error Codes: VM BAD POWER STATE
RPC name: clean reboot
Overview: Attempt to cleanly shutdown the specified VM (Note: this may not be supported—
e.g. if a guest agent is not installed).
Once shutdown has been completed perform reboot action specified in guest configuration.
This can only be called when the specified VM is in the Running state.
Signature:
void clean_reboot (session_id s, VM ref vm)
36
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
name
vm
description
The VM to shutdown
Return Type: void
Possible Error Codes: VM BAD POWER STATE
RPC name: hard shutdown
Overview: Stop executing the specified VM without attempting a clean shutdown. Then perform
poweroff action specified in VM configuration.
Signature:
void hard_shutdown (session_id s, VM ref vm)
Arguments:
type
VM ref
name
vm
description
The VM to destroy
Return Type: void
Possible Error Codes: VM BAD POWER STATE
RPC name: hard reboot
Overview: Stop executing the specified VM without attempting a clean shutdown. Then perform
reboot action specified in VM configuration.
Signature:
void hard_reboot (session_id s, VM ref vm)
Arguments:
type
VM ref
name
vm
description
The VM to reboot
Return Type: void
RPC name: suspend
Overview: Suspend the specified VM to disk. This can only be called when the specified VM is
in the Running state.
Signature:
void suspend (session_id s, VM ref vm)
Arguments:
type
VM ref
name
vm
description
The VM to suspend
Return Type: void
37
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Possible Error Codes: VM BAD POWER STATE
RPC name: resume
Overview: Awaken the specified VM and resume it. This can only be called when the specified
VM is in the Suspended state.
Signature:
void resume (session_id s, VM ref vm, bool start_paused)
Arguments:
type
VM ref
bool
name
vm
start paused
description
The VM to resume
Resume VM in paused state if set to true.
Return Type: void
Possible Error Codes: VM BAD POWER STATE
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:
void set_VCPUs_number_live (session_id s, VM ref self, int nvcpu)
Arguments:
type
VM ref
int
name
self
nvcpu
description
The VM
The number of VCPUs
Return Type: void
RPC name: add to VCPUs params live
Overview: Add the given 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
VM ref
string
string
name
self
key
value
description
The VM
The key
The value
Return Type: void
38
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: set memory dynamic max live
Overview: Set memory dynamic max in database and on running VM.
Signature:
void set_memory_dynamic_max_live (session_id s, VM ref self, int max)
Arguments:
type
VM ref
int
name
self
max
description
The VM
The memory dynamic max value
Return Type: void
RPC name: set memory dynamic min live
Overview: Set memory dynamic min in database and on running VM.
Signature:
void set_memory_dynamic_min_live (session_id s, VM ref self, int min)
Arguments:
type
VM ref
int
name
self
min
description
The VM
The memory dynamic min value
Return Type: void
RPC name: send sysrq
Overview: Send the given key as a sysrq to this VM. The key is specified as a single character
(a String of length 1). This can only be called when the specified VM is in the Running state.
Signature:
void send_sysrq (session_id s, VM ref vm, string key)
Arguments:
type
VM ref
string
name
vm
key
description
The VM
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 specified VM
is in the Running state.
Signature:
39
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
void send_trigger (session_id s, VM ref vm, string trigger)
Arguments:
type
VM ref
string
name
vm
trigger
description
The VM
The trigger to send
Return Type: void
Possible Error Codes: VM BAD POWER STATE
RPC name: migrate
Overview: Migrate the VM to another host. This can only be called when the specified VM is
in the Running state.
Signature:
void migrate (session_id s, VM ref vm, string dest, bool live, (string -> string) Map options)
Arguments:
type
VM ref
string
bool
(string → string) Map
name
vm
dest
live
options
description
The VM
The destination host
Live migration
Other parameters
Return Type: void
Possible Error Codes: VM BAD POWER STATE
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)
Return Type: (VM ref) Set
A list of all the IDs of all the VMs
RPC name: get uuid
Overview: Get the uuid field of the given VM.
Signature:
string get_uuid (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
40
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Return Type: string
value of the field
RPC name: get power state
Overview: Get the power state field of the given VM.
Signature:
(vm_power_state) get_power_state (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: vm power state
value of the field
RPC name: get name label
Overview: Get the name/label field of the given VM.
Signature:
string get_name_label (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set name label
Overview: Set the name/label field of the given VM.
Signature:
void set_name_label (session_id s, VM ref self, string value)
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
41
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: get name description
Overview: Get the name/description field of the given VM.
Signature:
string get_name_description (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set name description
Overview: Set the name/description field of the given VM.
Signature:
void set_name_description (session_id s, VM ref self, string value)
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get user version
Overview: Get the user version field of the given VM.
Signature:
int get_user_version (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set user version
Overview: Set the user version field of the given VM.
Signature:
void set_user_version (session_id s, VM ref self, int value)
42
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get is a template
Overview: Get the is a template field of the given VM.
Signature:
bool get_is_a_template (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: bool
value of the field
RPC name: set is a template
Overview: Set the is a template field of the given VM.
Signature:
void set_is_a_template (session_id s, VM ref self, bool value)
Arguments:
type
VM ref
bool
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get auto power on
Overview: Get the auto power on field of the given VM.
Signature:
bool get_auto_power_on (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: bool
value of the field
43
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: set auto power on
Overview: Set the auto power on field of the given VM.
Signature:
void set_auto_power_on (session_id s, VM ref self, bool value)
Arguments:
type
VM ref
bool
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get suspend VDI
Overview: Get the suspend VDI field of the given VM.
Signature:
(VDI ref) get_suspend_VDI (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: VDI ref
value of the field
RPC name: get resident on
Overview: Get the resident on field of the given VM.
Signature:
(host ref) get_resident_on (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: host ref
value of the field
RPC name: get memory static max
Overview: Get the memory/static max field of the given VM.
Signature:
int get_memory_static_max (session_id s, VM ref self)
44
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set memory static max
Overview: Set the memory/static max field of the given VM.
Signature:
void set_memory_static_max (session_id s, VM ref self, int value)
Arguments:
type
VM ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get memory dynamic max
Overview: Get the memory/dynamic max field of the given VM.
Signature:
int get_memory_dynamic_max (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set memory dynamic max
Overview: Set the memory/dynamic max field of the given VM.
Signature:
void set_memory_dynamic_max (session_id s, VM ref self, int value)
Arguments:
type
VM ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
45
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: get memory dynamic min
Overview: Get the memory/dynamic min field of the given VM.
Signature:
int get_memory_dynamic_min (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set memory dynamic min
Overview: Set the memory/dynamic min field of the given VM.
Signature:
void set_memory_dynamic_min (session_id s, VM ref self, int value)
Arguments:
type
VM ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get memory static min
Overview: Get the memory/static min field of the given VM.
Signature:
int get_memory_static_min (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set memory static min
Overview: Set the memory/static min field of the given VM.
Signature:
void set_memory_static_min (session_id s, VM ref self, int value)
46
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get VCPUs params
Overview: Get the VCPUs/params field of the given VM.
Signature:
((string -> string) Map) get_VCPUs_params (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set VCPUs params
Overview: Set the VCPUs/params field of the given VM.
Signature:
void set_VCPUs_params (session_id s, VM ref self, (string -> string) Map value)
Arguments:
type
VM ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to VCPUs params
Overview: Add the given key-value pair to the VCPUs/params field of the given VM.
Signature:
void add_to_VCPUs_params (session_id s, VM ref self, string key, string value)
Arguments:
type
VM ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
47
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: remove from VCPUs params
Overview: Remove the given key and its corresponding value from the VCPUs/params field 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
VM ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: get VCPUs max
Overview: Get the VCPUs/max field of the given VM.
Signature:
int get_VCPUs_max (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set VCPUs max
Overview: Set the VCPUs/max field of the given VM.
Signature:
void set_VCPUs_max (session_id s, VM ref self, int value)
Arguments:
type
VM ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get VCPUs at startup
Overview: Get the VCPUs/at startup field of the given VM.
Signature:
int get_VCPUs_at_startup (session_id s, VM ref self)
48
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set VCPUs at startup
Overview: Set the VCPUs/at startup field of the given VM.
Signature:
void set_VCPUs_at_startup (session_id s, VM ref self, int value)
Arguments:
type
VM ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get actions after shutdown
Overview: Get the actions/after shutdown field of the given VM.
Signature:
(on_normal_exit) get_actions_after_shutdown (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: on normal exit
value of the field
RPC name: set actions after shutdown
Overview: Set the actions/after shutdown field of the given VM.
Signature:
void set_actions_after_shutdown (session_id s, VM ref self, on_normal_exit value)
Arguments:
type
VM ref
on normal exit
name
self
value
description
reference to the object
New value to set
Return Type: void
49
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: get actions after reboot
Overview: Get the actions/after reboot field of the given VM.
Signature:
(on_normal_exit) get_actions_after_reboot (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: on normal exit
value of the field
RPC name: set actions after reboot
Overview: Set the actions/after reboot field of the given VM.
Signature:
void set_actions_after_reboot (session_id s, VM ref self, on_normal_exit value)
Arguments:
type
VM ref
on normal exit
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get actions after crash
Overview: Get the actions/after crash field of the given VM.
Signature:
(on_crash_behaviour) get_actions_after_crash (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: on crash behaviour
value of the field
RPC name: set actions after crash
Overview: Set the actions/after crash field of the given VM.
Signature:
void set_actions_after_crash (session_id s, VM ref self, on_crash_behaviour value)
50
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
on crash behaviour
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get consoles
Overview: Get the consoles field of the given VM.
Signature:
((console ref) Set) get_consoles (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (console ref) Set
value of the field
RPC name: get VIFs
Overview: Get the VIFs field of the given VM.
Signature:
((VIF ref) Set) get_VIFs (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (VIF ref) Set
value of the field
RPC name: get VBDs
Overview: Get the VBDs field of the given VM.
Signature:
((VBD ref) Set) get_VBDs (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (VBD ref) Set
value of the field
51
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: get crash dumps
Overview: Get the crash dumps field of the given VM.
Signature:
((crashdump ref) Set) get_crash_dumps (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (crashdump ref) Set
value of the field
RPC name: get VTPMs
Overview: Get the VTPMs field of the given VM.
Signature:
((VTPM ref) Set) get_VTPMs (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (VTPM ref) Set
value of the field
RPC name: get DPCIs
Overview: Get the DPCIs field of the given VM.
Signature:
((DPCI ref) Set) get_DPCIs (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (DPCI ref) Set
value of the field
RPC name: get PV bootloader
Overview: Get the PV/bootloader field of the given VM.
Signature:
string get_PV_bootloader (session_id s, VM ref self)
52
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set PV bootloader
Overview: Set the PV/bootloader field of the given VM.
Signature:
void set_PV_bootloader (session_id s, VM ref self, string value)
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get PV kernel
Overview: Get the PV/kernel field of the given VM.
Signature:
string get_PV_kernel (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set PV kernel
Overview: Set the PV/kernel field of the given VM.
Signature:
void set_PV_kernel (session_id s, VM ref self, string value)
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
53
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: get PV ramdisk
Overview: Get the PV/ramdisk field of the given VM.
Signature:
string get_PV_ramdisk (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set PV ramdisk
Overview: Set the PV/ramdisk field of the given VM.
Signature:
void set_PV_ramdisk (session_id s, VM ref self, string value)
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get PV args
Overview: Get the PV/args field of the given VM.
Signature:
string get_PV_args (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set PV args
Overview: Set the PV/args field of the given VM.
Signature:
void set_PV_args (session_id s, VM ref self, string value)
54
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get PV bootloader args
Overview: Get the PV/bootloader args field of the given VM.
Signature:
string get_PV_bootloader_args (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set PV bootloader args
Overview: Set the PV/bootloader args field of the given VM.
Signature:
void set_PV_bootloader_args (session_id s, VM ref self, string value)
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get HVM boot policy
Overview: Get the HVM/boot policy field of the given VM.
Signature:
string get_HVM_boot_policy (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
55
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: set HVM boot policy
Overview: Set the HVM/boot policy field of the given VM.
Signature:
void set_HVM_boot_policy (session_id s, VM ref self, string value)
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get HVM boot params
Overview: Get the HVM/boot params field of the given VM.
Signature:
((string -> string) Map) get_HVM_boot_params (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set HVM boot params
Overview: Set the HVM/boot params field of the given VM.
Signature:
void set_HVM_boot_params (session_id s, VM ref self, (string -> string) Map value)
Arguments:
type
VM ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to HVM boot params
Overview: Add the given key-value pair to the HVM/boot params field of the given VM.
Signature:
void add_to_HVM_boot_params (session_id s, VM ref self, string key, string value)
56
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from HVM boot params
Overview: Remove the given key and its corresponding value from the HVM/boot params field
of 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
VM ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: get platform
Overview: Get the platform field of the given VM.
Signature:
((string -> string) Map) get_platform (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set platform
Overview: Set the platform field of the given VM.
Signature:
void set_platform (session_id s, VM ref self, (string -> string) Map value)
Arguments:
type
VM ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
57
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Return Type: void
RPC name: add to platform
Overview: Add the given key-value pair to the platform field of the given VM.
Signature:
void add_to_platform (session_id s, VM ref self, string key, string value)
Arguments:
type
VM ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from platform
Overview: Remove the given key and its corresponding value from the platform field 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
VM ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: get PCI bus
Overview: Get the PCI bus field of the given VM.
Signature:
string get_PCI_bus (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
58
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: set PCI bus
Overview: Set the PCI bus field of the given VM.
Signature:
void set_PCI_bus (session_id s, VM ref self, string value)
Arguments:
type
VM ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get other config
Overview: Get the other config field of the given VM.
Signature:
((string -> string) Map) get_other_config (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set other config
Overview: Set the other config field of the given VM.
Signature:
void set_other_config (session_id s, VM ref self, (string -> string) Map value)
Arguments:
type
VM ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to other config
Overview: Add the given key-value pair to the other config field of the given VM.
Signature:
void add_to_other_config (session_id s, VM ref self, string key, string value)
59
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
Arguments:
type
VM ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from other config
Overview: Remove the given key and its corresponding value from the other config field of the
given VM. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session_id s, VM ref self, string key)
Arguments:
type
VM ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: get domid
Overview: Get the domid field of the given VM.
Signature:
int get_domid (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get is control domain
Overview: Get the is control domain field of the given VM.
Signature:
bool get_is_control_domain (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: bool
60
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
value of the field
RPC name: get metrics
Overview: Get the metrics field of the given VM.
Signature:
(VM_metrics ref) get_metrics (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: VM metrics ref
value of the field
RPC name: get guest metrics
Overview: Get the guest metrics field of the given VM.
Signature:
(VM_guest_metrics ref) get_guest_metrics (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: VM guest metrics ref
value of the field
RPC name: get security label
Overview: Get the security label field of the given VM. Refer to the XSPolicy class for the format
of the security label.
Signature:
string get_security_label (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: string
value of the field
61
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: set security label
Overview: Set the security label field of the given VM. Refer to the XSPolicy class for the format
of the security label.
Signature:
int set_security_label (session_id s, VM ref self, string
security_label, string old_label)
Arguments:
type
VM ref
string
string
name
self
security label
old label
description
reference to the object
security label for the VM
Label value that the security label
must currently have for the change to succeed.
Return Type: int
Returns the ssidref in case of an VM that is currently running or paused, zero in case of a dormant
VM (halted, suspended).
Possible Error Codes: SECURITY ERROR
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
VM record
name
args
description
All constructor arguments
Return Type: VM ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified 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
VM ref
name
self
description
reference to the object
Return Type: void
62
2.8. CLASS: VM
CHAPTER 2. API REFERENCE
RPC name: get by uuid
Overview: Get a reference to the VM instance with the specified UUID.
Signature:
(VM ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VM ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given VM.
Signature:
(VM record) get_record (session_id s, VM ref self)
Arguments:
type
VM ref
name
self
description
reference to the object
Return Type: VM record
all fields from the object
RPC name: get by name label
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
string
name
label
description
label of object to return
Return Type: (VM ref) Set
references to objects with match names
63
2.9. CLASS: VM METRICS
2.9
2.9.1
CHAPTER 2. API REFERENCE
Class: VM metrics
Fields for class: VM metrics
Name
Description
Quals
RO run
RO run
RO run
RO run
VM metrics
The metrics associated with a VM.
Field
Type
uuid
string
memory/actual
int
VCPUs/number
int
VCPUs/utilisation (int → float) Map
RO run
RO run
VCPUs/CPU
VCPUs/params
(int → int) Map
(string → string) Map
RO run
RO run
VCPUs/flags
state
(int → string Set) Map
string Set
RO run
start time
datetime
RO run
last updated
datetime
2.9.2
Description
unique identifier/object reference
Guest’s actual memory (bytes)
Current number of VCPUs
Utilisation for all of guest’s current
VCPUs
VCPU to PCPU map
The
live
equivalent
to
VM.VCPUs params
CPU flags (blocked,online,running)
The state of the guest, eg blocked,
dying etc
Time at which this VM was last
booted
Time at which this information was
last updated
RPCs associated with class: VM metrics
RPC name: get all
Overview: Return a list of all the VM metrics instances known to the system.
Signature:
((VM_metrics ref) Set) get_all (session_id s)
Return Type: (VM metrics ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given VM metrics.
Signature:
string get_uuid (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: string
value of the field
64
2.9. CLASS: VM METRICS
CHAPTER 2. API REFERENCE
RPC name: get memory actual
Overview: Get the memory/actual field of the given VM metrics.
Signature:
int get_memory_actual (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get VCPUs number
Overview: Get the VCPUs/number field of the given VM metrics.
Signature:
int get_VCPUs_number (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get VCPUs utilisation
Overview: Get the VCPUs/utilisation field of the given VM metrics.
Signature:
((int -> float) Map) get_VCPUs_utilisation (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: (int → float) Map
value of the field
RPC name: get VCPUs CPU
Overview: Get the VCPUs/CPU field of the given VM metrics.
Signature:
((int -> int) Map) get_VCPUs_CPU (session_id s, VM_metrics ref self)
65
2.9. CLASS: VM METRICS
CHAPTER 2. API REFERENCE
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: (int → int) Map
value of the field
RPC name: get VCPUs params
Overview: Get the VCPUs/params field of the given VM metrics.
Signature:
((string -> string) Map) get_VCPUs_params (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get VCPUs flags
Overview: Get the VCPUs/flags field of the given VM metrics.
Signature:
((int -> string Set) Map) get_VCPUs_flags (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: (int → string Set) Map
value of the field
RPC name: get state
Overview: Get the state field of the given VM metrics.
Signature:
(string Set) get_state (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: string Set
value of the field
66
2.9. CLASS: VM METRICS
CHAPTER 2. API REFERENCE
RPC name: get start time
Overview: Get the start time field of the given VM metrics.
Signature:
datetime get_start_time (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: datetime
value of the field
RPC name: get last updated
Overview: Get the last updated field of the given VM metrics.
Signature:
datetime get_last_updated (session_id s, VM_metrics ref self)
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: datetime
value of the field
RPC name: get by uuid
Overview: Get a reference to the VM metrics instance with the specified UUID.
Signature:
(VM_metrics ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VM metrics ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given VM metrics.
Signature:
(VM_metrics record) get_record (session_id s, VM_metrics ref self)
67
2.9. CLASS: VM METRICS
CHAPTER 2. API REFERENCE
Arguments:
type
VM metrics ref
name
self
description
reference to the object
Return Type: VM metrics record
all fields from the object
68
2.10. CLASS: VM GUEST METRICS
CHAPTER 2. API REFERENCE
2.10
Class: VM guest metrics
2.10.1
Fields for class: VM guest metrics
Name
Description
Quals
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
2.10.2
VM guest metrics
The metrics reported by the guest
Field
Type
uuid
string
os version
(string →
PV drivers version (string →
memory
(string →
disks
(string →
networks
(string →
other
(string →
last updated
datetime
(as opposed to inferred from outside).
Description
unique identifier/object reference
string) Map version of the OS
string) Map version of the PV drivers
string) Map free/used/total memory
string) Map disk configuration/free space
string) Map network configuration
string) Map anything else
Time at which this information was
last updated
RPCs associated with class: VM guest metrics
RPC name: get all
Overview: Return a list of all the VM guest metrics instances known to the system.
Signature:
((VM_guest_metrics ref) Set) get_all (session_id s)
Return Type: (VM guest metrics ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given VM guest metrics.
Signature:
string get_uuid (session_id s, VM_guest_metrics ref self)
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get os version
Overview: Get the os version field of the given VM guest metrics.
Signature:
((string -> string) Map) get_os_version (session_id s, VM_guest_metrics ref self)
69
2.10. CLASS: VM GUEST METRICS
CHAPTER 2. API REFERENCE
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get PV drivers version
Overview: Get the PV drivers version field of the given VM guest metrics.
Signature:
((string -> string) Map) get_PV_drivers_version (session_id s, VM_guest_metrics ref self)
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get memory
Overview: Get the memory field of the given VM guest metrics.
Signature:
((string -> string) Map) get_memory (session_id s, VM_guest_metrics ref self)
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get disks
Overview: Get the disks field of the given VM guest metrics.
Signature:
((string -> string) Map) get_disks (session_id s, VM_guest_metrics ref self)
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
70
2.10. CLASS: VM GUEST METRICS
CHAPTER 2. API REFERENCE
RPC name: get networks
Overview: Get the networks field of the given VM guest metrics.
Signature:
((string -> string) Map) get_networks (session_id s, VM_guest_metrics ref self)
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get other
Overview: Get the other field of the given VM guest metrics.
Signature:
((string -> string) Map) get_other (session_id s, VM_guest_metrics ref self)
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get last updated
Overview: Get the last updated field of the given VM guest metrics.
Signature:
datetime get_last_updated (session_id s, VM_guest_metrics ref self)
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: datetime
value of the field
RPC name: get by uuid
Overview: Get a reference to the VM guest metrics instance with the specified UUID.
Signature:
(VM_guest_metrics ref) get_by_uuid (session_id s, string uuid)
71
2.10. CLASS: VM GUEST METRICS
CHAPTER 2. API REFERENCE
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VM guest metrics ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given VM guest metrics.
Signature:
(VM_guest_metrics record) get_record (session_id s, VM_guest_metrics ref self)
Arguments:
type
VM guest metrics ref
name
self
description
reference to the object
Return Type: VM guest metrics record
all fields from the object
72
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
2.11
Class: host
2.11.1
Fields for class: host
Name
Description
Quals
RO run
RW
RW
host
A physical host.
Field
uuid
name/label
name/description
Type
string
string
string
RO run
RO run
RO run
RO run
RO run
RO run
RW
RO run
RO run
API version/major
API version/minor
API version/vendor
API version/vendor implementation
enabled
software version
other config
capabilities
cpu configuration
int
int
string
(string →
bool
(string →
(string →
string Set
(string →
RO run
sched policy
string
RO run
supported bootloaders
string Set
RO run
RW
RO run
RW
resident VMs
logging
PIFs
suspend image sr
(VM ref) Set
(string → string) Map
(PIF ref) Set
SR ref
RW
crash dump sr
SR ref
RO run
RO run
RO run
RO run
PBDs
PPCIs
host CPUs
metrics
(PBD ref) Set
(PPCI ref) Set
(host cpu ref) Set
host metrics ref
2.11.2
string) Map
string) Map
string) Map
string) Map
Description
unique identifier/object reference
a human-readable name
a notes field containg humanreadable description
major version number
minor version number
identification of vendor
details of vendor implementation
True if the host is currently enabled
version strings
additional configuration
Xen capabilities
The
CPU
configuration
on
this host.
May contain keys
such
as
“nr nodes”,
“sockets per node”, “cores per socket”, or
“threads per core”
Scheduler policy currently in force on
this host
a list of the bootloaders installed on
the machine
list of VMs currently resident on host
logging configuration
physical network interfaces
The SR in which VDIs for suspend
images are created
The SR in which VDIs for crash
dumps are created
physical blockdevices
physical PCI devices
The physical CPUs on this host
metrics associated with this host
RPCs associated with class: host
RPC name: disable
Overview: Puts the host into a state in which no new VMs can be started. Currently active
VMs on the host continue to execute.
Signature:
void disable (session_id s, host ref host)
Arguments:
type
host ref
name
host
description
The Host to disable
Return Type: void
73
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
RPC name: enable
Overview: Puts the host into a state in which new VMs can be started.
Signature:
void enable (session_id s, host ref host)
Arguments:
type
host ref
name
host
description
The Host to enable
Return Type: void
RPC name: shutdown
Overview: Shutdown the host. (This function can only be called if there are no currently running
VMs on the host and it is disabled.).
Signature:
void shutdown (session_id s, host ref host)
Arguments:
type
host ref
name
host
description
The Host to shutdown
Return Type: void
RPC name: reboot
Overview: Reboot the host. (This function can only be called if there are no currently running
VMs on the host and it is disabled.).
Signature:
void reboot (session_id s, host ref host)
Arguments:
type
host ref
name
host
description
The Host to reboot
Return Type: void
RPC name: dmesg
Overview: Get the host xen dmesg.
Signature:
string dmesg (session_id s, host ref host)
74
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
Arguments:
type
host ref
name
host
description
The Host to query
Return Type: string
dmesg string
RPC name: dmesg clear
Overview: Get the host xen dmesg, and clear the buffer.
Signature:
string dmesg_clear (session_id s, host ref host)
Arguments:
type
host ref
name
host
description
The Host to query
Return Type: string
dmesg string
RPC name: get log
Overview: Get the host’s log file.
Signature:
string get_log (session_id s, host ref host)
Arguments:
type
host ref
name
host
description
The Host to query
Return Type: string
The contents of the host’s primary log file
RPC name: send debug keys
Overview: Inject the given string as debugging keys into Xen.
Signature:
void send_debug_keys (session_id s, host ref host, string keys)
Arguments:
type
host ref
string
name
host
keys
description
The host
The keys to send
Return Type: void
75
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
RPC name: list methods
Overview: List all supported methods.
Signature:
(string Set) list_methods (session_id s)
Return Type: string Set
The name of every supported method.
RPC name: get all
Overview: Return a list of all the hosts known to the system.
Signature:
((host ref) Set) get_all (session_id s)
Return Type: (host ref) Set
A list of all the IDs of all the hosts
RPC name: get uuid
Overview: Get the uuid field of the given host.
Signature:
string get_uuid (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get name label
Overview: Get the name/label field of the given host.
Signature:
string get_name_label (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: string
value of the field
76
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
RPC name: set name label
Overview: Set the name/label field of the given host.
Signature:
void set_name_label (session_id s, host ref self, string value)
Arguments:
type
host ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get name description
Overview: Get the name/description field of the given host.
Signature:
string get_name_description (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set name description
Overview: Set the name/description field of the given host.
Signature:
void set_name_description (session_id s, host ref self, string value)
Arguments:
type
host ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get API version major
Overview: Get the API version/major field of the given host.
Signature:
int get_API_version_major (session_id s, host ref self)
77
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get API version minor
Overview: Get the API version/minor field of the given host.
Signature:
int get_API_version_minor (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get API version vendor
Overview: Get the API version/vendor field of the given host.
Signature:
string get_API_version_vendor (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get API version vendor implementation
Overview: Get the API version/vendor implementation field of the given host.
Signature:
((string -> string) Map) get_API_version_vendor_implementation (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
78
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
RPC name: get enabled
Overview: Get the enabled field of the given host.
Signature:
bool get_enabled (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: bool
value of the field
RPC name: get software version
Overview: Get the software version field of the given host.
Signature:
((string -> string) Map) get_software_version (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get other config
Overview: Get the other config field of the given host.
Signature:
((string -> string) Map) get_other_config (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set other config
Overview: Set the other config field of the given host.
Signature:
void set_other_config (session_id s, host ref self, (string -> string) Map value)
79
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
Arguments:
type
host ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to other config
Overview: Add the given key-value pair to the other config field of the given host.
Signature:
void add_to_other_config (session_id s, host ref self, string key, string value)
Arguments:
type
host ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from other config
Overview: Remove the given key and its corresponding value from the other config field of the
given host. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session_id s, host ref self, string key)
Arguments:
type
host ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: get capabilities
Overview: Get the capabilities field of the given host.
Signature:
(string Set) get_capabilities (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: string Set
80
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
value of the field
RPC name: get cpu configuration
Overview: Get the cpu configuration field of the given host.
Signature:
((string -> string) Map) get_cpu_configuration (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get sched policy
Overview: Get the sched policy field of the given host.
Signature:
string get_sched_policy (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get supported bootloaders
Overview: Get the supported bootloaders field of the given host.
Signature:
(string Set) get_supported_bootloaders (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: string Set
value of the field
81
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
RPC name: get resident VMs
Overview: Get the resident VMs field of the given host.
Signature:
((VM ref) Set) get_resident_VMs (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (VM ref) Set
value of the field
RPC name: get logging
Overview: Get the logging field of the given host.
Signature:
((string -> string) Map) get_logging (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set logging
Overview: Set the logging field of the given host.
Signature:
void set_logging (session_id s, host ref self, (string -> string) Map value)
Arguments:
type
host ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to logging
Overview: Add the given key-value pair to the logging field of the given host.
Signature:
void add_to_logging (session_id s, host ref self, string key, string value)
82
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
Arguments:
type
host ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from logging
Overview: Remove the given key and its corresponding value from the logging field of the given
host. If the key is not in that Map, then do nothing.
Signature:
void remove_from_logging (session_id s, host ref self, string key)
Arguments:
type
host ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: get PIFs
Overview: Get the PIFs field of the given host.
Signature:
((PIF ref) Set) get_PIFs (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (PIF ref) Set
value of the field
RPC name: get suspend image sr
Overview: Get the suspend image sr field of the given host.
Signature:
(SR ref) get_suspend_image_sr (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: SR ref
83
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
value of the field
RPC name: set suspend image sr
Overview: Set the suspend image sr field of the given host.
Signature:
void set_suspend_image_sr (session_id s, host ref self, SR ref value)
Arguments:
type
host ref
SR ref
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get crash dump sr
Overview: Get the crash dump sr field of the given host.
Signature:
(SR ref) get_crash_dump_sr (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: SR ref
value of the field
RPC name: set crash dump sr
Overview: Set the crash dump sr field of the given host.
Signature:
void set_crash_dump_sr (session_id s, host ref self, SR ref value)
Arguments:
type
host ref
SR ref
name
self
value
description
reference to the object
New value to set
Return Type: void
84
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
RPC name: get PBDs
Overview: Get the PBDs field of the given host.
Signature:
((PBD ref) Set) get_PBDs (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (PBD ref) Set
value of the field
RPC name: get PPCIs
Overview: Get the PPCIs field of the given host.
Signature:
((PPCI ref) Set) get_PPCIs (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (PPCI ref) Set
value of the field
RPC name: get host CPUs
Overview: Get the host CPUs field of the given host.
Signature:
((host_cpu ref) Set) get_host_CPUs (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: (host cpu ref) Set
value of the field
RPC name: get metrics
Overview: Get the metrics field of the given host.
Signature:
(host_metrics ref) get_metrics (session_id s, host ref self)
85
2.11. CLASS: HOST
CHAPTER 2. API REFERENCE
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: host metrics ref
value of the field
RPC name: get by uuid
Overview: Get a reference to the host instance with the specified UUID.
Signature:
(host ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: host ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given host.
Signature:
(host record) get_record (session_id s, host ref self)
Arguments:
type
host ref
name
self
description
reference to the object
Return Type: host record
all fields from the object
RPC name: get by name label
Overview: Get all the host instances with the given label.
Signature:
((host ref) Set) get_by_name_label (session_id s, string label)
Arguments:
type
string
name
label
description
label of object to return
Return Type: (host ref) Set
references to objects with match names
86
2.12. CLASS: HOST METRICS
CHAPTER 2. API REFERENCE
2.12
Class: host metrics
2.12.1
Fields for class: host metrics
Name
Description
Quals
RO run
RO run
RO run
RO run
2.12.2
host metrics
The metrics associated with
Field
Type
uuid
string
memory/total int
memory/free
int
last updated datetime
a host.
Description
unique identifier/object reference
Host’s total memory (bytes)
Host’s free memory (bytes)
Time at which this information was
last updated
RPCs associated with class: host metrics
RPC name: get all
Overview: Return a list of all the host metrics instances known to the system.
Signature:
((host_metrics ref) Set) get_all (session_id s)
Return Type: (host metrics ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given host metrics.
Signature:
string get_uuid (session_id s, host_metrics ref self)
Arguments:
type
host metrics ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get memory total
Overview: Get the memory/total field of the given host metrics.
Signature:
int get_memory_total (session_id s, host_metrics ref self)
Arguments:
type
host metrics ref
name
self
description
reference to the object
Return Type: int
87
2.12. CLASS: HOST METRICS
CHAPTER 2. API REFERENCE
value of the field
RPC name: get memory free
Overview: Get the memory/free field of the given host metrics.
Signature:
int get_memory_free (session_id s, host_metrics ref self)
Arguments:
type
host metrics ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get last updated
Overview: Get the last updated field of the given host metrics.
Signature:
datetime get_last_updated (session_id s, host_metrics ref self)
Arguments:
type
host metrics ref
name
self
description
reference to the object
Return Type: datetime
value of the field
RPC name: get by uuid
Overview: Get a reference to the host metrics instance with the specified UUID.
Signature:
(host_metrics ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: host metrics ref
reference to the object
88
2.12. CLASS: HOST METRICS
CHAPTER 2. API REFERENCE
RPC name: get record
Overview: Get a record containing the current state of the given host metrics.
Signature:
(host_metrics record) get_record (session_id s, host_metrics ref self)
Arguments:
type
host metrics ref
name
self
description
reference to the object
Return Type: host metrics record
all fields from the object
89
2.13. CLASS: HOST CPU
CHAPTER 2. API REFERENCE
2.13
Class: host cpu
2.13.1
Fields for class: host cpu
Name
Description
Quals
RO run
RO run
RO run
host cpu
A physical CPU
Field
Type
uuid
string
host
host ref
number
int
RO run
RO run
RO run
RO run
RO run
vendor
speed
modelname
stepping
flags
string
int
string
string
string
RO run
RO run
features
utilisation
string
float
2.13.2
Description
unique identifier/object reference
the host the CPU is in
the number of the physical CPU
within the host
the vendor of the physical CPU
the speed of the physical CPU
the model name of the physical CPU
the stepping of the physical CPU
the flags of the physical CPU (a decoded version of the features field)
the physical CPU feature bitmap
the current CPU utilisation
RPCs associated with class: host cpu
RPC name: get all
Overview: Return a list of all the host cpus known to the system.
Signature:
((host_cpu ref) Set) get_all (session_id s)
Return Type: (host cpu ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given host cpu.
Signature:
string get_uuid (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get host
Overview: Get the host field of the given host cpu.
Signature:
90
2.13. CLASS: HOST CPU
CHAPTER 2. API REFERENCE
(host ref) get_host (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: host ref
value of the field
RPC name: get number
Overview: Get the number field of the given host cpu.
Signature:
int get_number (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get vendor
Overview: Get the vendor field of the given host cpu.
Signature:
string get_vendor (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get speed
Overview: Get the speed field of the given host cpu.
Signature:
int get_speed (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: int
91
2.13. CLASS: HOST CPU
CHAPTER 2. API REFERENCE
value of the field
RPC name: get modelname
Overview: Get the modelname field of the given host cpu.
Signature:
string get_modelname (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get stepping
Overview: Get the stepping field of the given host cpu.
Signature:
string get_stepping (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get flags
Overview: Get the flags field of the given host cpu. As of this version of the API, the semantics
of the returned string are explicitly unspecified, and may change in the future.
Signature:
string get_flags (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: string
value of the field
92
2.13. CLASS: HOST CPU
CHAPTER 2. API REFERENCE
RPC name: get features
Overview: Get the features field of the given host cpu. As of this version of the API, the
semantics of the returned string are explicitly unspecified, and may change in the future.
Signature:
string get_features (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get utilisation
Overview: Get the utilisation field of the given host cpu.
Signature:
float get_utilisation (session_id s, host_cpu ref self)
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: float
value of the field
RPC name: get by uuid
Overview: Get a reference to the host cpu instance with the specified UUID.
Signature:
(host_cpu ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: host cpu ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given host cpu.
Signature:
(host_cpu record) get_record (session_id s, host_cpu ref self)
93
2.13. CLASS: HOST CPU
CHAPTER 2. API REFERENCE
Arguments:
type
host cpu ref
name
self
description
reference to the object
Return Type: host cpu record
all fields from the object
94
2.14. CLASS: NETWORK
CHAPTER 2. API REFERENCE
2.14
Class: network
2.14.1
Fields for class: network
Name
Description
Quals
RO run
RW
RW
network
A virtual network.
Field
uuid
name/label
name/description
Type
string
string
string
RO run
RO run
RW
RW
RW
VIFs
PIFs
default gateway
default netmask
other config
(VIF ref) Set
(PIF ref) Set
string
string
(string → string) Map
2.14.2
Description
unique identifier/object reference
a human-readable name
a notes field containg humanreadable description
list of connected vifs
list of connected pifs
default gateway
default netmask
additional configuration
RPCs associated with class: network
RPC name: get all
Overview: Return a list of all the networks known to the system
Signature:
((network ref) Set) get_all (session_id s)
Return Type: (network ref) Set
A list of all the IDs of all the networks
RPC name: get uuid
Overview: Get the uuid field of the given network.
Signature:
string get_uuid (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get name label
Overview: Get the name/label field of the given network.
Signature:
string get_name_label (session_id s, network ref self)
95
2.14. CLASS: NETWORK
CHAPTER 2. API REFERENCE
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set name label
Overview: Set the name/label field of the given network.
Signature:
void set_name_label (session_id s, network ref self, string value)
Arguments:
type
network ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get name description
Overview: Get the name/description field of the given network.
Signature:
string get_name_description (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set name description
Overview: Set the name/description field of the given network.
Signature:
void set_name_description (session_id s, network ref self, string value)
Arguments:
type
network ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
96
2.14. CLASS: NETWORK
CHAPTER 2. API REFERENCE
RPC name: get VIFs
Overview: Get the VIFs field of the given network.
Signature:
((VIF ref) Set) get_VIFs (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: (VIF ref) Set
value of the field
RPC name: get PIFs
Overview: Get the PIFs field of the given network.
Signature:
((PIF ref) Set) get_PIFs (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: (PIF ref) Set
value of the field
RPC name: get default gateway
Overview: Get the default gateway field of the given network.
Signature:
string get_default_gateway (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set default gateway
Overview: Set the default gateway field of the given network.
Signature:
void set_default_gateway (session_id s, network ref self, string value)
97
2.14. CLASS: NETWORK
CHAPTER 2. API REFERENCE
Arguments:
type
network ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get default netmask
Overview: Get the default netmask field of the given network.
Signature:
string get_default_netmask (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set default netmask
Overview: Set the default netmask field of the given network.
Signature:
void set_default_netmask (session_id s, network ref self, string value)
Arguments:
type
network ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get other config
Overview: Get the other config field of the given network.
Signature:
((string -> string) Map) get_other_config (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
98
2.14. CLASS: NETWORK
CHAPTER 2. API REFERENCE
RPC name: set other config
Overview: Set the other config field of the given network.
Signature:
void set_other_config (session_id s, network ref self, (string -> string) Map value)
Arguments:
type
network ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to other config
Overview: Add the given key-value pair to the other config field of the given network.
Signature:
void add_to_other_config (session_id s, network ref self, string key, string value)
Arguments:
type
network ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from other config
Overview: Remove the given key and its corresponding value from the other config field of the
given network. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session_id s, network ref self, string key)
Arguments:
type
network ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: create
Overview: Create a new network instance, and return its handle.
Signature:
(network ref) create (session_id s, network record args)
99
2.14. CLASS: NETWORK
CHAPTER 2. API REFERENCE
Arguments:
type
network record
name
args
description
All constructor arguments
Return Type: network ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified network instance.
Signature:
void destroy (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: void
RPC name: get by uuid
Overview: Get a reference to the network instance with the specified UUID.
Signature:
(network ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: network ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given network.
Signature:
(network record) get_record (session_id s, network ref self)
Arguments:
type
network ref
name
self
description
reference to the object
Return Type: network record
all fields from the object
100
2.14. CLASS: NETWORK
CHAPTER 2. API REFERENCE
RPC name: get by name label
Overview: Get all the network instances with the given label.
Signature:
((network ref) Set) get_by_name_label (session_id s, string label)
Arguments:
type
string
name
label
description
label of object to return
Return Type: (network ref) Set
references to objects with match names
101
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
2.15
Class: VIF
2.15.1
Fields for class: VIF
Name
Description
Quals
RO run
RW
VIF
A virtual network interface.
Field
uuid
device
Type
string
string
RO ins
network
network ref
RO ins
VM
VM ref
RW
MAC
string
RW
RO run
MTU
currently attached
int
bool
RO run
status code
int
RO run
status detail
string
RO run
RW
RW
RO run
runtime properties
qos/algorithm type
qos/algorithm params
qos/supported algorithms
(string → string) Map
string
(string → string) Map
string Set
RO run
metrics
VIF metrics ref
2.15.2
Description
unique identifier/object reference
name of network device as exposed to
guest e.g. eth0
virtual network to which this vif is
connected
virtual machine to which this vif is
connected
ethernet MAC address of virtual interface, as exposed to guest
MTU in octets
is the device currently attached
(erased on reboot)
error/success code associated with
last attach-operation (erased on reboot)
error/success information associated
with last attach-operation status
(erased on reboot)
Device runtime properties
QoS algorithm to use
parameters for chosen QoS algorithm
supported QoS algorithms for this
VIF
metrics associated with this VIF
RPCs associated with class: VIF
RPC name: plug
Overview: Hotplug the specified VIF, dynamically attaching it to the running VM.
Signature:
void plug (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
The VIF to hotplug
Return Type: void
RPC name: unplug
Overview: Hot-unplug the specified VIF, dynamically unattaching it from the running VM.
Signature:
void unplug (session_id s, VIF ref self)
102
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
Arguments:
type
VIF ref
name
self
description
The VIF to hot-unplug
Return Type: void
RPC name: get all
Overview: Return a list of all the VIFs known to the system.
Signature:
((VIF ref) Set) get_all (session_id s)
Return Type: (VIF ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given VIF.
Signature:
string get_uuid (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get device
Overview: Get the device field of the given VIF.
Signature:
string get_device (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: string
value of the field
103
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
RPC name: set device
Overview: Set the device field of the given VIF.
Signature:
void set_device (session_id s, VIF ref self, string value)
Arguments:
type
VIF ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get network
Overview: Get the network field of the given VIF.
Signature:
(network ref) get_network (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: network ref
value of the field
RPC name: get VM
Overview: Get the VM field of the given VIF.
Signature:
(VM ref) get_VM (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: VM ref
value of the field
RPC name: get MAC
Overview: Get the MAC field of the given VIF.
Signature:
string get_MAC (session_id s, VIF ref self)
104
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set MAC
Overview: Set the MAC field of the given VIF.
Signature:
void set_MAC (session_id s, VIF ref self, string value)
Arguments:
type
VIF ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get MTU
Overview: Get the MTU field of the given VIF.
Signature:
int get_MTU (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set MTU
Overview: Set the MTU field of the given VIF.
Signature:
void set_MTU (session_id s, VIF ref self, int value)
Arguments:
type
VIF ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
105
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
RPC name: get currently attached
Overview: Get the currently attached field of the given VIF.
Signature:
bool get_currently_attached (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: bool
value of the field
RPC name: get status code
Overview: Get the status code field of the given VIF.
Signature:
int get_status_code (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get status detail
Overview: Get the status detail field of the given VIF.
Signature:
string get_status_detail (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get runtime properties
Overview: Get the runtime properties field of the given VIF.
Signature:
((string -> string) Map) get_runtime_properties (session_id s, VIF ref self)
106
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get qos algorithm type
Overview: Get the qos/algorithm type field of the given VIF.
Signature:
string get_qos_algorithm_type (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set qos algorithm type
Overview: Set the qos/algorithm type field of the given VIF.
Signature:
void set_qos_algorithm_type (session_id s, VIF ref self, string value)
Arguments:
type
VIF ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get qos algorithm params
Overview: Get the qos/algorithm params field of the given VIF.
Signature:
((string -> string) Map) get_qos_algorithm_params (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
107
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
RPC name: set qos algorithm params
Overview: Set the qos/algorithm params field of the given VIF.
Signature:
void set_qos_algorithm_params (session_id s, VIF ref self, (string -> string) Map value)
Arguments:
type
VIF ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to qos algorithm params
Overview: Add the given key-value pair to the qos/algorithm params field of the given VIF.
Signature:
void add_to_qos_algorithm_params (session_id s, VIF ref self, string key, string value)
Arguments:
type
VIF ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from qos algorithm params
Overview: Remove the given key and its corresponding value from the qos/algorithm params
field of the given VIF. If the key is not in that Map, then do nothing.
Signature:
void remove_from_qos_algorithm_params (session_id s, VIF ref self, string key)
Arguments:
type
VIF ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: get qos supported algorithms
Overview: Get the qos/supported algorithms field of the given VIF.
Signature:
(string Set) get_qos_supported_algorithms (session_id s, VIF ref self)
108
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: string Set
value of the field
RPC name: get metrics
Overview: Get the metrics field of the given VIF.
Signature:
(VIF_metrics ref) get_metrics (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: VIF metrics ref
value of the field
RPC name: set security label
Overview: Set the security label of the given VIF. Refer to the XSPolicy class for the format of
the security label.
Signature:
void set_security_label (session_id s, VIF ref self, string
security_label, string old_label)
Arguments:
type
VIF ref
string
string
name
self
security label
old label
description
reference to the object
New value of the security label
Label value that the security label
must currently have for the change to succeed.
Return Type: void
Possible Error Codes: SECURITY ERROR
RPC name: get security label
Overview: Get the security label of the given VIF.
Signature:
string get_security_label (session_id s, VIF ref self)
109
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: string
value of the given field
RPC name: create
Overview: Create a new VIF instance, and return its handle.
Signature:
(VIF ref) create (session_id s, VIF record args)
Arguments:
type
VIF record
name
args
description
All constructor arguments
Return Type: VIF ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified VIF instance.
Signature:
void destroy (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: void
RPC name: get by uuid
Overview: Get a reference to the VIF instance with the specified UUID.
Signature:
(VIF ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VIF ref
reference to the object
110
2.15. CLASS: VIF
CHAPTER 2. API REFERENCE
RPC name: get record
Overview: Get a record containing the current state of the given VIF.
Signature:
(VIF record) get_record (session_id s, VIF ref self)
Arguments:
type
VIF ref
name
self
description
reference to the object
Return Type: VIF record
all fields from the object
111
2.16. CLASS: VIF METRICS
CHAPTER 2. API REFERENCE
2.16
Class: VIF metrics
2.16.1
Fields for class: VIF metrics
Name
Description
Quals
RO run
RO run
RO run
RO run
2.16.2
VIF metrics
The metrics associated with a virtual network device.
Field
Type
Description
uuid
string
unique identifier/object reference
io/read kbs
float
Read bandwidth (KiB/s)
io/write kbs float
Write bandwidth (KiB/s)
last updated datetime Time at which this information was
last updated
RPCs associated with class: VIF metrics
RPC name: get all
Overview: Return a list of all the VIF metrics instances known to the system.
Signature:
((VIF_metrics ref) Set) get_all (session_id s)
Return Type: (VIF metrics ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given VIF metrics.
Signature:
string get_uuid (session_id s, VIF_metrics ref self)
Arguments:
type
VIF metrics ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get io read kbs
Overview: Get the io/read kbs field of the given VIF metrics.
Signature:
float get_io_read_kbs (session_id s, VIF_metrics ref self)
Arguments:
type
VIF metrics ref
name
self
description
reference to the object
Return Type: float
112
2.16. CLASS: VIF METRICS
CHAPTER 2. API REFERENCE
value of the field
RPC name: get io write kbs
Overview: Get the io/write kbs field of the given VIF metrics.
Signature:
float get_io_write_kbs (session_id s, VIF_metrics ref self)
Arguments:
type
VIF metrics ref
name
self
description
reference to the object
Return Type: float
value of the field
RPC name: get last updated
Overview: Get the last updated field of the given VIF metrics.
Signature:
datetime get_last_updated (session_id s, VIF_metrics ref self)
Arguments:
type
VIF metrics ref
name
self
description
reference to the object
Return Type: datetime
value of the field
RPC name: get by uuid
Overview: Get a reference to the VIF metrics instance with the specified UUID.
Signature:
(VIF_metrics ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VIF metrics ref
reference to the object
113
2.16. CLASS: VIF METRICS
CHAPTER 2. API REFERENCE
RPC name: get record
Overview: Get a record containing the current state of the given VIF metrics.
Signature:
(VIF_metrics record) get_record (session_id s, VIF_metrics ref self)
Arguments:
type
VIF metrics ref
name
self
description
reference to the object
Return Type: VIF metrics record
all fields from the object
114
2.17. CLASS: PIF
CHAPTER 2. API REFERENCE
2.17
Class: PIF
2.17.1
Fields for class: PIF
Name
Description
Quals
RO run
RW
RO ins
RO ins
RW
RW
RW
RO run
2.17.2
PIF
A physical network interface (note separate VLANs are represented as
several PIFs).
Field
Type
Description
uuid
string
unique identifier/object reference
device
string
machine-readable name of the interface (e.g. eth0)
network network ref
virtual network to which this pif is
connected
host
host ref
physical machine to which this pif is
connected
MAC
string
ethernet MAC address of physical interface
MTU
int
MTU in octets
VLAN
int
VLAN tag for all traffic passing
through this interface
metrics PIF metrics ref metrics associated with this PIF
RPCs associated with class: PIF
RPC name: create VLAN
Overview: Create a VLAN interface from an existing physical interface.
Signature:
(PIF ref) create_VLAN (session_id s, string device, network ref network, host ref host, int VLAN)
Arguments:
type
string
name
device
network ref
network
host ref
host
int
VLAN
description
physical interface on which to crate the VLAN
interface
network to which this interface should be connected
physical machine to which this PIF is connected
VLAN tag for the new interface
Return Type: PIF ref
The reference of the created PIF object
Possible Error Codes: VLAN TAG INVALID
RPC name: destroy
Overview: Destroy the interface (provided it is a synthetic interface like a VLAN; fail if it is a
physical interface).
Signature:
void destroy (session_id s, PIF ref self)
115
2.17. CLASS: PIF
CHAPTER 2. API REFERENCE
Arguments:
type
PIF ref
name
self
description
the PIF object to destroy
Return Type: void
Possible Error Codes: PIF IS PHYSICAL
RPC name: get all
Overview: Return a list of all the PIFs known to the system.
Signature:
((PIF ref) Set) get_all (session_id s)
Return Type: (PIF ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given PIF.
Signature:
string get_uuid (session_id s, PIF ref self)
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get device
Overview: Get the device field of the given PIF.
Signature:
string get_device (session_id s, PIF ref self)
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: string
value of the field
116
2.17. CLASS: PIF
CHAPTER 2. API REFERENCE
RPC name: set device
Overview: Set the device field of the given PIF.
Signature:
void set_device (session_id s, PIF ref self, string value)
Arguments:
type
PIF ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get network
Overview: Get the network field of the given PIF.
Signature:
(network ref) get_network (session_id s, PIF ref self)
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: network ref
value of the field
RPC name: get host
Overview: Get the host field of the given PIF.
Signature:
(host ref) get_host (session_id s, PIF ref self)
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: host ref
value of the field
RPC name: get MAC
Overview: Get the MAC field of the given PIF.
Signature:
string get_MAC (session_id s, PIF ref self)
117
2.17. CLASS: PIF
CHAPTER 2. API REFERENCE
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set MAC
Overview: Set the MAC field of the given PIF.
Signature:
void set_MAC (session_id s, PIF ref self, string value)
Arguments:
type
PIF ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get MTU
Overview: Get the MTU field of the given PIF.
Signature:
int get_MTU (session_id s, PIF ref self)
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set MTU
Overview: Set the MTU field of the given PIF.
Signature:
void set_MTU (session_id s, PIF ref self, int value)
Arguments:
type
PIF ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
118
2.17. CLASS: PIF
CHAPTER 2. API REFERENCE
RPC name: get VLAN
Overview: Get the VLAN field of the given PIF.
Signature:
int get_VLAN (session_id s, PIF ref self)
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set VLAN
Overview: Set the VLAN field of the given PIF.
Signature:
void set_VLAN (session_id s, PIF ref self, int value)
Arguments:
type
PIF ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get metrics
Overview: Get the metrics field of the given PIF.
Signature:
(PIF_metrics ref) get_metrics (session_id s, PIF ref self)
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: PIF metrics ref
value of the field
RPC name: get by uuid
Overview: Get a reference to the PIF instance with the specified UUID.
Signature:
(PIF ref) get_by_uuid (session_id s, string uuid)
119
2.17. CLASS: PIF
CHAPTER 2. API REFERENCE
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: PIF ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given PIF.
Signature:
(PIF record) get_record (session_id s, PIF ref self)
Arguments:
type
PIF ref
name
self
description
reference to the object
Return Type: PIF record
all fields from the object
120
2.18. CLASS: PIF METRICS
CHAPTER 2. API REFERENCE
2.18
Class: PIF metrics
2.18.1
Fields for class: PIF metrics
Name
Description
Quals
RO run
RO run
RO run
RO run
2.18.2
PIF metrics
The metrics associated with a physical network interface.
Field
Type
Description
uuid
string
unique identifier/object reference
io/read kbs
float
Read bandwidth (KiB/s)
io/write kbs float
Write bandwidth (KiB/s)
last updated datetime Time at which this information was
last updated
RPCs associated with class: PIF metrics
RPC name: get all
Overview: Return a list of all the PIF metrics instances known to the system.
Signature:
((PIF_metrics ref) Set) get_all (session_id s)
Return Type: (PIF metrics ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given PIF metrics.
Signature:
string get_uuid (session_id s, PIF_metrics ref self)
Arguments:
type
PIF metrics ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get io read kbs
Overview: Get the io/read kbs field of the given PIF metrics.
Signature:
float get_io_read_kbs (session_id s, PIF_metrics ref self)
Arguments:
type
PIF metrics ref
name
self
description
reference to the object
Return Type: float
121
2.18. CLASS: PIF METRICS
CHAPTER 2. API REFERENCE
value of the field
RPC name: get io write kbs
Overview: Get the io/write kbs field of the given PIF metrics.
Signature:
float get_io_write_kbs (session_id s, PIF_metrics ref self)
Arguments:
type
PIF metrics ref
name
self
description
reference to the object
Return Type: float
value of the field
RPC name: get last updated
Overview: Get the last updated field of the given PIF metrics.
Signature:
datetime get_last_updated (session_id s, PIF_metrics ref self)
Arguments:
type
PIF metrics ref
name
self
description
reference to the object
Return Type: datetime
value of the field
RPC name: get by uuid
Overview: Get a reference to the PIF metrics instance with the specified UUID.
Signature:
(PIF_metrics ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: PIF metrics ref
reference to the object
122
2.18. CLASS: PIF METRICS
CHAPTER 2. API REFERENCE
RPC name: get record
Overview: Get a record containing the current state of the given PIF metrics.
Signature:
(PIF_metrics record) get_record (session_id s, PIF_metrics ref self)
Arguments:
type
PIF metrics ref
name
self
description
reference to the object
Return Type: PIF metrics record
all fields from the object
123
2.19. CLASS: SR
2.19
Class: SR
2.19.1
Fields for class: SR
CHAPTER 2. API REFERENCE
Name
Description
Quals
RO run
RW
RW
SR
A storage repository.
Field
uuid
name/label
name/description
Type
string
string
string
RO run
RO run
RO run
VDIs
PBDs
virtual allocation
(VDI ref) Set
(PBD ref) Set
int
RO run
physical utilisation
int
RO ins
physical size
int
RO ins
RO ins
type
content type
string
string
2.19.2
Description
unique identifier/object reference
a human-readable name
a notes field containg humanreadable description
managed virtual disks
physical blockdevices
sum of virtual sizes of all VDIs in this
storage repository (in bytes)
physical space currently utilised on
this storage repository (in bytes).
Note that for sparse disk formats,
physical utilisation may be less than
virtual allocation
total physical size of the repository
(in bytes)
type of the storage repository
the type of the SR’s content, if required (e.g. ISOs)
RPCs associated with class: SR
RPC name: get supported types
Overview: Return a set of all the SR types supported by the system.
Signature:
(string Set) get_supported_types (session_id s)
Return Type: string Set
the supported SR types
RPC name: get all
Overview: Return a list of all the SRs known to the system.
Signature:
((SR ref) Set) get_all (session_id s)
Return Type: (SR ref) Set
references to all objects
124
2.19. CLASS: SR
CHAPTER 2. API REFERENCE
RPC name: get uuid
Overview: Get the uuid field of the given SR.
Signature:
string get_uuid (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get name label
Overview: Get the name/label field of the given SR.
Signature:
string get_name_label (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set name label
Overview: Set the name/label field of the given SR.
Signature:
void set_name_label (session_id s, SR ref self, string value)
Arguments:
type
SR ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get name description
Overview: Get the name/description field of the given SR.
Signature:
string get_name_description (session_id s, SR ref self)
125
2.19. CLASS: SR
CHAPTER 2. API REFERENCE
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set name description
Overview: Set the name/description field of the given SR.
Signature:
void set_name_description (session_id s, SR ref self, string value)
Arguments:
type
SR ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get VDIs
Overview: Get the VDIs field of the given SR.
Signature:
((VDI ref) Set) get_VDIs (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: (VDI ref) Set
value of the field
RPC name: get PBDs
Overview: Get the PBDs field of the given SR.
Signature:
((PBD ref) Set) get_PBDs (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: (PBD ref) Set
value of the field
126
2.19. CLASS: SR
CHAPTER 2. API REFERENCE
RPC name: get virtual allocation
Overview: Get the virtual allocation field of the given SR.
Signature:
int get_virtual_allocation (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get physical utilisation
Overview: Get the physical utilisation field of the given SR.
Signature:
int get_physical_utilisation (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get physical size
Overview: Get the physical size field of the given SR.
Signature:
int get_physical_size (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get type
Overview: Get the type field of the given SR.
Signature:
string get_type (session_id s, SR ref self)
127
2.19. CLASS: SR
CHAPTER 2. API REFERENCE
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get content type
Overview: Get the content type field of the given SR.
Signature:
string get_content_type (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get by uuid
Overview: Get a reference to the SR instance with the specified UUID.
Signature:
(SR ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: SR ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given SR.
Signature:
(SR record) get_record (session_id s, SR ref self)
Arguments:
type
SR ref
name
self
description
reference to the object
Return Type: SR record
all fields from the object
128
2.19. CLASS: SR
CHAPTER 2. API REFERENCE
RPC name: get by name label
Overview: Get all the SR instances with the given label.
Signature:
((SR ref) Set) get_by_name_label (session_id s, string label)
Arguments:
type
string
name
label
description
label of object to return
Return Type: (SR ref) Set
references to objects with match names
129
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
2.20
Class: VDI
2.20.1
Fields for class: VDI
Name
Description
Quals
RO run
RW
RW
VDI
A virtual disk image.
Field
uuid
name/label
name/description
Type
string
string
string
RO ins
SR
SR ref
RO run
RO run
VBDs
crash dumps
(VBD ref) Set
(crashdump ref) Set
RW
virtual size
int
RO run
physical utilisation
int
RO ins
RW
RW
type
sharable
read only
vdi type
bool
bool
RW
RO run
other config
security/label
(string → string) Map
string
2.20.2
RPCs associated with class: VDI
RPC name: get all
Overview: Return a list of all the VDIs known to the system.
Signature:
((VDI ref) Set) get_all (session_id s)
Return Type: (VDI ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given VDI.
Signature:
string get_uuid (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
130
Description
unique identifier/object reference
a human-readable name
a notes field containg humanreadable description
storage repository in which the VDI
resides
list of vbds that refer to this disk
list of crash dumps that refer to this
disk
size of disk as presented to the guest
(in bytes). Note that, depending on
storage backend type, requested size
may not be respected exactly
amount of physical space that the
disk image is currently taking up on
the storage repository (in bytes)
type of the VDI
true if this disk may be shared
true if this disk may ONLY be
mounted read-only
additional configuration
the VM’s security label
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
Return Type: string
value of the field
RPC name: get name label
Overview: Get the name/label field of the given VDI.
Signature:
string get_name_label (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set name label
Overview: Set the name/label field of the given VDI.
Signature:
void set_name_label (session_id s, VDI ref self, string value)
Arguments:
type
VDI ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get name description
Overview: Get the name/description field of the given VDI.
Signature:
string get_name_description (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: string
value of the field
131
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
RPC name: set name description
Overview: Set the name/description field of the given VDI.
Signature:
void set_name_description (session_id s, VDI ref self, string value)
Arguments:
type
VDI ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get SR
Overview: Get the SR field of the given VDI.
Signature:
(SR ref) get_SR (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: SR ref
value of the field
RPC name: get VBDs
Overview: Get the VBDs field of the given VDI.
Signature:
((VBD ref) Set) get_VBDs (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: (VBD ref) Set
value of the field
RPC name: get crash dumps
Overview: Get the crash dumps field of the given VDI.
Signature:
((crashdump ref) Set) get_crash_dumps (session_id s, VDI ref self)
132
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: (crashdump ref) Set
value of the field
RPC name: get virtual size
Overview: Get the virtual size field of the given VDI.
Signature:
int get_virtual_size (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: set virtual size
Overview: Set the virtual size field of the given VDI.
Signature:
void set_virtual_size (session_id s, VDI ref self, int value)
Arguments:
type
VDI ref
int
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get physical utilisation
Overview: Get the physical utilisation field of the given VDI.
Signature:
int get_physical_utilisation (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: int
value of the field
133
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
RPC name: get type
Overview: Get the type field of the given VDI.
Signature:
(vdi_type) get_type (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: vdi type
value of the field
RPC name: get sharable
Overview: Get the sharable field of the given VDI.
Signature:
bool get_sharable (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: bool
value of the field
RPC name: set sharable
Overview: Set the sharable field of the given VDI.
Signature:
void set_sharable (session_id s, VDI ref self, bool value)
Arguments:
type
VDI ref
bool
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get read only
Overview: Get the read only field of the given VDI.
Signature:
bool get_read_only (session_id s, VDI ref self)
134
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: bool
value of the field
RPC name: set read only
Overview: Set the read only field of the given VDI.
Signature:
void set_read_only (session_id s, VDI ref self, bool value)
Arguments:
type
VDI ref
bool
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get other config
Overview: Get the other config field of the given VDI.
Signature:
((string -> string) Map) get_other_config (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set other config
Overview: Set the other config field of the given VDI.
Signature:
void set_other_config (session_id s, VDI ref self, (string -> string) Map value)
Arguments:
type
VDI ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
135
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
RPC name: add to other config
Overview: Add the given key-value pair to the other config field of the given VDI.
Signature:
void add_to_other_config (session_id s, VDI ref self, string key, string value)
Arguments:
type
VDI ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from other config
Overview: Remove the given key and its corresponding value from the other config field of the
given VDI. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session_id s, VDI ref self, string key)
Arguments:
type
VDI ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: set security label
Overview: Set the security label of the given VDI. Refer to the XSPolicy class for the format of
the security label.
Signature:
void set_security_label (session_id s, VDI ref self, string
security_label, string old_label)
Arguments:
type
VDI ref
string
string
name
self
security label
old label
description
reference to the object
New value of the security label
Label value that the security label
must currently have for the change to succeed.
Return Type: void
Possible Error Codes: SECURITY ERROR
136
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
RPC name: get security label
Overview: Get the security label of the given VDI.
Signature:
string get_security_label (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: string
value of the given field
RPC name: create
Overview: Create a new VDI instance, and return its handle.
Signature:
(VDI ref) create (session_id s, VDI record args)
Arguments:
type
VDI record
name
args
description
All constructor arguments
Return Type: VDI ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified VDI instance.
Signature:
void destroy (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: void
RPC name: get by uuid
Overview: Get a reference to the VDI instance with the specified UUID.
Signature:
(VDI ref) get_by_uuid (session_id s, string uuid)
137
2.20. CLASS: VDI
CHAPTER 2. API REFERENCE
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VDI ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given VDI.
Signature:
(VDI record) get_record (session_id s, VDI ref self)
Arguments:
type
VDI ref
name
self
description
reference to the object
Return Type: VDI record
all fields from the object
RPC name: get by name label
Overview: Get all the VDI instances with the given label.
Signature:
((VDI ref) Set) get_by_name_label (session_id s, string label)
Arguments:
type
string
name
label
description
label of object to return
Return Type: (VDI ref) Set
references to objects with match names
138
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
2.21
Class: VBD
2.21.1
Fields for class: VBD
Name
Description
Quals
RO run
RO ins
RO ins
RW
RW
RW
VBD
A virtual block device.
Field
uuid
VM
VDI
device
bootable
mode
Type
string
VM ref
VDI ref
string
bool
vbd mode
RW
type
vbd type
RO run
currently attached
bool
RO run
status code
int
RO run
status detail
string
RO run
RW
RW
RO run
runtime properties
qos/algorithm type
qos/algorithm params
qos/supported algorithms
(string → string) Map
string
(string → string) Map
string Set
RO run
metrics
VBD metrics ref
2.21.2
Description
unique identifier/object reference
the virtual machine
the virtual disk
device seen by the guest e.g. hda1
true if this VBD is bootable
the mode the VBD should be
mounted with
how the VBD will appear to the guest
(e.g. disk or CD)
is the device currently attached
(erased on reboot)
error/success code associated with
last attach-operation (erased on reboot)
error/success information associated
with last attach-operation status
(erased on reboot)
Device runtime properties
QoS algorithm to use
parameters for chosen QoS algorithm
supported QoS algorithms for this
VBD
metrics associated with this VBD
RPCs associated with class: VBD
RPC name: media change
Overview: Change the media in the device for CDROM-like devices only. For other devices,
detach the VBD and attach a new one.
Signature:
void media_change (session_id s, VBD ref vbd, VDI ref vdi)
Arguments:
type
VBD ref
VDI ref
name
vbd
vdi
description
The vbd representing the CDROM-like device
The new VDI to ’insert’
Return Type: void
RPC name: plug
Overview: Hotplug the specified VBD, dynamically attaching it to the running VM.
Signature:
139
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
void plug (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
The VBD to hotplug
Return Type: void
RPC name: unplug
Overview: Hot-unplug the specified VBD, dynamically unattaching it from the running VM.
Signature:
void unplug (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
The VBD to hot-unplug
Return Type: void
RPC name: get all
Overview: Return a list of all the VBDs known to the system.
Signature:
((VBD ref) Set) get_all (session_id s)
Return Type: (VBD ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given VBD.
Signature:
string get_uuid (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: string
value of the field
140
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
RPC name: get VM
Overview: Get the VM field of the given VBD.
Signature:
(VM ref) get_VM (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: VM ref
value of the field
RPC name: get VDI
Overview: Get the VDI field of the given VBD.
Signature:
(VDI ref) get_VDI (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: VDI ref
value of the field
RPC name: get device
Overview: Get the device field of the given VBD.
Signature:
string get_device (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set device
Overview: Set the device field of the given VBD.
Signature:
void set_device (session_id s, VBD ref self, string value)
141
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
Arguments:
type
VBD ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get bootable
Overview: Get the bootable field of the given VBD.
Signature:
bool get_bootable (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: bool
value of the field
RPC name: set bootable
Overview: Set the bootable field of the given VBD.
Signature:
void set_bootable (session_id s, VBD ref self, bool value)
Arguments:
type
VBD ref
bool
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get mode
Overview: Get the mode field of the given VBD.
Signature:
(vbd_mode) get_mode (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: vbd mode
value of the field
142
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
RPC name: set mode
Overview: Set the mode field of the given VBD.
Signature:
void set_mode (session_id s, VBD ref self, vbd_mode value)
Arguments:
type
VBD ref
vbd mode
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get type
Overview: Get the type field of the given VBD.
Signature:
(vbd_type) get_type (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: vbd type
value of the field
RPC name: set type
Overview: Set the type field of the given VBD.
Signature:
void set_type (session_id s, VBD ref self, vbd_type value)
Arguments:
type
VBD ref
vbd type
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get currently attached
Overview: Get the currently attached field of the given VBD.
Signature:
bool get_currently_attached (session_id s, VBD ref self)
143
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: bool
value of the field
RPC name: get status code
Overview: Get the status code field of the given VBD.
Signature:
int get_status_code (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get status detail
Overview: Get the status detail field of the given VBD.
Signature:
string get_status_detail (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get runtime properties
Overview: Get the runtime properties field of the given VBD.
Signature:
((string -> string) Map) get_runtime_properties (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
144
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
RPC name: get qos algorithm type
Overview: Get the qos/algorithm type field of the given VBD.
Signature:
string get_qos_algorithm_type (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: set qos algorithm type
Overview: Set the qos/algorithm type field of the given VBD.
Signature:
void set_qos_algorithm_type (session_id s, VBD ref self, string value)
Arguments:
type
VBD ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get qos algorithm params
Overview: Get the qos/algorithm params field of the given VBD.
Signature:
((string -> string) Map) get_qos_algorithm_params (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set qos algorithm params
Overview: Set the qos/algorithm params field of the given VBD.
Signature:
void set_qos_algorithm_params (session_id s, VBD ref self, (string -> string) Map value)
145
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
Arguments:
type
VBD ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to qos algorithm params
Overview: Add the given key-value pair to the qos/algorithm params field of the given VBD.
Signature:
void add_to_qos_algorithm_params (session_id s, VBD ref self, string key, string value)
Arguments:
type
VBD ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from qos algorithm params
Overview: Remove the given key and its corresponding value from the qos/algorithm params
field of the given VBD. If the key is not in that Map, then do nothing.
Signature:
void remove_from_qos_algorithm_params (session_id s, VBD ref self, string key)
Arguments:
type
VBD ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: get qos supported algorithms
Overview: Get the qos/supported algorithms field of the given VBD.
Signature:
(string Set) get_qos_supported_algorithms (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: string Set
146
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
value of the field
RPC name: get metrics
Overview: Get the metrics field of the given VBD.
Signature:
(VBD_metrics ref) get_metrics (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: VBD metrics ref
value of the field
RPC name: create
Overview: Create a new VBD instance, and return its handle.
Signature:
(VBD ref) create (session_id s, VBD record args)
Arguments:
type
VBD record
name
args
description
All constructor arguments
Return Type: VBD ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified VBD instance.
Signature:
void destroy (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: void
147
2.21. CLASS: VBD
CHAPTER 2. API REFERENCE
RPC name: get by uuid
Overview: Get a reference to the VBD instance with the specified UUID.
Signature:
(VBD ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VBD ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given VBD.
Signature:
(VBD record) get_record (session_id s, VBD ref self)
Arguments:
type
VBD ref
name
self
description
reference to the object
Return Type: VBD record
all fields from the object
148
2.22. CLASS: VBD METRICS
CHAPTER 2. API REFERENCE
2.22
Class: VBD metrics
2.22.1
Fields for class: VBD metrics
Name
Description
Quals
RO run
RO run
RO run
RO run
2.22.2
VBD metrics
The metrics associated with a virtual block device.
Field
Type
Description
uuid
string
unique identifier/object reference
io/read kbs
float
Read bandwidth (KiB/s)
io/write kbs float
Write bandwidth (KiB/s)
last updated datetime Time at which this information was
last updated
RPCs associated with class: VBD metrics
RPC name: get all
Overview: Return a list of all the VBD metrics instances known to the system.
Signature:
((VBD_metrics ref) Set) get_all (session_id s)
Return Type: (VBD metrics ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given VBD metrics.
Signature:
string get_uuid (session_id s, VBD_metrics ref self)
Arguments:
type
VBD metrics ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get io read kbs
Overview: Get the io/read kbs field of the given VBD metrics.
Signature:
float get_io_read_kbs (session_id s, VBD_metrics ref self)
Arguments:
type
VBD metrics ref
name
self
description
reference to the object
Return Type: float
149
2.22. CLASS: VBD METRICS
CHAPTER 2. API REFERENCE
value of the field
RPC name: get io write kbs
Overview: Get the io/write kbs field of the given VBD metrics.
Signature:
float get_io_write_kbs (session_id s, VBD_metrics ref self)
Arguments:
type
VBD metrics ref
name
self
description
reference to the object
Return Type: float
value of the field
RPC name: get last updated
Overview: Get the last updated field of the given VBD metrics.
Signature:
datetime get_last_updated (session_id s, VBD_metrics ref self)
Arguments:
type
VBD metrics ref
name
self
description
reference to the object
Return Type: datetime
value of the field
RPC name: get by uuid
Overview: Get a reference to the VBD metrics instance with the specified UUID.
Signature:
(VBD_metrics ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VBD metrics ref
reference to the object
150
2.22. CLASS: VBD METRICS
CHAPTER 2. API REFERENCE
RPC name: get record
Overview: Get a record containing the current state of the given VBD metrics.
Signature:
(VBD_metrics record) get_record (session_id s, VBD_metrics ref self)
Arguments:
type
VBD metrics ref
name
self
description
reference to the object
Return Type: VBD metrics record
all fields from the object
151
2.23. CLASS: PBD
CHAPTER 2. API REFERENCE
2.23
Class: PBD
2.23.1
Fields for class: PBD
Name
Description
Quals
RO run
RO ins
RO ins
RO ins
RO run
2.23.2
PBD
The physical block devices through which hosts access SRs.
Field
Type
Description
uuid
string
unique identifier/object reference
host
host ref
physical machine on which the pbd is
available
SR
SR ref
the storage repository that the pbd
realises
device config
(string → string) Map a config string to string map that is
provided to the host’s SR-backenddriver
currently attached bool
is the SR currently attached on this
host?
RPCs associated with class: PBD
RPC name: get all
Overview: Return a list of all the PBDs known to the system.
Signature:
((PBD ref) Set) get_all (session_id s)
Return Type: (PBD ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given PBD.
Signature:
string get_uuid (session_id s, PBD ref self)
Arguments:
type
PBD ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get host
Overview: Get the host field of the given PBD.
Signature:
(host ref) get_host (session_id s, PBD ref self)
152
2.23. CLASS: PBD
CHAPTER 2. API REFERENCE
Arguments:
type
PBD ref
name
self
description
reference to the object
Return Type: host ref
value of the field
RPC name: get SR
Overview: Get the SR field of the given PBD.
Signature:
(SR ref) get_SR (session_id s, PBD ref self)
Arguments:
type
PBD ref
name
self
description
reference to the object
Return Type: SR ref
value of the field
RPC name: get device config
Overview: Get the device config field of the given PBD.
Signature:
((string -> string) Map) get_device_config (session_id s, PBD ref self)
Arguments:
type
PBD ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: get currently attached
Overview: Get the currently attached field of the given PBD.
Signature:
bool get_currently_attached (session_id s, PBD ref self)
Arguments:
type
PBD ref
name
self
description
reference to the object
Return Type: bool
value of the field
153
2.23. CLASS: PBD
CHAPTER 2. API REFERENCE
RPC name: create
Overview: Create a new PBD instance, and return its handle.
Signature:
(PBD ref) create (session_id s, PBD record args)
Arguments:
type
PBD record
name
args
description
All constructor arguments
Return Type: PBD ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified PBD instance.
Signature:
void destroy (session_id s, PBD ref self)
Arguments:
type
PBD ref
name
self
description
reference to the object
Return Type: void
RPC name: get by uuid
Overview: Get a reference to the PBD instance with the specified UUID.
Signature:
(PBD ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: PBD ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given PBD.
Signature:
(PBD record) get_record (session_id s, PBD ref self)
154
2.23. CLASS: PBD
CHAPTER 2. API REFERENCE
Arguments:
type
PBD ref
name
self
description
reference to the object
Return Type: PBD record
all fields from the object
155
2.24. CLASS: CRASHDUMP
CHAPTER 2. API REFERENCE
2.24
Class: crashdump
2.24.1
Fields for class: crashdump
Name
Description
Quals
RO run
RO ins
RO ins
2.24.2
crashdump
A VM crashdump.
Field Type
Description
uuid string
unique identifier/object reference
VM
VM ref the virtual machine
VDI
VDI ref the virtual disk
RPCs associated with class: crashdump
RPC name: destroy
Overview: Destroy the specified crashdump.
Signature:
void destroy (session_id s, crashdump ref self)
Arguments:
type
crashdump ref
name
self
description
The crashdump to destroy
Return Type: void
RPC name: get all
Overview: Return a list of all the crashdumps known to the system.
Signature:
((crashdump ref) Set) get_all (session_id s)
Return Type: (crashdump ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given crashdump.
Signature:
string get_uuid (session_id s, crashdump ref self)
Arguments:
type
crashdump ref
name
self
description
reference to the object
Return Type: string
value of the field
156
2.24. CLASS: CRASHDUMP
CHAPTER 2. API REFERENCE
RPC name: get VM
Overview: Get the VM field of the given crashdump.
Signature:
(VM ref) get_VM (session_id s, crashdump ref self)
Arguments:
type
crashdump ref
name
self
description
reference to the object
Return Type: VM ref
value of the field
RPC name: get VDI
Overview: Get the VDI field of the given crashdump.
Signature:
(VDI ref) get_VDI (session_id s, crashdump ref self)
Arguments:
type
crashdump ref
name
self
description
reference to the object
Return Type: VDI ref
value of the field
RPC name: get by uuid
Overview: Get a reference to the crashdump instance with the specified UUID.
Signature:
(crashdump ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: crashdump ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given crashdump.
Signature:
(crashdump record) get_record (session_id s, crashdump ref self)
157
2.24. CLASS: CRASHDUMP
CHAPTER 2. API REFERENCE
Arguments:
type
crashdump ref
name
self
description
reference to the object
Return Type: crashdump record
all fields from the object
158
2.25. CLASS: VTPM
CHAPTER 2. API REFERENCE
2.25
Class: VTPM
2.25.1
Fields for class: VTPM
Name
Description
Quals
RO run
RO ins
RO ins
VTPM
A virtual TPM device.
Field
Type
uuid
string
VM
VM ref
backend
VM ref
RW
other config
2.25.2
(string → string) Map
Description
unique identifier/object reference
the virtual machine
the domain where the backend is located
additional configuration
RPCs associated with class: VTPM
RPC name: get uuid
Overview: Get the uuid field of the given VTPM.
Signature:
string get_uuid (session_id s, VTPM ref self)
Arguments:
type
VTPM ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get VM
Overview: Get the VM field of the given VTPM.
Signature:
(VM ref) get_VM (session_id s, VTPM ref self)
Arguments:
type
VTPM ref
name
self
description
reference to the object
Return Type: VM ref
value of the field
RPC name: get backend
Overview: Get the backend field of the given VTPM.
Signature:
(VM ref) get_backend (session_id s, VTPM ref self)
159
2.25. CLASS: VTPM
CHAPTER 2. API REFERENCE
Arguments:
type
VTPM ref
name
self
description
reference to the object
Return Type: VM ref
value of the field
RPC name: get other config
Overview: Get the other config field of the given VTPM.
Signature:
((string -> string) Map) get_other_config (session_id s, VTPM ref self)
Arguments:
type
VTPM ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
RPC name: set other config
Overview: Set the other config field of the given VTPM.
Signature:
void set_other_config (session_id s, VTPM ref self, (string -> string) Map value)
Arguments:
type
VTPM ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: get runtime properties
Overview: Get the runtime properties field of the given VTPM.
Signature:
((string -> string) Map) get_runtime_properties (session_id s, VTPM ref self)
Arguments:
type
VTPM ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
160
2.25. CLASS: VTPM
CHAPTER 2. API REFERENCE
RPC name: create
Overview: Create a new VTPM instance, and return its handle.
Signature:
(VTPM ref) create (session_id s, VTPM record args)
Arguments:
type
VTPM record
name
args
description
All constructor arguments
Return Type: VTPM ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified VTPM instance.
Signature:
void destroy (session_id s, VTPM ref self)
Arguments:
type
VTPM ref
name
self
description
reference to the object
Return Type: void
RPC name: get by uuid
Overview: Get a reference to the VTPM instance with the specified UUID.
Signature:
(VTPM ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: VTPM ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given VTPM.
Signature:
(VTPM record) get_record (session_id s, VTPM ref self)
161
2.25. CLASS: VTPM
CHAPTER 2. API REFERENCE
Arguments:
type
VTPM ref
name
self
description
reference to the object
Return Type: VTPM record
all fields from the object
162
2.26. CLASS: CONSOLE
CHAPTER 2. API REFERENCE
2.26
Class: console
2.26.1
Fields for class: console
Name
Description
Quals
RO run
RO run
RO run
RO run
RW
2.26.2
console
A console.
Field
uuid
protocol
location
VM
other config
Type
string
console protocol
string
VM ref
(string → string) Map
Description
unique identifier/object reference
the protocol used by this console
URI for the console service
VM to which this console is attached
additional configuration
RPCs associated with class: console
RPC name: get all
Overview: Return a list of all the consoles known to the system.
Signature:
((console ref) Set) get_all (session_id s)
Return Type: (console ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given console.
Signature:
string get_uuid (session_id s, console ref self)
Arguments:
type
console ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get protocol
Overview: Get the protocol field of the given console.
Signature:
(console_protocol) get_protocol (session_id s, console ref self)
Arguments:
type
console ref
name
self
description
reference to the object
Return Type: console protocol
163
2.26. CLASS: CONSOLE
CHAPTER 2. API REFERENCE
value of the field
RPC name: get location
Overview: Get the location field of the given console.
Signature:
string get_location (session_id s, console ref self)
Arguments:
type
console ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get VM
Overview: Get the VM field of the given console.
Signature:
(VM ref) get_VM (session_id s, console ref self)
Arguments:
type
console ref
name
self
description
reference to the object
Return Type: VM ref
value of the field
RPC name: get other config
Overview: Get the other config field of the given console.
Signature:
((string -> string) Map) get_other_config (session_id s, console ref self)
Arguments:
type
console ref
name
self
description
reference to the object
Return Type: (string → string) Map
value of the field
164
2.26. CLASS: CONSOLE
CHAPTER 2. API REFERENCE
RPC name: set other config
Overview: Set the other config field of the given console.
Signature:
void set_other_config (session_id s, console ref self, (string -> string) Map value)
Arguments:
type
console ref
(string → string) Map
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: add to other config
Overview: Add the given key-value pair to the other config field of the given console.
Signature:
void add_to_other_config (session_id s, console ref self, string key, string value)
Arguments:
type
console ref
string
string
name
self
key
value
description
reference to the object
Key to add
Value to add
Return Type: void
RPC name: remove from other config
Overview: Remove the given key and its corresponding value from the other config field of the
given console. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session_id s, console ref self, string key)
Arguments:
type
console ref
string
name
self
key
description
reference to the object
Key to remove
Return Type: void
RPC name: create
Overview: Create a new console instance, and return its handle.
Signature:
(console ref) create (session_id s, console record args)
165
2.26. CLASS: CONSOLE
CHAPTER 2. API REFERENCE
Arguments:
type
console record
name
args
description
All constructor arguments
Return Type: console ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified console instance.
Signature:
void destroy (session_id s, console ref self)
Arguments:
type
console ref
name
self
description
reference to the object
Return Type: void
RPC name: get by uuid
Overview: Get a reference to the console instance with the specified UUID.
Signature:
(console ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: console ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given console.
Signature:
(console record) get_record (session_id s, console ref self)
Arguments:
type
console ref
name
self
description
reference to the object
Return Type: console record
all fields from the object
166
2.27. CLASS: DPCI
CHAPTER 2. API REFERENCE
2.27
Class: DPCI
2.27.1
Fields for class: DPCI
Name
Description
Quals
RO run
RO inst
RO inst
RO inst
DPCI
A pass-through PCI device.
Field
Type
uuid
string
VM
VM ref
PPCI
PPCI ref
hotplug slot
int
RO run
RO run
RO run
RO run
RO run
virtual
virtual
virtual
virtual
virtual
2.27.2
domain
bus
slot
func
name
int
int
int
int
string
Description
unique identifier/object reference
the virtual machine
the physical PCI device
the slot number to which this PCI device is inserted
the virtual domain number
the virtual bus number
the virtual slot number
the virtual func number
the virtual PCI name
RPCs associated with class: DPCI
RPC name: get all
Overview: Return a list of all the DPCIs known to the system.
Signature:
((DPCI ref) Set) get_all (session_id s)
Return Type: (DPCI ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given DPCI.
Signature:
string get_uuid (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get VM
Overview: Get the VM field of the given DPCI.
Signature:
(VM ref) get_VM (session_id s, DPCI ref self)
167
2.27. CLASS: DPCI
CHAPTER 2. API REFERENCE
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: VM ref
value of the field
RPC name: get PPCI
Overview: Get the PPCI field of the given DPCI.
Signature:
(PPCI ref) get_PPCI (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: PPCI ref
value of the field
RPC name: get hotplug slot
Overview: Get the hotplug slot field of the given DPCI.
Signature:
int get_hotplug_slot (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get virtual domain
Overview: Get the virtual domain field of the given DPCI.
Signature:
int get_virtual_domain (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
168
2.27. CLASS: DPCI
CHAPTER 2. API REFERENCE
RPC name: get virtual bus
Overview: Get the virtual bus field of the given DPCI.
Signature:
int get_virtual_bus (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get virtual slot
Overview: Get the virtual slot field of the given DPCI.
Signature:
int get_virtual_slot (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get virtual func
Overview: Get the virtual func field of the given DPCI.
Signature:
int get_virtual_func (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get virtual name
Overview: Get the virtual name field of the given DPCI.
Signature:
string get_virtual_name (session_id s, DPCI ref self)
169
2.27. CLASS: DPCI
CHAPTER 2. API REFERENCE
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: create
Overview: Create a new DPCI instance, and return its handle.
Signature:
(DPCI ref) create (session_id s, DPCI record args)
Arguments:
type
DPCI record
name
args
description
All constructor arguments
Return Type: DPCI ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified DPCI instance.
Signature:
void destroy (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: void
RPC name: get by uuid
Overview: Get a reference to the DPCI instance with the specified UUID.
Signature:
(DPCI ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: DPCI ref
reference to the object
170
2.27. CLASS: DPCI
CHAPTER 2. API REFERENCE
RPC name: get record
Overview: Get a record containing the current state of the given DPCI.
Signature:
(DPCI record) get_record (session_id s, DPCI ref self)
Arguments:
type
DPCI ref
name
self
description
reference to the object
Return Type: DPCI record
all fields from the object
171
2.28. CLASS: PPCI
CHAPTER 2. API REFERENCE
2.28
Class: PPCI
2.28.1
Fields for class: PPCI
Name
Description
Quals
RO run
RO run
PPCI
A physical PCI device.
Field
uuid
host
Type
string
host ref
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
RO run
domain
bus
slot
func
name
vendor id
vendor name
device id
device name
revision id
class code
class name
subsystem vendor id
subsystem vendor name
subsystem id
subsystem name
driver
int
int
int
int
string
int
string
int
string
int
int
string
int
string
int
string
string
2.28.2
Description
unique identifier/object reference
the physical machine to which this
PPCI is connected
the domain number
the bus number
the slot number
the func number
the PCI name
the vendor ID
the vendor name
the device ID
the device name
the revision ID
the class code
the class name
the subsystem vendor ID
the subsystem vendor name
the subsystem ID
the subsystem name
the driver name
RPCs associated with class: PPCI
RPC name: get all
Overview: Return a list of all the PPCIs known to the system.
Signature:
((PPCI ref) Set) get_all (session_id s)
Return Type: (PPCI ref) Set
references to all objects
RPC name: get uuid
Overview: Get the uuid field of the given PPCI.
Signature:
string get_uuid (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: string
172
2.28. CLASS: PPCI
CHAPTER 2. API REFERENCE
value of the field
RPC name: get host
Overview: Get the host field of the given PPCI.
Signature:
(host ref) get_host (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: host ref
value of the field
RPC name: get domain
Overview: Get the domain field of the given PPCI.
Signature:
int get_domain (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get bus
Overview: Get the bus field of the given PPCI.
Signature:
int get_bus (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
173
2.28. CLASS: PPCI
CHAPTER 2. API REFERENCE
RPC name: get slot
Overview: Get the slot field of the given PPCI.
Signature:
int get_slot (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get func
Overview: Get the func field of the given PPCI.
Signature:
int get_func (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get name
Overview: Get the name field of the given PPCI.
Signature:
string get_name (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get vendor id
Overview: Get the vendor id field of the given PPCI.
Signature:
int get_vendor_id (session_id s, PPCI ref self)
174
2.28. CLASS: PPCI
CHAPTER 2. API REFERENCE
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get vendor name
Overview: Get the vendor name field of the given PPCI.
Signature:
string get_vendor_name (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get device id
Overview: Get the device id field of the given PPCI.
Signature:
int get_device_id (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get device name
Overview: Get the device name field of the given PPCI.
Signature:
string get_device_name (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
175
2.28. CLASS: PPCI
CHAPTER 2. API REFERENCE
RPC name: get revision id
Overview: Get the revision id field of the given PPCI.
Signature:
int get_revision_id (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get class code
Overview: Get the class code field of the given PPCI.
Signature:
int get_class_code (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get class name
Overview: Get the class name field of the given PPCI.
Signature:
string get_class_name (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get subsystem vendor id
Overview: Get the subsystem vendor id field of the given PPCI.
Signature:
int get_subsystem_vendor_id (session_id s, PPCI ref self)
176
2.28. CLASS: PPCI
CHAPTER 2. API REFERENCE
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get subsystem vendor name
Overview: Get the subsystem vendor name field of the given PPCI.
Signature:
string get_subsystem_vendor_name (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get subsystem id
Overview: Get the subsystem id field of the given PPCI.
Signature:
int get_subsystem_id (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: int
value of the field
RPC name: get subsystem name
Overview: Get the subsystem name field of the given PPCI.
Signature:
string get_subsystem_name (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
177
2.28. CLASS: PPCI
CHAPTER 2. API REFERENCE
RPC name: get driver
Overview: Get the driver field of the given PPCI.
Signature:
string get_driver (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get by uuid
Overview: Get a reference to the PPCI instance with the specified UUID.
Signature:
(PPCI ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: PPCI ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given PPCI.
Signature:
(PPCI record) get_record (session_id s, PPCI ref self)
Arguments:
type
PPCI ref
name
self
description
reference to the object
Return Type: PPCI record
all fields from the object
178
2.29. CLASS: USER
CHAPTER 2. API REFERENCE
2.29
Class: user
2.29.1
Fields for class: user
Name
Description
Quals
RO run
RO ins
RW
2.29.2
user
A user of the
Field
uuid
short name
fullname
system.
Type
string
string
string
Description
unique identifier/object reference
short name (e.g. userid)
full name
RPCs associated with class: user
RPC name: get uuid
Overview: Get the uuid field of the given user.
Signature:
string get_uuid (session_id s, user ref self)
Arguments:
type
user ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get short name
Overview: Get the short name field of the given user.
Signature:
string get_short_name (session_id s, user ref self)
Arguments:
type
user ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get fullname
Overview: Get the fullname field of the given user.
Signature:
string get_fullname (session_id s, user ref self)
Arguments:
type
user ref
name
self
description
reference to the object
179
2.29. CLASS: USER
CHAPTER 2. API REFERENCE
Return Type: string
value of the field
RPC name: set fullname
Overview: Set the fullname field of the given user.
Signature:
void set_fullname (session_id s, user ref self, string value)
Arguments:
type
user ref
string
name
self
value
description
reference to the object
New value to set
Return Type: void
RPC name: create
Overview: Create a new user instance, and return its handle.
Signature:
(user ref) create (session_id s, user record args)
Arguments:
type
user record
name
args
description
All constructor arguments
Return Type: user ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified user instance.
Signature:
void destroy (session_id s, user ref self)
Arguments:
type
user ref
name
self
description
reference to the object
Return Type: void
180
2.29. CLASS: USER
CHAPTER 2. API REFERENCE
RPC name: get by uuid
Overview: Get a reference to the user instance with the specified UUID.
Signature:
(user ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: user ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given user.
Signature:
(user record) get_record (session_id s, user ref self)
Arguments:
type
user ref
name
self
description
reference to the object
Return Type: user record
all fields from the object
181
2.30. CLASS: XSPOLICY
CHAPTER 2. API REFERENCE
2.30
Class: XSPolicy
2.30.1
Fields for class: XSPolicy
Name
Description
Quals
RO run
RW
RO run
RO run
2.30.2
XSPolicy
A Xen Security Policy
Field
Type
uuid
string
repr
string
type
xs type
flags xs instantiationflags
Description
unique identifier / object reference
representation of policy, i.e., XML
type of the policy
policy status flags
Semantics of the class: XSPolicy
The XSPolicy class is used for administering Xen Security policies. Through this class a new
policy can be uploaded to the system, loaded into the Xen hypervisor for enforcement and be set
as the policy that the system is automatically loading when the machine is started.
This class returns information about the currently administered policy, including a reference to
the policy. This reference can then be used with policy-specific classes, i.e., the ACMPolicy class,
to allow retrieval of information or changes to be made to a particular policy.
2.30.3
Structure and datatypes of class: XSPolicy
Format of the security label:
A security label consist of the three different parts policy type, policy name and label separated
with colons. To specify the virtual machine label for an ACM-type policy xm-test, the security
label string would be ACM:xm-test:blue, where blue denotes the virtual machine’s label. The
format of resource labels is the same.
The following flags are used by this class:
xs type
XS POLICY ACM
xs instantiationflags
XS INST NONE
XS INST BOOT
XS INST LOAD
xs policystate
xserr
xs ref
repr
type
flags
version
errors
value
(1 << 0)
value
0
(1 << 0)
(1 << 1)
type
int
XSPolicy ref
string
xs type
xs instantiationflags
string
string
meaning
ACM-type policy
meaning
do nothing
make system boot with this policy
load policy immediately
meaning
Error code from operation (if applicable)
reference to the XS policy as returned by the API
representation of the policy, i.e., XML
the type of the policy
instantiation flags of the policy
version of the policy
Base64-encoded sequence of integer tuples consisting
of (error code, detail); will be returned as part
of the xs setpolicy function.
182
2.30. CLASS: XSPOLICY
2.30.4
CHAPTER 2. API REFERENCE
Additional RPCs associated with class: XSPolicy
RPC name: get xstype
Overview: Return the Xen Security Policy types supported by this system
Signature:
xs_type get_xstype (session_id s)
Return Type: xs type
flags representing the supported Xen security policy types
RPC name: set xspolicy
Overview: Set the current XSPolicy. This function can also be be used for updating of an existing
policy whose name must be equivalent to the one of the currently running policy.
Signature:
xs_policystate set_xspolicy (session_id s, xs_type type, string repr,
xs_instantiationflags flags, bool overwrite)
Arguments:
type
xs type
string
xs instantiationflags
bool
name
type
repr
flags
overwrite
description
the type of policy
representation of the policy, i.e., XML
flags for the setting of the policy
whether to overwrite an existing policy
Return Type: xs policystate
State information about the policy. In case an error occurred, the ’xs err’ field contains the error
code. The ’errors’ may contain further information about the error.
RPC name: reset xspolicy
Overview: Attempt to reset the system’s policy by installing the default policy. Since this
function is implemented as an update to the current policy, it underlies the same restrictions.
This function may fail if for example other domains than Domain-0 are running and use a different
label than Domain-0
Signature:
xs_policystate reset_xspolicy (session_id s, xs_type type)
Arguments:
type
xs type
name
type
description
the type of policy
Return Type: xs policystate
State information about the policy. In case an error occurred, the ’xs err’ field contains the error
code. The ’errors’ may contain further information about the error.
183
2.30. CLASS: XSPOLICY
CHAPTER 2. API REFERENCE
RPC name: get xspolicy
Overview: Get information regarding the currently set Xen Security Policy
Signature:
xs_policystate get_xspolicy (session_id s)
Return Type: xs policystate
Policy state information.
RPC name: rm xsbootpolicy
Overview: Remove any policy from the default boot configuration.
Signature:
void rm_xsbootpolicy (session_id s)
Possible Error Codes: SECURITY ERROR
RPC name: get labeled resources
Overview: Get a list of resources that have been labeled.
Signature:
((string -> string) Map) get_labeled_resources (session_id s)
Return Type: (string → string) Map
A map of resources with their labels.
RPC name: set resource label
Overview: Label the given resource with the given label. An empty label removes any label from
the resource.
Signature:
void set_resource_label (session_id s, string resource, string
label, string old_label)
Arguments:
type
string
string
string
name
resource
label
old label
description
resource to label
label for the resource
Optional label value that the security label
must currently have for the change to succeed.
Possible Error Codes: SECURITY ERROR
184
2.30. CLASS: XSPOLICY
CHAPTER 2. API REFERENCE
RPC name: get resource label
Overview: Get the label of the given resource.
Signature:
string get_resource_label (session_id s, string resource)
Arguments:
type
string
name
resource
description
resource to label
Return Type: string
The label of the given resource.
RPC name: can run
Overview: Check whether a VM with the given security label could run on the system.
Signature:
int can_run (session_id s, string security_label)
Arguments:
type
string
name
security label
description
reference to the object
Return Type: int
Error code indicating whether a VM with the given security label could run. If zero, it can run.
Possible Error Codes: SECURITY ERROR
RPC name: get all
Overview: Return a list of all the XSPolicies known to the system.
Signature:
((XSPolicy ref) Set) get_all (session_id s)
Return Type: (XSPolicy ref) Set
A list of all the IDs of all the XSPolicies
RPC name: get uuid
Overview: Get the uuid field of the given XSPolicy.
Signature:
string get_uuid (session_id s, XSPolicy ref self)
Arguments:
type
XSPolicy ref
name
self
description
reference to the object
Return Type: string
value of the field
185
2.30. CLASS: XSPOLICY
CHAPTER 2. API REFERENCE
RPC name: get record
Overview: Get a record of the referenced XSPolicy.
Signature:
(XSPolicy record) get_record (session_id s, xs_ref xspolicy)
Arguments:
type
xs ref
name
self
description
reference to the object
Return Type: XSPolicy record
all fields from the object
186
2.31. CLASS: ACMPOLICY
CHAPTER 2. API REFERENCE
2.31
Class: ACMPolicy
2.31.1
Fields for class: ACMPolicy
Name
Description
Quals
RO run
RW
RO run
RO run
2.31.2
ACMPolicy
An ACM Security Policy
Field
Type
uuid
string
repr
string
type
xs type
flags xs instantiationflags
Description
unique identifier / object reference
representation of policy, in XML
type of the policy
policy status flags
Structure and datatypes of class: ACMPolicy
The following data structures are used:
RIP acm policyheader
policyname
policyurl
date
reference
namespaceurl
version
type
string
string
string
string
string
string
meaning
name of the policy
URL of the policy
data of the policy
reference of the policy
namespaceurl of the policy
version of the policy
RPC name: get header
Overview: Get the referenced policy’s header information.
Signature:
acm_policyheader get_header (session_id s, xs ref self)
Arguments:
type
xs ref
name
self
description
reference to the object
Return Type: acm policyheader
The policy’s header information.
RPC name: get xml
Overview: Get the XML representation of the given policy.
Signature:
string get_XML (session_id s, xs ref self)
Arguments:
type
xs ref
name
self
description
reference to the object
187
2.31. CLASS: ACMPOLICY
CHAPTER 2. API REFERENCE
Return Type: string
XML representation of the referenced policy
RPC name: get map
Overview: Get the mapping information of the given policy.
Signature:
string get_map (session_id s, xs ref self)
Arguments:
type
xs ref
name
self
description
reference to the object
Return Type: string
Mapping information of the referenced policy.
RPC name: get binary
Overview: Get the binary policy representation of the referenced policy.
Signature:
string get_binary (session_id s, xs ref self)
Arguments:
type
xs ref
name
self
description
reference to the object
Return Type: string
Base64-encoded representation of the binary policy.
RPC name: get enforced binary
Overview: Get the binary policy representation of the currently enforced ACM policy. In case
the default policy is loaded in the hypervisor, a policy may be managed by xend that is not yet
loaded into the hypervisor.
Signature:
string get_enforced_binary (session_id s, xs ref self)
Arguments:
type
xs ref
name
self
description
reference to the object
Return Type: string
Base64-encoded representation of the binary policy.
188
2.31. CLASS: ACMPOLICY
CHAPTER 2. API REFERENCE
RPC name: get VM ssidref
Overview: Get the ACM ssidref of the given virtual machine.
Signature:
string get_VM_ssidref (session_id s, vm ref vm)
Arguments:
type
vm ref
name
vm
description
reference to a valid VM
Return Type: int
The ssidref of the given virtual machine.
Possible Error Codes: HANDLE INVALID, VM BAD POWER STATE, SECURITY ERROR
RPC name: get all
Overview: Return a list of all the ACMPolicies known to the system.
Signature:
((ACMPolicy ref) Set) get_all (session_id s)
Return Type: (ACMPolicy ref) Set
A list of all the IDs of all the ACMPolicies
RPC name: get uuid
Overview: Get the uuid field of the given ACMPolicy.
Signature:
string get_uuid (session_id s, ACMPolicy ref self)
Arguments:
type
ACMPolicy ref
name
self
description
reference to the object
Return Type: string
value of the field
RPC name: get record
Overview: Get a record of the referenced ACMPolicy.
Signature:
(XSPolicy record) get_record (session_id s, xs_ref xspolicy)
Arguments:
type
xs ref
name
self
description
reference to the object
189
2.31. CLASS: ACMPOLICY
CHAPTER 2. API REFERENCE
Return Type: XSPolicy record
all fields from the object
190
2.32. CLASS: DEBUG
CHAPTER 2. API REFERENCE
2.32
Class: debug
2.32.1
Fields for class: debug
Class debug has no fields.
2.32.2
RPCs associated with class: debug
RPC name: get all
Overview: Return a list of all the debug records known to the system
Signature:
((debug ref) Set) get_all (session_id s)
Return Type: (debug ref) Set
A list of all the IDs of all the debug records
RPC name: return failure
Overview: Return an API ’successful’ failure.
Signature:
void return_failure (session_id s)
Return Type: void
RPC name: create
Overview: Create a new debug instance, and return its handle.
Signature:
(debug ref) create (session_id s, debug record args)
Arguments:
type
debug record
name
args
description
All constructor arguments
Return Type: debug ref
reference to the newly created object
RPC name: destroy
Overview: Destroy the specified debug instance.
Signature:
void destroy (session_id s, debug ref self)
191
2.32. CLASS: DEBUG
CHAPTER 2. API REFERENCE
Arguments:
type
debug ref
name
self
description
reference to the object
Return Type: void
RPC name: get by uuid
Overview: Get a reference to the debug instance with the specified UUID.
Signature:
(debug ref) get_by_uuid (session_id s, string uuid)
Arguments:
type
string
name
uuid
description
UUID of object to return
Return Type: debug ref
reference to the object
RPC name: get record
Overview: Get a record containing the current state of the given debug.
Signature:
(debug record) get_record (session_id s, debug ref self)
Arguments:
type
debug ref
name
self
description
reference to the object
Return Type: debug record
all fields from the object
192
Chapter 3
GNU Free Documentation License
Version 1.2, November 2002
c
Copyright 2000,2001,2002
Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but
changing it is not allowed.
Preamble
The purpose of this License is to make a manual, textbook, or other functional and useful document
”free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially. Secondarily, this License
preserves for the author and publisher a way to get credit for their work, while not being considered
responsible for modifications made by others.
This License is a kind of ”copyleft”, which means that derivative works of the document must
themselves be free in the same sense. It complements the GNU General Public License, which is
a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software
needs free documentation: a free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to software manuals; it can be used for
any textual work, regardless of subject matter or whether it is published as a printed book. We
recommend this License principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed
by the copyright holder saying it can be distributed under the terms of this License. Such a
notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the
conditions stated herein. The ”Document”, below, refers to any such manual or work. Any
member of the public is a licensee, and is addressed as ”you”. You accept the license if you copy,
modify or distribute the work in a way requiring permission under copyright law.
A ”Modified Version” of the Document means any work containing the Document or a portion
of it, either copied verbatim, or with modifications and/or translated into another language.
A ”Secondary Section” is a named appendix or a front-matter section of the Document that
deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within
that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary
Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or
political position regarding them.
193
CHAPTER 3. GNU FREE DOCUMENTATION LICENSE
The ”Invariant Sections” are certain Secondary Sections whose titles are designated, as being
those of Invariant Sections, in the notice that says that the Document is released under this
License. If a section does not fit the above definition of Secondary then it is not allowed to be
designated as Invariant. The Document may contain zero Invariant Sections. If the Document
does not identify any Invariant Sections then there are none.
The ”Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or
Back-Cover Texts, in the notice that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ”Transparent” copy of the Document means a machine-readable copy, represented in a format
whose specification is available to the general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text
formatters or for automatic translation to a variety of formats suitable for input to text formatters.
A copy made in an otherwise Transparent file format whose markup, or absence of markup, has
been arranged to thwart or discourage subsequent modification by readers is not Transparent. An
image format is not Transparent if used for any substantial amount of text. A copy that is not
”Transparent” is called ”Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo
input format, LaTeX input format, SGML or XML using a publicly available DTD, and standardconforming simple HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary
formats that can be read and edited only by proprietary word processors, SGML or XML for
which the DTD and/or processing tools are not generally available, and the machine-generated
HTML, PostScript or PDF produced by some word processors for output purposes only.
The ”Title Page” means, for a printed book, the title page itself, plus such following pages as are
needed to hold, legibly, the material this License requires to appear in the title page. For works
in formats which do not have any title page as such, ”Title Page” means the text near the most
prominent appearance of the work’s title, preceding the beginning of the body of the text.
A section ”Entitled XYZ” means a named subunit of the Document whose title either is precisely
XYZ or contains XYZ in parentheses following text that translates XYZ in another language.
(Here XYZ stands for a specific section name mentioned below, such as ”Acknowledgements”,
”Dedications”, ”Endorsements”, or ”History”.) To ”Preserve the Title” of such a section
when you modify the Document means that it remains a section ”Entitled XYZ” according to this
definition.
The Document may include Warranty Disclaimers next to the notice which states that this License
applies to the Document. These Warranty Disclaimers are considered to be included by reference
in this License, but only as regards disclaiming warranties: any other implication that these
Warranty Disclaimers may have is void and has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the
reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also
follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display
copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the
Document, numbering more than 100, and the Document’s license notice requires Cover Texts,
194
CHAPTER 3. GNU FREE DOCUMENTATION LICENSE
you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: FrontCover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also
clearly and legibly identify you as the publisher of these copies. The front cover must present the
full title with all words of the title equally prominent and visible. You may add other material on
the covers in addition. Copying with changes limited to the covers, as long as they preserve the
title of the Document and satisfy these conditions, can be treated as verbatim copying in other
respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones
listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must
either include a machine-readable Transparent copy along with each Opaque copy, or state in or
with each Opaque copy a computer-network location from which the general network-using public
has access to download using public-standard network protocols a complete Transparent copy of
the Document, free of added material. If you use the latter option, you must take reasonably
prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location until at least one year after
the last time you distribute an Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the Document well before
redistributing any large number of copies, to give them a chance to provide you with an updated
version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections
2 and 3 above, provided that you release the Modified Version under precisely this License, with
the Modified Version filling the role of the Document, thus licensing distribution and modification
of the Modified Version to whoever possesses a copy of it. In addition, you must do these things
in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document,
and from those of previous versions (which should, if there were any, be listed in the History
section of the Document). You may use the same title as a previous version if the original
publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship
of the modifications in the Modified Version, together with at least five of the principal
authors of the Document (all of its principal authors, if it has fewer than five), unless they
release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright
notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission
to use the Modified Version under the terms of this License, in the form shown in the
Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts
given in the Document’s license notice.
H. Include an unaltered copy of this License.
195
CHAPTER 3. GNU FREE DOCUMENTATION LICENSE
I. Preserve the section Entitled ”History”, Preserve its Title, and add to it an item stating at
least the title, year, new authors, and publisher of the Modified Version as given on the Title
Page. If there is no section Entitled ”History” in the Document, create one stating the title,
year, authors, and publisher of the Document as given on its Title Page, then add an item
describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document
for previous versions it was based on. These may be placed in the ”History” section. You
may omit a network location for a work that was published at least four years before the
Document itself, or if the original publisher of the version it refers to gives permission.
K. For any section Entitled ”Acknowledgements” or ”Dedications”, Preserve the Title of the
section, and preserve in the section all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their
titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section Entitled ”Endorsements”. Such a section may not be included in the
Modified Version.
N. Do not retitle any existing section to be Entitled ”Endorsements” or to conflict in title with
any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary
Sections and contain no material copied from the Document, you may at your option designate
some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections
in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled ”Endorsements”, provided it contains nothing but endorsements
of your Modified Version by various parties–for example, statements of peer review or that the
text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as
a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage
of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made
by) any one entity. If the Document already includes a cover text for the same cover, previously
added by you or by arrangement made by the same entity you are acting on behalf of, you may not
add another; but you may replace the old one, on explicit permission from the previous publisher
that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use
their names for publicity for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms
defined in section 4 above for modified versions, provided that you include in the combination all of
the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant
Sections of your combined work in its license notice, and that you preserve all their Warranty
Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant
Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same
name but different contents, make the title of each such section unique by adding at the end of
it, in parentheses, the name of the original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in the list of Invariant Sections
in the license notice of the combined work.
196
CHAPTER 3. GNU FREE DOCUMENTATION LICENSE
In the combination, you must combine any sections Entitled ”History” in the various original
documents, forming one section Entitled ”History”; likewise combine any sections Entitled ”Acknowledgements”, and any sections Entitled ”Dedications”. You must delete all sections Entitled
”Endorsements”.
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this
License, and replace the individual copies of this License in the various documents with a single
copy that is included in the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under
this License, provided you insert a copy of this License into the extracted document, and follow
this License in all other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents
or works, in or on a volume of a storage or distribution medium, is called an ”aggregate” if the
copyright resulting from the compilation is not used to limit the legal rights of the compilation’s
users beyond what the individual works permit. When the Document is included in an aggregate,
this License does not apply to the other works in the aggregate which are not themselves derivative
works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if
the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be
placed on covers that bracket the Document within the aggregate, or the electronic equivalent of
covers if the Document is in electronic form. Otherwise they must appear on printed covers that
bracket the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include translations of some or all Invariant
Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers,
provided that you also include the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between the translation and the original
version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled ”Acknowledgements”, ”Dedications”, or ”History”, the
requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual
title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided
for under this License. Any other attempt to copy, modify, sublicense or distribute the Document
is void, and will automatically terminate your rights under this License. However, parties who
have received copies, or rights, from you under this License will not have their licenses terminated
so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation
License from time to time. Such new versions will be similar in spirit to the present version, but
may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
197
CHAPTER 3. GNU FREE DOCUMENTATION LICENSE
Each version of the License is given a distinguishing version number. If the Document specifies
that a particular numbered version of this License ”or any later version” applies to it, you have the
option of following the terms and conditions either of that specified version or of any later version
that has been published (not as a draft) by the Free Software Foundation. If the Document does
not specify a version number of this License, you may choose any version ever published (not as
a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document
and put the following copyright and license notices just after the title page:
c
Copyright YEAR
YOUR NAME. Permission is granted to copy, distribute and/or
modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the
license is included in the section entitled ”GNU Free Documentation License”.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the ”with...Texts.”
line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts
being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge
those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these
examples in parallel under your choice of free software license, such as the GNU General Public
License, to permit their use in free software.
198
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising