1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
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="Connection">
28 <title>Connection</title>
30 <para>The NM XMLRPC server listens locally on every PlanetLab node at http://localhost:812.</para>
31 <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>
33 <section id="Example">
34 <title>An Example using the PLC and NM API</title>
36 <para>The nm-controller slice is given a stub account such that it can
37 be accessed over ssh. So rather than logging into NM server listens
38 locally on every PlanetLab node at http://localhost:812.
42 controller_slice_fields = {'name' : 'princeton_mycontroller',
43 'instantiation' : 'nm-controller',
44 'url' : 'http://www.yourhost.com',
45 'description' : 'a brief description of this slice.', }
46 controller_slice_id = api.AddSlices(plauth, controller_slice_fields)
49 <para>After this, the controller owner, should both add users and nodes to
50 this slice. As well, becasue this account is created using the standard
51 NM mechanism, you should wait at least 15 minutes for the controller slice
52 to be instantiated on all the nodes you'd like to access it. </para>
54 <para> Subsequently, slices that will be delegated to this controller will
55 be registered at PLC. An example follows.
59 delegated_slice_fields = {'name' : 'anothersite_mydelegated',
60 'instantiation' : 'delegated',
61 'url' : 'http://www.yourhost.com',
62 'description' : 'a brief description of this slice.', }
63 delegated_slice_id = api.AddSlices(plauth, delegated_slice_fields)
65 # Get ticket for this slice.
66 ticket = api.GetSliceTicket(plauth, "princetondsl_solteszdelegated")
69 <para>After the slice is registered with PLC, and your application has the
70 Ticket, the last step is to redeem the ticket by presenting it to the NM
71 through the nm-controller account. THe following code formats the message
75 # generate an XMLRPC request.
76 print xmlrpclib.dumps((ticket,), 'Ticket')
79 <para>Finally, this message must be sent to the NM using the controller
80 account. It should be possible to create a program that creates the ssh
81 connection or to use a library that does this automatically such as:
82 <ulink url="http://cheeseshop.python.org/pypi/pyXMLRPCssh/1.0-0">pyXMLRPCssh</ulink>
86 Or, you could use something much simpler. Assuming the output from
87 <literal>dumps()</literal> above, is saved to a file called
88 <literal>ticket.txt</literal>, you could run a command like:
92 cat ticket.txt | ssh princeton_mycontroller@mynode.someuniversity.edu
98 p = subprocess.Popen(['/usr/bin/ssh', 'princeton_mycontroller@mynode.someuniversity.edu'],
99 stdin=subprocess.PIPE, stdout=subprocess.PIPE)
100 print >>p.stdin, xmlrpclib.dumps((ticket,), 'Ticket')
102 print xmlrpclib.loads(p.stdout.read())
110 <chapter id="Methods">
111 <title>PlanetLab API Methods</title>
119 <!-- LocalWords: PlanetLab API PLCAPI RPC HTTPS listMethods methodSignature
121 <!-- LocalWords: methodHelp multicall AuthMethod GetSession GnuPG Username GPG
123 <!-- LocalWords: AuthString AddPersonKey AddPeer UpdatePeer gpg