view docs/xen-api/wire-protocol.tex @ 19973:42795382cb93

docs/xenapi: Update examples section reflecting the current behaviour.

Signed-off-by: Andreas Florath <>
author Keir Fraser <>
date Tue Jul 14 14:37:53 2009 +0100 (2009-07-14)
parents a2903704c17a
line source
1 %
2 % Copyright (c) 2006-2007 XenSource, Inc.
3 % Copyright (c) 2009 flonatel GmbH & Co. KG
4 %
5 % Permission is granted to copy, distribute and/or modify this document under
6 % the terms of the GNU Free Documentation License, Version 1.2 or any later
7 % version published by the Free Software Foundation; with no Invariant
8 % Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the
9 % license is included in the section entitled
10 % "GNU Free Documentation License" or the file fdl.tex.
11 %
12 % Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
13 % Contributor: Andreas Florath
14 %
16 \section{Wire Protocol for Remote API Calls}
18 API calls are sent over a network to a Xen-enabled host using
19 the XML-RPC protocol. In this Section we describe how the
20 higher-level types used in our API Reference are mapped to
21 primitive XML-RPC types.
23 In our API Reference we specify the signatures of API functions in the following
24 style:
25 \begin{verbatim}
26 (ref_vm Set) VM.get_all()
27 \end{verbatim}
28 This specifies that the function with name {\tt VM.get\_all} takes
29 no parameters and returns a Set of {\tt ref\_vm}s.
30 These types are mapped onto XML-RPC types in a straight-forward manner:
31 \begin{itemize}
32 \item Floats, Bools, DateTimes and Strings map directly to the XML-RPC {\tt
33 double}, {\tt boolean}, {\tt dateTime.iso8601}, and {\tt string} elements.
35 \item all ``{\tt ref\_}'' types are opaque references, encoded as the
36 XML-RPC's {\tt String} type. Users of the API should not make assumptions
37 about the concrete form of these strings and should not expect them to
38 remain valid after the client's session with the server has terminated.
40 \item fields named ``{\tt uuid}'' of type ``{\tt String}'' are mapped to
41 the XML-RPC {\tt String} type. The string itself is the OSF
42 DCE UUID presentation format (as output by {\tt uuidgen}, etc).
44 \item ints are all assumed to be 64-bit in our API and are encoded as a
45 string of decimal digits (rather than using XML-RPC's built-in 32-bit {\tt
46 i4} type).
48 \item values of enum types are encoded as strings. For example, a value of
49 {\tt destroy} of type {\tt on\_normal\_exit}, would be conveyed as:
50 \begin{verbatim}
51 <value><string>destroy</string></value>
52 \end{verbatim}
54 \item for all our types, {\tt t}, our type {\tt t Set} simply maps to
55 XML-RPC's {\tt Array} type, so for example a value of type {\tt cpu\_feature
56 Set} would be transmitted like this:
58 \begin{verbatim}
59 <array>
60 <data>
61 <value><string>CX8</string></value>
62 <value><string>PSE36</string></value>
63 <value><string>FPU</string></value>
64 </data>
65 </array>
66 \end{verbatim}
68 \item for types {\tt k} and {\tt v}, our type {\tt (k, v) Map} maps onto an
69 XML-RPC struct, with the key as the name of the struct. Note that the {\tt
70 (k, v) Map} type is only valid when {\tt k} is a {\tt String}, {\tt Ref}, or
71 {\tt Int}, and in each case the keys of the maps are stringified as
72 above. For example, the {\tt (String, double) Map} containing a the mappings
73 Mike $\rightarrow$ 2.3 and John $\rightarrow$ 1.2 would be represented as:
75 \begin{verbatim}
76 <value>
77 <struct>
78 <member>
79 <name>Mike</name>
80 <value><double>2.3</double></value>
81 </member>
82 <member>
83 <name>John</name>
84 <value><double>1.2</double></value>
85 </member>
86 </struct>
87 </value>
88 \end{verbatim}
90 \item our {\tt Void} type is transmitted as an empty string.
92 \end{itemize}
94 \subsection{Note on References vs UUIDs}
96 References are opaque types --- encoded as XML-RPC strings on the wire --- understood
97 only by the particular server which generated them. Servers are free to choose
98 any concrete representation they find convenient; clients should not make any
99 assumptions or attempt to parse the string contents. References are not guaranteed
100 to be permanent identifiers for objects; clients should not assume that references
101 generated during one session are valid for any future session. References do not
102 allow objects to be compared for equality. Two references to the same object are
103 not guaranteed to be textually identical.
105 UUIDs are intended to be permanent names for objects. They are
106 guaranteed to be in the OSF DCE UUID presentation format (as output by {\tt uuidgen}.
107 Clients may store UUIDs on disk and use them to lookup objects in subsequent sessions
108 with the server. Clients may also test equality on objects by comparing UUID strings.
110 The API provides mechanisms
111 for translating between UUIDs and opaque references. Each class that contains a UUID
112 field provides:
113 \begin{itemize}
114 \item A ``{\tt get\_by\_uuid}'' method that takes a UUID, $u$, and returns an opaque reference
115 to the server-side object that has UUID=$u$;
116 \item A {\tt get\_uuid} function (a regular ``field getter'' RPC) that takes an opaque reference,
117 $r$, and returns the UUID of the server-side object that is referenced by $r$.
118 \end{itemize}
120 \subsection{Return Values/Status Codes}
121 \label{synchronous-result}
123 The return value of an RPC call is an XML-RPC {\tt Struct}.
125 \begin{itemize}
126 \item The first element of the struct is named {\tt Status}; it
127 contains a string value indicating whether the result of the call was
128 a ``{\tt Success}'' or a ``{\tt Failure}''.
129 \end{itemize}
131 If {\tt Status} was set to {\tt Success} then the Struct contains a second
132 element named {\tt Value}:
133 \begin{itemize}
134 \item The element of the struct named {\tt Value} contains the function's return value.
135 \end{itemize}
137 In the case where {\tt Status} is set to {\tt Failure} then
138 the struct contains a second element named {\tt ErrorDescription}:
139 \begin{itemize}
140 \item The element of the struct named {\tt ErrorDescription} contains
141 an array of string values. The first element of the array is an error code;
142 the remainder of the array are strings representing error parameters relating
143 to that code.
144 \end{itemize}
146 For example, an XML-RPC return value from the {\tt host.get\_resident\_VMs}
147 function above
148 may look like this:
149 \begin{verbatim}
150 <struct>
151 <member>
152 <name>Status</name>
153 <value>Success</value>
154 </member>
155 <member>
156 <name>Value</name>
157 <value>
158 <array>
159 <data>
160 <value>81547a35-205c-a551-c577-00b982c5fe00</value>
161 <value>61c85a22-05da-b8a2-2e55-06b0847da503</value>
162 <value>1d401ec4-3c17-35a6-fc79-cee6bd9811fe</value>
163 </data>
164 </array>
165 </value>
166 </member>
167 </struct>
168 \end{verbatim}
170 \section{Making XML-RPC Calls}
172 \subsection{Transport Layer}
174 The following transport layers are currently supported:
175 \begin{itemize}
176 \item HTTP/S for remote administration
177 \item HTTP over Unix domain sockets for local administration
178 \end{itemize}
180 \subsection{Session Layer}
182 The XML-RPC interface is session-based; before you can make arbitrary RPC calls
183 you must login and initiate a session. For example:
184 \begin{verbatim}
185 session_id session.login_with_password(string uname, string pwd)
186 \end{verbatim}
187 Where {\tt uname} and {\tt password} refer to your username and password
188 respectively, as defined by the Xen administrator.
189 The {\tt session\_id} returned by {\tt session.login\_with\_password} is passed
190 to subsequent RPC calls as an authentication token.
192 A session can be terminated with the {\tt session.logout} function:
193 \begin{verbatim}
194 void session.logout(session_id session)
195 \end{verbatim}
197 \subsection{Synchronous and Asynchronous invocation}
199 Each method call (apart from methods on ``Session'' and ``Task'' objects
200 and ``getters'' and ``setters'' derived from fields)
201 can be made either synchronously or asynchronously.
202 A synchronous RPC call blocks until the
203 return value is received; the return value of a synchronous RPC call is
204 exactly as specified in Section~\ref{synchronous-result}.
206 Only synchronous API calls are listed explicitly in this document.
207 All asynchronous versions are in the special {\tt Async} namespace.
208 For example, synchronous call {\tt VM.clone(...)}
209 (described in Chapter~\ref{api-reference})
210 has an asynchronous counterpart, {\tt
211 Async.VM.clone(...)}, that is non-blocking.
213 Instead of returning its result directly, an asynchronous RPC call
214 returns a {\tt task-id}; this identifier is subsequently used
215 to track the status of a running asynchronous RPC. Note that an asynchronous
216 call may fail immediately, before a {\tt task-id} has even been created---to
217 represent this eventuality, the returned {\tt task-id}
218 is wrapped in an XML-RPC struct with a {\tt Status}, {\tt ErrorDescription} and
219 {\tt Value} fields, exactly as specified in Section~\ref{synchronous-result}.
221 The {\tt task-id} is provided in the {\tt Value} field if {\tt Status} is set to
222 {\tt Success}.
224 The RPC call
225 \begin{verbatim}
226 (ref_task Set) Task.get_all(session_id s)
227 \end{verbatim}
228 returns a set of all task IDs known to the system. The status (including any
229 returned result and error codes) of these tasks
230 can then be queried by accessing the fields of the Task object in the usual way.
231 Note that, in order to get a consistent snapshot of a task's state, it is advisable to call the ``get\_record'' function.
233 \section{Example interactive session}
234 This section describes how an interactive session might look, using
235 the python API. All python versions starting from 2.4 should work.
237 The examples in this section use a remote Xen host with the ip address
238 of \texttt{} and the xmlrpc port \texttt{9363}. No
239 authentication is used.
241 Note that the remote server must be configured in the way, that it
242 accepts remote connections. Some lines must be added to the
243 xend-config.sxp configuration file:
244 \begin{verbatim}
245 (xen-api-server ((9363 none)
246 (unix none)))
247 (xend-tcp-xmlrpc-server yes)
248 \end{verbatim}
249 The xend must be restarted after changing the configuration.
251 Before starting python, the \texttt{PYTHONPATH} must be set that the
252 \texttt{} can be found. Typically the \texttt{} is
253 installed with one of the Xen helper packages which the last part of
254 the path is \texttt{xen/xm/}.
256 Example: Under Debian 5.0 the package which contains the
257 \texttt{} is \texttt{xen-utils-3.2-1}. \texttt{} is
258 located in \texttt{/usr/lib/xen-3.2-1/lib/python/xen/xm}. The
259 following command will set the \texttt{PYTHONPATH} environment
260 variable in a bash:
262 \begin{verbatim}
263 $ export PYTHONPATH=/usr/lib/xen-3.2-1/lib/python
264 \end{verbatim}
266 Then python can be started and the XenAPI must be imported:
268 \begin{verbatim}
269 $ python
270 ...
271 >>> import xen.xm.XenAPI
272 \end{verbatim}
274 To create a session to the remote server, the
275 \texttt{xen.xm.XenAPI.Session} constructor is used:
276 \begin{verbatim}
277 >>> session = xen.xm.XenAPI.Session("")
278 \end{verbatim}
280 For authentication with a username and password the
281 \texttt{login\_with\_password} is used:
282 \begin{verbatim}
283 >>> session.login_with_password("", "")
284 \end{verbatim}
286 When serialised, this call looks like:
287 \begin{verbatim}
288 POST /RPC2 HTTP/1.0
289 Host:
290 User-Agent: (by
291 Content-Type: text/xml
292 Content-Length: 221
294 <?xml version='1.0'?>
295 <methodCall>
296 <methodName>session.login_with_password</methodName>
297 <params>
298 <param>
299 <value><string></string></value>
300 </param>
301 <param>
302 <value><string></string></value>
303 </param>
304 </params>
305 </methodCall>
306 \end{verbatim}
308 And the response:
309 \begin{verbatim}
310 HTTP/1.1 200 OK
311 Server: BaseHTTP/0.3 Python/2.5.2
312 Date: Fri, 10 Jul 2009 09:01:27 GMT
313 Content-Type: text/xml
314 Content-Length: 313
316 <?xml version='1.0'?>
317 <methodResponse>
318 <params>
319 <param>
320 <value><struct>
321 <member>
322 <name>Status</name>
323 <value><string>Success</string></value>
324 </member>
325 <member>
326 <name>Value</name>
327 <value><string>68e3a009-0249-725b-246b-7fc43cf4f154</string></value>
328 </member>
329 </struct></value>
330 </param>
331 </params>
332 </methodResponse>
333 \end{verbatim}
335 Next, the user may acquire a list of all the VMs known to the host:
337 \begin{verbatim}
338 >>> vms = session.xenapi.VM.get_all()
339 >>> vms
340 ['00000000-0000-0000-0000-000000000000', 'b28e4ee3-216f-fa85-9cae-615e954dbbe7']
341 \end{verbatim}
343 The VM references here have the form of an uuid, though they may
344 change in the future, and they should be treated as opaque strings.
346 Some examples of using accessors for object fields:
347 \begin{verbatim}
348 >>> session.xenapi.VM.get_name_label(vms[1])
349 'guest002'
350 >>> session.xenapi.VM.get_actions_after_reboot(vms[1])
351 'restart'
352 \end{verbatim}
354 Grab the actual memory and cpu utilisation of one vm:
355 \begin{verbatim}
356 >>> m = session.xenapi.VM.get_metrics(vms[1])
357 >>> session.xenapi.VM_metrics.get_memory_actual(m)
358 '268435456'
359 >>> session.xenapi.VM_metrics.get_VCPUs_utilisation(m)
360 {'0': 0.00041759955632935362}
361 \end{verbatim}
362 (The virtual machine has about 256 MByte RAM and is idle.)
364 Pausing and unpausing a vm:
365 \begin{verbatim}
366 >>> session.xenapi.VM.pause(vms[1])
367 ''
368 >>> session.xenapi.VM.unpause(vms[1])
369 ''
370 \end{verbatim}
372 Trying to start an vm:
373 \begin{verbatim}
374 >>> session.xenapi.VM.start(vms[1], False)
375 ...
376 : Xen-API failure: ['VM_BAD_POWER_STATE', \
377 'b28e4ee3-216f-fa85-9cae-615e954dbbe7', 'Halted', 'Running']
378 \end{verbatim}
380 In this case the {\tt start} message has been rejected, because the VM is
381 already running, and so an error response has been returned. These high-level
382 errors are returned as structured data (rather than as XML-RPC faults),
383 allowing them to be internationalised.