This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
Home Products Support Community News


[Xen-devel] [Patch] Fix 'Example interactive session' in docs/xen-api/wi

To: xen-devel@xxxxxxxxxxxxxxxxxxx
Subject: [Xen-devel] [Patch] Fix 'Example interactive session' in docs/xen-api/wire-protocol.tex
From: Andreas Florath <xen@xxxxxxxxxxxx>
Date: Sun, 12 Jul 2009 22:13:13 +0200
Delivery-date: Sun, 12 Jul 2009 13:13:46 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
List-help: <mailto:xen-devel-request@lists.xensource.com?subject=help>
List-id: Xen developer discussion <xen-devel.lists.xensource.com>
List-post: <mailto:xen-devel@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=unsubscribe>
Sender: xen-devel-bounces@xxxxxxxxxxxxxxxxxxx
User-agent: Mozilla-Thunderbird (X11/20090103)

In the section 'Example inteactive session' in the XenAPI documentation
the example(s) just don't work.

I tried to fix the problems and added some hints.

What do you think about the patch? Any hints are welcome!

Kind regards

Andreas Florath

Signed-off-by: Andreas Florath <xen@xxxxxxxxxxxx>

# HG changeset patch
# User Andreas Florath <xen@xxxxxxxxxxxx>
# Date 1247217566 -7200
# Node ID 5b89bfefa6668213899424341eb851bb34259461
# Parent  d6c1d7992f437c625135c2f8752fc94078ec4c31
docs/xenapi: Update examples section reflecting the current behaviour.

diff -r d6c1d7992f43 -r 5b89bfefa666 docs/xen-api/wire-protocol.tex
--- a/docs/xen-api/wire-protocol.tex    Wed Jul 08 22:08:31 2009 +0100
+++ b/docs/xen-api/wire-protocol.tex    Fri Jul 10 11:19:26 2009 +0200
@@ -1,5 +1,6 @@
 % Copyright (c) 2006-2007 XenSource, Inc.
+% Copyright (c) 2009 flonatel GmbH & Co. KG
 % Permission is granted to copy, distribute and/or modify this document
 % the terms of the GNU Free Documentation License, Version 1.2 or any later
@@ -9,6 +10,7 @@
 % "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}
@@ -229,76 +231,153 @@
 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.
-This section describes how an interactive session might look, using the
-XML-RPC client library.
+The examples in this section use a remote Xen host with the ip address
+of \texttt{} and the xmlrpc port \texttt{9363}.  No
+authentication is used.
-First, initialise python and import the library {\tt xmlrpclib}:
+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:
+(xen-api-server ((9363 none)
+                 (unix none)))
+(xend-tcp-xmlrpc-server yes)
+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:
-\$ python2.4
->>> import xmlrpclib
+$ export PYTHONPATH=/usr/lib/xen-3.2-1/lib/python
-Create a python object referencing the remote server:
+Then python can be started and the XenAPI must be imported:
->>> xen = xmlrpclib.Server("http://test:4464";)
+$ python
+>>> import xen.xm.XenAPI
-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 {\tt 'Value'} in the returned dictionary)
+To create a session to the remote server, the
+\texttt{xen.xm.XenAPI.Session} constructor is used:
->>> session = session.login_with_password("user", "passwd")['Value']
+>>> session = xen.xm.XenAPI.Session("";)
-When serialised, this call looks like the following:
+For authentication with a username and password the
+\texttt{login\_with\_password} is used:
+>>> session.login_with_password("", "")
+When serialised, this call looks like:
+User-Agent: xmlrpclib.py/1.0.1 (by www.pythonware.com)
+Content-Type: text/xml
+Content-Length: 221
 <?xml version='1.0'?>
-  <methodName>session.login_with_password</methodName>
-  <params>
-    <param>
-      <value><string>user</string></value>
-    </param>
-    <param>
-      <value><string>passwd</string></value>
-    </param>
-  </params>
-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)
+And the response:
+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'?>
+Next, the user may acquire a list of all the VMs known to the host:
->>> all_vms = host.get_resident_VMs(session)['Value']
->>> all_vms
-['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ]
+>>> vms = session.xenapi.VM.get_all()
+>>> vms
-The VM references here have the form {\tt 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
+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:
->>> xen.VM.start(session, all_vms[3], False)
-{'Status': 'Failure', 'ErrorDescription': ['VM_BAD_POWER_STATE',
'Halted', 'Running']}
+>>> session.xenapi.VM.get_name_label(vms[1])
+>>> session.xenapi.VM.get_actions_after_reboot(vms[1])
+Grab the actual memory and cpu utilisation of one vm:
+>>> m = session.xenapi.VM.get_metrics(vms[1])
+>>> session.xenapi.VM_metrics.get_memory_actual(m)
+>>> session.xenapi.VM_metrics.get_VCPUs_utilisation(m)
+{'0': 0.00041759955632935362}
+(The virtual machine has about 256 MByte RAM and is idle.)
+Pausing and unpausing a vm:
+>>> session.xenapi.VM.pause(vms[1])
+>>> session.xenapi.VM.unpause(vms[1])
+Trying to start an vm:
+>>> session.xenapi.VM.start(vms[1], False)
+: Xen-API failure: ['VM_BAD_POWER_STATE', \
+    'b28e4ee3-216f-fa85-9cae-615e954dbbe7', 'Halted', 'Running']
 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
 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:
->>> xen.VM.get_name_label(session, all_vms[3])['Value']
->>> xen.VM.get_name_description(session, all_vms[3])['Value']
-'Debian for Xen'
+allowing them to be internationalised. 

Xen-devel mailing list

<Prev in Thread] Current Thread [Next in Thread>