view docs/xen-api/wire-protocol.tex @ 12470:fb107b9eee86

merge with xen-ia64-unstable.hg
author kaf24@localhost.localdomain
date Wed Nov 15 00:14:41 2006 +0000 (2006-11-15)
parents a2d6e4a53e7a
children 884c25ba7d26
line source
1 %
2 % Copyright (c) 2006 XenSource, Inc.
3 %
4 % Permission is granted to copy, distribute and/or modify this document under
5 % the terms of the GNU Free Documentation License, Version 1.2 or any later
6 % version published by the Free Software Foundation; with no Invariant
7 % Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the
8 % license is included in the section entitled
9 % "GNU Free Documentation License" or the file fdl.tex.
10 %
11 % Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
12 %
14 \section{Wire Protocol for Remote API Calls}
16 API calls are sent over a network to a Xen-enabled host using
17 the XML-RPC protocol. In this Section we describe how the
18 higher-level types used in our API Reference are mapped to
19 primitive XML-RPC types.
21 In our API Reference we specify the signatures of API functions in the following
22 style:
23 \begin{verbatim}
24 (ref_vm Set) Host.ListAllVMs()
25 \end{verbatim}
26 This specifies that the function with name {\tt Host.ListAllVMs} takes
27 no parameters and returns a Set of {\tt ref\_vm}s.
28 These types are mapped onto XML-RPC types in a straight-forward manner:
29 \begin{itemize}
30 \item Floats, Bools, DateTimes and Strings map directly to the XML-RPC {\tt
31 double}, {\tt boolean}, {\tt dateTime.iso8601}, and {\tt string} elements.
33 \item all our ``{\tt ref\_}'' types (e.g.\ {\tt ref\_vm} in the above
34 example) map to XML-RPC's {\tt String} type. The string itself is the OSF
35 DCE UUID presentation format (as output by {\tt uuidgen}, etc).
37 \item ints are all assumed to be 64-bit in our API and are encoded as a
38 string of decimal digits (rather than using XML-RPC's built-in 32-bit {\tt
39 i4} type).
41 \item values of enum types are encoded as strings. For example, a value of
42 {\tt destroy} of type {\tt on\_normal\_exit}, would be conveyed as:
43 \begin{verbatim}
44 <value><string>destroy</string></value>
45 \end{verbatim}
47 \item for all our types, {\tt t}, our type {\tt t Set} simply maps to
48 XML-RPC's {\tt Array} type, so for example a value of type {\tt cpu\_feature
49 Set} would be transmitted like this:
51 \begin{verbatim}
52 <array>
53 <data>
54 <value><string>CX8</string></value>
55 <value><string>PSE36</string></value>
56 <value><string>FPU</string></value>
57 </data>
58 </array>
59 \end{verbatim}
61 \item for types {\tt k} and {\tt v}, our type {\tt (k, v) Map} maps onto an
62 XML-RPC struct, with the key as the name of the struct. Note that the {\tt
63 (k, v) Map} type is only valid when {\tt k} is a {\tt String}, {\tt Ref}, or
64 {\tt Int}, and in each case the keys of the maps are stringified as
65 above. For example, the {\tt (String, double) Map} containing a the mappings
66 Mike $\rightarrow$ 2.3 and John $\rightarrow$ 1.2 would be represented as:
68 \begin{verbatim}
69 <value>
70 <struct>
71 <member>
72 <name>Mike</name>
73 <value><double>2.3</double></value>
74 </member>
75 <member>
76 <name>John</name>
77 <value><double>1.2</double></value>
78 </member>
79 </struct>
80 </value>
81 \end{verbatim}
83 \item our {\tt Void} type is transmitted as an empty string.
85 \end{itemize}
87 \subsection{Return Values/Status Codes}
88 \label{synchronous-result}
90 The return value of an RPC call is an XML-RPC {\tt Struct}.
92 \begin{itemize}
93 \item The first element of the struct is named {\tt Status}; it
94 contains a string value indicating whether the result of the call was
95 a ``{\tt Success}'' or a ``{\tt Failure}''.
96 \end{itemize}
98 If {\tt Status} was set to {\tt Success} then the Struct contains a second
99 element named {\tt Value}:
100 \begin{itemize}
101 \item The element of the struct named {\tt Value} contains the function's return value.
102 \end{itemize}
104 In the case where {\tt Status} is set to {\tt Failure} then
105 the struct contains a second element named {\tt ErrorDescription}:
106 \begin{itemize}
107 \item The element of the struct named {\tt ErrorDescription} contains
108 an array of string values. The first element of the array represents an error code;
109 the remainder of the array represents error parameters relating to that code.
110 \end{itemize}
112 For example, an XML-RPC return value from the {\tt Host.ListAllVMs} function above
113 may look like this:
114 \begin{verbatim}
115 <struct>
116 <member>
117 <name>Status</name>
118 <value>Success</value>
119 </member>
120 <member>
121 <name>Value</name>
122 <value>
123 <array>
124 <data>
125 <value>vm-id-1</value>
126 <value>vm-id-2</value>
127 <value>vm-id-3</value>
128 </data>
129 </array>
130 </value>
131 </member>
132 </struct>
133 \end{verbatim}
135 \section{Making XML-RPC Calls}
137 \subsection{Transport Layer}
139 We ought to support at least
140 \begin{itemize}
141 \item HTTP/S for remote administration
142 \item HTTP over Unix domain sockets for local administration
143 \end{itemize}
145 \subsection{Session Layer}
147 The XML-RPC interface is session-based; before you can make arbitrary RPC calls
148 you must login and initiate a session. For example:
149 \begin{verbatim}
150 session_id Session.login_with_password(string uname, string pwd)
151 \end{verbatim}
152 Where {\tt uname} and {\tt password} refer to your username and password
153 respectively, as defined by the Xen administrator.
154 The {\tt session\_id} returned by {\tt Session.Login} is passed to subequent
155 RPC calls as an authentication token.
157 A session can be terminated with the {\tt Session.Logout} function:
158 \begin{verbatim}
159 void Session.Logout(session_id session)
160 \end{verbatim}
162 \subsection{Synchronous and Asynchronous invocation}
164 Each method call (apart from those on ``Session'' and ``Task'' objects)
165 can be made either synchronously or asynchronously.
166 A synchronous RPC call blocks until the
167 return value is received; the return value of a synchronous RPC call is
168 exactly as specified in Section~\ref{synchronous-result}.
170 Each of the methods specified in the API Reference is synchronous.
171 However, although not listed explicitly in this document, each
172 method call has an asynchronous analogue in the {\tt Async}
173 namespace. For example, synchronous call {\tt VM.Install(...)}
174 (described in Chapter~\ref{api-reference})
175 has an asynchronous counterpart, {\tt
176 Async.VM.Install(...)}, that is non-blocking.
178 Instead of returning its result directly, an asynchronous RPC call
179 returns a {\tt task-id}; this identifier is subsequently used
180 to track the status of a running asynchronous RPC. Note that an asychronous
181 call may fail immediately, before a {\tt task-id} has even been created---to
182 represent this eventuality, the returned {\tt task-id}
183 is wrapped in an XML-RPC struct with a {\tt Status}, {\tt ErrorDescription} and
184 {\tt Value} fields, exactly as specified in Section~\ref{synchronous-result}.
186 The {\tt task-id} is provided in the {\tt Value} field if {\tt Status} is set to
187 {\tt Success}.
189 Two special RPC calls are provided to poll the status of
190 asynchronous calls:
191 \begin{verbatim}
192 Array<task_id> Async.Task.GetAllTasks (session_id s)
193 task_status Async.Task.GetStatus (session_id s, task_id t)
194 \end{verbatim}
196 {\tt Async.Task.GetAllTasks} returns a set of the currently
197 executing asynchronous tasks belong to the current user\footnote{
198 %
199 The current user is determined by the username that was provided
200 to {\tt Session.Login}.
201 %
202 }.
204 {\tt Async.Task.GetStatus} returns a {\tt task\_status} result.
205 This is an XML-RPC struct with three elements:
206 \begin{itemize}
207 \item The first element is named {\tt Progress} and contains
208 an {\tt Integer} between 0 and 100 representing the estimated percentage of
209 the task currently completed.
210 \item The second element is named {\tt ETA} and contains a {\tt DateTime}
211 representing the estimated time the task will be complete.
212 \item The third element is named {\tt Result}. If {\tt Progress}
213 is not 100 then {\tt Result} contains the empty string. If {\tt Progress}
214 {\em is\/} set to 100, then {\tt Result} contains the function's return
215 result (as specified in Section~\ref{synchronous-result})\footnote{
216 %
217 Recall that this itself is a struct potentially containing status, errorcode,
218 value fields etc.
219 %
220 }.
221 \end{itemize}
223 \section{Example interactive session}
225 This section describes how an interactive session might look, using the python
226 XML-RPC client library.
228 First, initialise python and import the library {\tt xmlrpclib}:
230 \begin{verbatim}
231 \$ python2.4
232 ...
233 >>> import xmlrpclib
234 \end{verbatim}
236 Create a python object referencing the remote server:
238 \begin{verbatim}
239 >>> xen = xmlrpclib.Server("http://test:4464")
240 \end{verbatim}
242 Acquire a session token by logging in with a username and password (error-handling ommitted for brevity; the session token is pointed to by the key {\tt 'Value'} in the returned dictionary)
244 \begin{verbatim}
245 >>> session = xen.Session.do_login_with_password("user", "passwd")['Value']
246 \end{verbatim}
248 When serialised, this call looks like the following:
250 \begin{verbatim}
251 <?xml version='1.0'?>
252 <methodCall>
253 <methodName>Session.do_login_with_password</methodName>
254 <params>
255 <param>
256 <value><string>user</string></value>
257 </param>
258 <param>
259 <value><string>passwd</string></value>
260 </param>
261 </params>
262 </methodCall>
263 \end{verbatim}
265 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)
267 \begin{verbatim}
268 >>> all_vms = xen.VM.do_list(session)['Value']
269 >>> all_vms
270 ['b7b92d9e-d442-4710-92a5-ab039fd7d89b', '23e1e837-abbf-4675-b077-d4007989b0cc', '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2', '3202ae18-a046-4c32-9fda-e32e9631866e']
271 \end{verbatim}
273 Note the VM references are internally UUIDs. Once a reference to a VM has been acquired a lifecycle operation may be invoked:
275 \begin{verbatim}
276 >>> xen.VM.do_start(session, all_vms[3], False)
277 {'Status': 'Failure', 'ErrorDescription': 'Operation not implemented'}
278 \end{verbatim}
280 In this case the {\tt start} message has not been implemented and an error response has been returned. Currently these high-level errors are returned as structured data (rather than as XMLRPC faults), allowing for internationalised errors in future. Finally, here are some examples of using accessors for object fields:
282 \begin{verbatim}
283 >>> xen.VM.getname_label(session, all_vms[3])['Value']
284 'SMP'
285 >>> xen.VM.getname_description(session, all_vms[3])['Value']
286 'Debian for Xen'
287 \end{verbatim}