diff options
Diffstat (limited to 'docs/xen-api/wire-protocol.tex')
| -rw-r--r-- | docs/xen-api/wire-protocol.tex | 383 |
1 files changed, 0 insertions, 383 deletions
diff --git a/docs/xen-api/wire-protocol.tex b/docs/xen-api/wire-protocol.tex deleted file mode 100644 index dcb1a1c69d..0000000000 --- a/docs/xen-api/wire-protocol.tex +++ /dev/null @@ -1,383 +0,0 @@ -% -% Copyright (c) 2006-2007 XenSource, Inc. -% Copyright (c) 2009 flonatel GmbH & Co. KG -% -% 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" or the file fdl.tex. -% -% Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop. -% Contributor: Andreas Florath -% - -\section{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: -\begin{verbatim} - (ref_vm Set) VM.get_all() -\end{verbatim} -This specifies that the function with name {\tt VM.get\_all} takes -no parameters and returns a Set of {\tt ref\_vm}s. -These types are mapped onto XML-RPC types in a straight-forward manner: -\begin{itemize} - \item Floats, Bools, DateTimes and Strings map directly to the XML-RPC {\tt - double}, {\tt boolean}, {\tt dateTime.iso8601}, and {\tt string} elements. - - \item all ``{\tt ref\_}'' types are opaque references, encoded as the - XML-RPC's {\tt 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. - - \item fields named ``{\tt uuid}'' of type ``{\tt String}'' are mapped to - the XML-RPC {\tt String} type. The string itself is the OSF - DCE UUID presentation format (as output by {\tt uuidgen}, etc). - - \item 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 {\tt - i4} type). - - \item values of enum types are encoded as strings. For example, a value of - {\tt destroy} of type {\tt on\_normal\_exit}, would be conveyed as: - \begin{verbatim} - <value><string>destroy</string></value> - \end{verbatim} - - \item for all our types, {\tt t}, our type {\tt t Set} simply maps to - XML-RPC's {\tt Array} type, so for example a value of type {\tt cpu\_feature - Set} would be transmitted like this: - - \begin{verbatim} -<array> - <data> - <value><string>CX8</string></value> - <value><string>PSE36</string></value> - <value><string>FPU</string></value> - </data> -</array> - \end{verbatim} - - \item for types {\tt k} and {\tt v}, our type {\tt (k, v) Map} maps onto an - XML-RPC struct, with the key as the name of the struct. Note that the {\tt - (k, v) Map} type is only valid when {\tt k} is a {\tt String}, {\tt Ref}, or - {\tt Int}, and in each case the keys of the maps are stringified as - above. For example, the {\tt (String, double) Map} containing a the mappings - Mike $\rightarrow$ 2.3 and John $\rightarrow$ 1.2 would be represented as: - - \begin{verbatim} -<value> - <struct> - <member> - <name>Mike</name> - <value><double>2.3</double></value> - </member> - <member> - <name>John</name> - <value><double>1.2</double></value> - </member> - </struct> -</value> - \end{verbatim} - - \item our {\tt Void} type is transmitted as an empty string. - -\end{itemize} - -\subsection{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 {\tt 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: -\begin{itemize} -\item A ``{\tt get\_by\_uuid}'' method that takes a UUID, $u$, and returns an opaque reference -to the server-side object that has UUID=$u$; -\item A {\tt 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$. -\end{itemize} - -\subsection{Return Values/Status Codes} -\label{synchronous-result} - -The return value of an RPC call is an XML-RPC {\tt Struct}. - -\begin{itemize} -\item The first element of the struct is named {\tt Status}; it -contains a string value indicating whether the result of the call was -a ``{\tt Success}'' or a ``{\tt Failure}''. -\end{itemize} - -If {\tt Status} was set to {\tt Success} then the Struct contains a second -element named {\tt Value}: -\begin{itemize} -\item The element of the struct named {\tt Value} contains the function's return value. -\end{itemize} - -In the case where {\tt Status} is set to {\tt Failure} then -the struct contains a second element named {\tt ErrorDescription}: -\begin{itemize} -\item The element of the struct named {\tt 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. -\end{itemize} - -For example, an XML-RPC return value from the {\tt host.get\_resident\_VMs} -function above -may look like this: -\begin{verbatim} - <struct> - <member> - <name>Status</name> - <value>Success</value> - </member> - <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> -\end{verbatim} - -\section{Making XML-RPC Calls} - -\subsection{Transport Layer} - -The following transport layers are currently supported: -\begin{itemize} -\item HTTP/S for remote administration -\item HTTP over Unix domain sockets for local administration -\end{itemize} - -\subsection{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: -\begin{verbatim} - session_id session.login_with_password(string uname, string pwd) -\end{verbatim} -Where {\tt uname} and {\tt password} refer to your username and password -respectively, as defined by the Xen administrator. -The {\tt session\_id} returned by {\tt session.login\_with\_password} is passed -to subsequent RPC calls as an authentication token. - -A session can be terminated with the {\tt session.logout} function: -\begin{verbatim} - void session.logout(session_id session) -\end{verbatim} - -\subsection{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~\ref{synchronous-result}. - -Only synchronous API calls are listed explicitly in this document. -All asynchronous versions are in the special {\tt Async} namespace. -For example, synchronous call {\tt VM.clone(...)} -(described in Chapter~\ref{api-reference}) -has an asynchronous counterpart, {\tt -Async.VM.clone(...)}, that is non-blocking. - -Instead of returning its result directly, an asynchronous RPC call -returns a {\tt 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 {\tt task-id} has even been created---to -represent this eventuality, the returned {\tt task-id} -is wrapped in an XML-RPC struct with a {\tt Status}, {\tt ErrorDescription} and -{\tt Value} fields, exactly as specified in Section~\ref{synchronous-result}. - -The {\tt task-id} is provided in the {\tt Value} field if {\tt Status} is set to -{\tt Success}. - -The RPC call -\begin{verbatim} - (ref_task Set) Task.get_all(session_id s) -\end{verbatim} -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. - -\section{Example interactive session} -This section describes how an interactive session might look, using -the python API. All python versions starting from 2.4 should work. - -The examples in this section use a remote Xen host with the ip address -of \texttt{192.168.7.20} and the xmlrpc port \texttt{9363}. No -authentication is used. - -Note that the remote server must be configured in the way, that it -accepts remote connections. Some lines must be added to the -xend-config.sxp configuration file: -\begin{verbatim} -(xen-api-server ((9363 none) - (unix none))) -(xend-tcp-xmlrpc-server yes) -\end{verbatim} -The xend must be restarted after changing the configuration. - -Before starting python, the \texttt{PYTHONPATH} must be set that the -\texttt{XenAPI.py} can be found. Typically the \texttt{XenAPI.py} is -installed with one of the Xen helper packages which the last part of -the path is \texttt{xen/xm/XenAPI.py}. - -Example: Under Debian 5.0 the package which contains the -\texttt{XenAPI.py} is \texttt{xen-utils-3.2-1}. \texttt{XenAPI.py} is -located in \texttt{/usr/lib/xen-3.2-1/lib/python/xen/xm}. The -following command will set the \texttt{PYTHONPATH} environment -variable in a bash: - -\begin{verbatim} -$ export PYTHONPATH=/usr/lib/xen-3.2-1/lib/python -\end{verbatim} - -Then python can be started and the XenAPI must be imported: - -\begin{verbatim} -$ python -... ->>> import xen.xm.XenAPI -\end{verbatim} - -To create a session to the remote server, the -\texttt{xen.xm.XenAPI.Session} constructor is used: -\begin{verbatim} ->>> session = xen.xm.XenAPI.Session("http://192.168.7.20:9363") -\end{verbatim} - -For authentication with a username and password the -\texttt{login\_with\_password} is used: -\begin{verbatim} ->>> session.login_with_password("", "") -\end{verbatim} - -When serialised, this call looks like: -\begin{verbatim} -POST /RPC2 HTTP/1.0
-Host: 192.168.7.20:9363
-User-Agent: xmlrpclib.py/1.0.1 (by www.pythonware.com)
-Content-Type: text/xml
-Content-Length: 221
-
-<?xml version='1.0'?> -<methodCall> -<methodName>session.login_with_password</methodName> -<params> -<param> -<value><string></string></value> -</param> -<param> -<value><string></string></value> -</param> -</params> -</methodCall> -\end{verbatim} - -And the response: -\begin{verbatim} -HTTP/1.1 200 OK
-Server: BaseHTTP/0.3 Python/2.5.2
-Date: Fri, 10 Jul 2009 09:01:27 GMT
-Content-Type: text/xml
-Content-Length: 313
-
-<?xml version='1.0'?> -<methodResponse> -<params> -<param> -<value><struct> -<member> -<name>Status</name> -<value><string>Success</string></value> -</member> -<member> -<name>Value</name> -<value><string>68e3a009-0249-725b-246b-7fc43cf4f154</string></value> -</member> -</struct></value> -</param> -</params> -</methodResponse> -\end{verbatim} - -Next, the user may acquire a list of all the VMs known to the host: - -\begin{verbatim} ->>> vms = session.xenapi.VM.get_all() ->>> vms -['00000000-0000-0000-0000-000000000000', 'b28e4ee3-216f-fa85-9cae-615e954dbbe7'] -\end{verbatim} - -The VM references here have the form of an uuid, though they may -change in the future, and they should be treated as opaque strings. - -Some examples of using accessors for object fields: -\begin{verbatim} ->>> session.xenapi.VM.get_name_label(vms[1]) -'guest002' ->>> session.xenapi.VM.get_actions_after_reboot(vms[1]) -'restart' -\end{verbatim} - -Grab the actual memory and cpu utilisation of one vm: -\begin{verbatim} ->>> m = session.xenapi.VM.get_metrics(vms[1]) ->>> session.xenapi.VM_metrics.get_memory_actual(m) -'268435456' ->>> session.xenapi.VM_metrics.get_VCPUs_utilisation(m) -{'0': 0.00041759955632935362} -\end{verbatim} -(The virtual machine has about 256 MByte RAM and is idle.) - -Pausing and unpausing a vm: -\begin{verbatim} ->>> session.xenapi.VM.pause(vms[1]) -'' ->>> session.xenapi.VM.unpause(vms[1]) -'' -\end{verbatim} - -Trying to start an vm: -\begin{verbatim} ->>> session.xenapi.VM.start(vms[1], False) -... -: Xen-API failure: ['VM_BAD_POWER_STATE', \ - 'b28e4ee3-216f-fa85-9cae-615e954dbbe7', 'Halted', 'Running'] -\end{verbatim} - -In this case the {\tt 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. |