1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
4 <!ENTITY Methods SYSTEM "Methods.xml">
9 <title>PlanetLab Node Manager API Documentation</title>
12 <chapter id="Introduction">
13 <title>Introduction</title>
15 <para>The PlanetLab Node Manager API (NMAPI) is the interface through
16 which the slices access the Node API.</para>
18 <section id="Authentication">
19 <title>Authentication</title>
21 <para>Authentication for NM operations is based on the identity of the
22 connecting slice. For slices whose roles are defined as
23 'nm-controller', the target slice must be listed delegated and as
24 controlled by the calling slice.</para>
27 <section id="Delegation">
28 <title>Delegation</title>
31 <section id="Connection">
32 <title>Connection</title>
34 <para>The NM XMLRPC server listens locally on every PlanetLab node at http://localhost:812.</para>
35 <para>The NM XMLRPC server can be accessed remotely using an SSH connection through the nm-controller account. Rather than a standard shell, a special command is run that forwards all standard input to the local XMLRPC server, essentially XML-RPC over ssh.</para>
37 <section id="Example">
38 <title>An Example using the PLC and NM API</title>
40 <para>The nm-controller slice is given a stub account such that it can
41 be accessed over ssh. So rather than logging into NM server listens
42 locally on every PlanetLab node at http://localhost:812.
46 controller_slice_fields = {'name' : 'princeton_mycontroller',
47 'instantiation' : 'nm-controller',
48 'url' : 'http://www.yourhost.com',
49 'description' : 'a brief description of this slice.', }
50 controller_slice_id = api.AddSlice(plauth, controller_slice_fields)
53 <para>After this, the controller owner, should both add users and nodes to
54 this slice. As well, the controller slice is created using the standard
55 PlanetLab and NM mechanism. So, wait at least 15 minutes before attempting
56 to access the controller slice on any node.</para>
58 <para> Subsequently, slices that will be delegated to this controller will
59 be registered at PLC. An example follows.
63 delegated_slice_fields = {'name' : 'anothersite_mydelegated',
64 'instantiation' : 'delegated',
65 'url' : 'http://www.yourhost.com',
66 'description' : 'a brief description of this slice.', }
67 delegated_slice_id = api.AddSlice(plauth, delegated_slice_fields)
69 # Get ticket for this slice.
70 ticket = api.GetSliceTicket(plauth, "princetondsl_solteszdelegated")
73 <para>After the slice is registered with PLC, and your application has the
74 Ticket, the last step is to redeem the ticket by presenting it to the NM
75 through the nm-controller account. The following code formats the message
79 # generate an XMLRPC request.
80 print xmlrpclib.dumps((ticket,), 'Ticket')
83 <para>Finally, this message must be sent to the NM using the controller
84 account. It should be possible to create a program that creates the ssh
85 connection or to use a library that does this automatically such as:
86 <ulink url="http://cheeseshop.python.org/pypi/pyXMLRPCssh/1.0-0">pyXMLRPCssh</ulink>
90 Or, you could use something much simpler. Assuming the output from
91 <literal>dumps()</literal> above, is saved to a file called
92 <literal>ticket.txt</literal>, you could run a command like:
96 cat ticket.txt | ssh princeton_mycontroller@mynode.someuniversity.edu
102 p = subprocess.Popen(['/usr/bin/ssh', 'princeton_mycontroller@mynode.someuniversity.edu'],
103 stdin=subprocess.PIPE, stdout=subprocess.PIPE)
104 print >>p.stdin, xmlrpclib.dumps((ticket,), 'Ticket')
106 print xmlrpclib.loads(p.stdout.read())
110 The following is a stub to use as you would use the current
111 xmlrpclib.Server() object, but redirects the connection of SSH.
116 To use, create an XmlRpcOverSsh object like so:
117 >>> api = XmlRpcOverSsh('princeton_deisenst@planetlab-1.cs.princeton.edu')
118 and call methods as with the normal xmlrpclib.ServerProxy interface.
121 from subprocess import PIPE, Popen
122 from xmlrpclib import Fault, dumps, loads
124 __all__ = ['XmlRpcOverSsh']
128 def __init__(self, userAtHost):
129 self.userAtHost = userAtHost
131 def __getattr__(self, method):
132 return _Method(self.userAtHost, method)
136 def __init__(self, userAtHost, method):
137 self.userAtHost = userAtHost
140 def __call__(self, *args):
141 p = Popen(['ssh', self.userAtHost], stdin=PIPE, stdout=PIPE)
142 stdout, stderr = p.communicate(dumps(args, self.method))
144 raise Fault(1, stderr)
153 <chapter id="Methods">
154 <title>PlanetLab API Methods</title>
162 <!-- LocalWords: PlanetLab API PLCAPI RPC HTTPS listMethods methodSignature
164 <!-- LocalWords: methodHelp multicall AuthMethod GetSession GnuPG Username GPG
166 <!-- LocalWords: AuthString AddPersonKey AddPeer UpdatePeer gpg