doc/NMAPI.xml

   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">
   5 ]>
   6
   7 <book>
   8   <bookinfo>
   9     <title>PlanetLab Node Manager API Documentation</title>
  10   </bookinfo>
  11
  12   <chapter id="Introduction">
  13     <title>Introduction</title>
  14
  15     <para>The PlanetLab Node Manager API (NMAPI) is the interface through
  16     which the slices access the Node API.</para>
  17
  18     <section id="Authentication">
  19       <title>Authentication</title>
  20
  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>
  25
  26    </section>
  27     <section id="Connection">
  28       <title>Connection</title>
  29
  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>
  32    </section>
  33     <section id="Example">
  34       <title>An Example using the PLC and NM API</title>
  35
  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.
  39
  40           </para>
  41       <programlisting>
  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)
  47       </programlisting>
  48
  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>
  53
  54         <para> Subsequently, slices that will be delegated to this controller will
  55         be registered at PLC.  An example follows.
  56         </para>
  57
  58         <programlisting>
  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)
  64
  65 # Get ticket for this slice.
  66 ticket = api.GetSliceTicket(plauth, "princetondsl_solteszdelegated")
  67         </programlisting>
  68
  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
  72         correctly.</para>
  73
  74         <programlisting>
  75 # generate an XMLRPC request.
  76 print xmlrpclib.dumps((ticket,), 'Ticket')
  77         </programlisting>
  78
  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>
  83         </para>
  84
  85         <para>
  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:
  89         </para>
  90
  91         <programlisting>
  92 cat ticket.txt | ssh princeton_mycontroller@mynode.someuniversity.edu
  93         </programlisting>
  94
  95    </section>
  96
  97   </chapter>
  98
  99   <chapter id="Methods">
 100     <title>PlanetLab API Methods</title>
 101     <para></para>
 102
 103     &Methods;
 104   </chapter>
 105
 106 </book>
 107
 108 <!-- LocalWords:  PlanetLab API PLCAPI RPC HTTPS listMethods methodSignature
 109 -->
 110 <!-- LocalWords:  methodHelp multicall AuthMethod GetSession GnuPG Username GPG
 111 -->
 112 <!-- LocalWords:  AuthString AddPersonKey AddPeer UpdatePeer gpg
 113 -->