debuggers.hg

changeset 19973:42795382cb93

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

Signed-off-by: Andreas Florath <xen@flonatel.org>
author Keir Fraser <keir.fraser@citrix.com>
date Tue Jul 14 14:37:53 2009 +0100 (2009-07-14)
parents 82c6d0b8852e
children 4afd6669a351
files docs/xen-api/wire-protocol.tex
line diff
     1.1 --- a/docs/xen-api/wire-protocol.tex	Mon Jul 13 16:50:53 2009 +0100
     1.2 +++ b/docs/xen-api/wire-protocol.tex	Tue Jul 14 14:37:53 2009 +0100
     1.3 @@ -1,5 +1,6 @@
     1.4  %
     1.5  % Copyright (c) 2006-2007 XenSource, Inc.
     1.6 +% Copyright (c) 2009 flonatel GmbH & Co. KG
     1.7  %
     1.8  % Permission is granted to copy, distribute and/or modify this document under
     1.9  % the terms of the GNU Free Documentation License, Version 1.2 or any later
    1.10 @@ -9,6 +10,7 @@
    1.11  % "GNU Free Documentation License" or the file fdl.tex.
    1.12  %
    1.13  % Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
    1.14 +% Contributor: Andreas Florath
    1.15  %
    1.16  
    1.17  \section{Wire Protocol for Remote API Calls}
    1.18 @@ -229,76 +231,153 @@ can then be queried by accessing the fie
    1.19  Note that, in order to get a consistent snapshot of a task's state, it is advisable to call the ``get\_record'' function.
    1.20  
    1.21  \section{Example interactive session}
    1.22 +This section describes how an interactive session might look, using
    1.23 +the python API.  All python versions starting from 2.4 should work.
    1.24  
    1.25 -This section describes how an interactive session might look, using the python
    1.26 -XML-RPC client library. 
    1.27 +The examples in this section use a remote Xen host with the ip address
    1.28 +of \texttt{192.168.7.20} and the xmlrpc port \texttt{9363}.  No
    1.29 +authentication is used.
    1.30  
    1.31 -First, initialise python and import the library {\tt xmlrpclib}:
    1.32 +Note that the remote server must be configured in the way, that it
    1.33 +accepts remote connections.  Some lines must be added to the
    1.34 +xend-config.sxp configuration file:
    1.35 +\begin{verbatim}
    1.36 +(xen-api-server ((9363 none)
    1.37 +                 (unix none)))
    1.38 +(xend-tcp-xmlrpc-server yes)
    1.39 +\end{verbatim}
    1.40 +The xend must be restarted after changing the configuration.
    1.41 +
    1.42 +Before starting python, the \texttt{PYTHONPATH} must be set that the
    1.43 +\texttt{XenAPI.py} can be found.  Typically the \texttt{XenAPI.py} is
    1.44 +installed with one of the Xen helper packages which the last part of
    1.45 +the path is \texttt{xen/xm/XenAPI.py}.
    1.46 +
    1.47 +Example: Under Debian 5.0 the package which contains the
    1.48 +\texttt{XenAPI.py} is \texttt{xen-utils-3.2-1}. \texttt{XenAPI.py} is
    1.49 +located in \texttt{/usr/lib/xen-3.2-1/lib/python/xen/xm}. The
    1.50 +following command will set the \texttt{PYTHONPATH} environment
    1.51 +variable in a bash:
    1.52  
    1.53  \begin{verbatim}
    1.54 -\$ python2.4
    1.55 -...
    1.56 ->>> import xmlrpclib
    1.57 -\end{verbatim}
    1.58 -
    1.59 -Create a python object referencing the remote server:
    1.60 -
    1.61 -\begin{verbatim}
    1.62 ->>> xen = xmlrpclib.Server("http://test:4464")
    1.63 +$ export PYTHONPATH=/usr/lib/xen-3.2-1/lib/python
    1.64  \end{verbatim}
    1.65  
    1.66 -Acquire a session token by logging in with a username and password
    1.67 -(error-handling omitted for brevity; the session token is pointed to by the
    1.68 -key {\tt 'Value'} in the returned dictionary)
    1.69 -
    1.70 -\begin{verbatim}
    1.71 ->>> session = session.login_with_password("user", "passwd")['Value']
    1.72 -\end{verbatim}
    1.73 -
    1.74 -When serialised, this call looks like the following:
    1.75 +Then python can be started and the XenAPI must be imported:
    1.76  
    1.77  \begin{verbatim}
    1.78 +$ python
    1.79 +...
    1.80 +>>> import xen.xm.XenAPI
    1.81 +\end{verbatim}
    1.82 +
    1.83 +To create a session to the remote server, the
    1.84 +\texttt{xen.xm.XenAPI.Session} constructor is used:
    1.85 +\begin{verbatim}
    1.86 +>>> session = xen.xm.XenAPI.Session("http://192.168.7.20:9363")
    1.87 +\end{verbatim}
    1.88 +
    1.89 +For authentication with a username and password the
    1.90 +\texttt{login\_with\_password} is used:
    1.91 +\begin{verbatim}
    1.92 +>>> session.login_with_password("", "")
    1.93 +\end{verbatim}
    1.94 +
    1.95 +When serialised, this call looks like:
    1.96 +\begin{verbatim}
    1.97 +POST /RPC2 HTTP/1.0
    1.98 +Host: 192.168.7.20:9363
    1.99 +User-Agent: xmlrpclib.py/1.0.1 (by www.pythonware.com)
   1.100 +Content-Type: text/xml
   1.101 +Content-Length: 221
   1.102 +
   1.103  <?xml version='1.0'?>
   1.104  <methodCall>
   1.105 -  <methodName>session.login_with_password</methodName>
   1.106 -  <params>
   1.107 -    <param>
   1.108 -      <value><string>user</string></value>
   1.109 -    </param>
   1.110 -    <param>
   1.111 -      <value><string>passwd</string></value>
   1.112 -    </param>
   1.113 -  </params>
   1.114 +<methodName>session.login_with_password</methodName>
   1.115 +<params>
   1.116 +<param>
   1.117 +<value><string></string></value>
   1.118 +</param>
   1.119 +<param>
   1.120 +<value><string></string></value>
   1.121 +</param>
   1.122 +</params>
   1.123  </methodCall>
   1.124  \end{verbatim}
   1.125  
   1.126 -Next, the user may acquire a list of all the VMs known to the host: (Note the
   1.127 -call takes the session token as the only parameter)
   1.128 +And the response:
   1.129 +\begin{verbatim}
   1.130 +HTTP/1.1 200 OK
   1.131 +Server: BaseHTTP/0.3 Python/2.5.2
   1.132 +Date: Fri, 10 Jul 2009 09:01:27 GMT
   1.133 +Content-Type: text/xml
   1.134 +Content-Length: 313
   1.135 +
   1.136 +<?xml version='1.0'?>
   1.137 +<methodResponse>
   1.138 +<params>
   1.139 +<param>
   1.140 +<value><struct>
   1.141 +<member>
   1.142 +<name>Status</name>
   1.143 +<value><string>Success</string></value>
   1.144 +</member>
   1.145 +<member>
   1.146 +<name>Value</name>
   1.147 +<value><string>68e3a009-0249-725b-246b-7fc43cf4f154</string></value>
   1.148 +</member>
   1.149 +</struct></value>
   1.150 +</param>
   1.151 +</params>
   1.152 +</methodResponse>
   1.153 +\end{verbatim}
   1.154 +
   1.155 +Next, the user may acquire a list of all the VMs known to the host:
   1.156  
   1.157  \begin{verbatim}
   1.158 ->>> all_vms = host.get_resident_VMs(session)['Value']
   1.159 ->>> all_vms
   1.160 -['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ]
   1.161 +>>> vms = session.xenapi.VM.get_all()
   1.162 +>>> vms
   1.163 +['00000000-0000-0000-0000-000000000000', 'b28e4ee3-216f-fa85-9cae-615e954dbbe7']
   1.164 +\end{verbatim}
   1.165 +
   1.166 +The VM references here have the form of an uuid, though they may
   1.167 +change in the future, and they should be treated as opaque strings.
   1.168 +
   1.169 +Some examples of using accessors for object fields:
   1.170 +\begin{verbatim}
   1.171 +>>> session.xenapi.VM.get_name_label(vms[1])
   1.172 +'guest002'
   1.173 +>>> session.xenapi.VM.get_actions_after_reboot(vms[1])
   1.174 +'restart'
   1.175  \end{verbatim}
   1.176  
   1.177 -The VM references here have the form {\tt OpaqueRef:X}, though they may not be 
   1.178 -that simple in the future, and you should treat them as opaque strings.  
   1.179 -Once a reference to a VM has been acquired a lifecycle operation may be invoked:
   1.180 +Grab the actual memory and cpu utilisation of one vm:
   1.181 +\begin{verbatim}
   1.182 +>>> m = session.xenapi.VM.get_metrics(vms[1])
   1.183 +>>> session.xenapi.VM_metrics.get_memory_actual(m)
   1.184 +'268435456'
   1.185 +>>> session.xenapi.VM_metrics.get_VCPUs_utilisation(m)
   1.186 +{'0': 0.00041759955632935362}
   1.187 +\end{verbatim}
   1.188 +(The virtual machine has about 256 MByte RAM and is idle.)
   1.189  
   1.190 +Pausing and unpausing a vm:
   1.191  \begin{verbatim}
   1.192 ->>> xen.VM.start(session, all_vms[3], False)
   1.193 -{'Status': 'Failure', 'ErrorDescription': ['VM_BAD_POWER_STATE', 'Halted', 'Running']}
   1.194 +>>> session.xenapi.VM.pause(vms[1])
   1.195 +''
   1.196 +>>> session.xenapi.VM.unpause(vms[1])
   1.197 +''
   1.198 +\end{verbatim}
   1.199 +
   1.200 +Trying to start an vm:
   1.201 +\begin{verbatim}
   1.202 +>>> session.xenapi.VM.start(vms[1], False)
   1.203 +...
   1.204 +: Xen-API failure: ['VM_BAD_POWER_STATE', \
   1.205 +    'b28e4ee3-216f-fa85-9cae-615e954dbbe7', 'Halted', 'Running']
   1.206  \end{verbatim}
   1.207  
   1.208  In this case the {\tt start} message has been rejected, because the VM is
   1.209  already running, and so an error response has been returned.  These high-level
   1.210  errors are returned as structured data (rather than as XML-RPC faults),
   1.211 -allowing them to be internationalised.  Finally, here are some examples of
   1.212 -using accessors for object fields:
   1.213 -
   1.214 -\begin{verbatim}
   1.215 ->>> xen.VM.get_name_label(session, all_vms[3])['Value']
   1.216 -'SMP'
   1.217 ->>> xen.VM.get_name_description(session, all_vms[3])['Value']
   1.218 -'Debian for Xen'
   1.219 -\end{verbatim}
   1.220 +allowing them to be internationalised.