doc/PLCAPI.xml.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3 "@DOCBOOK-43@" [
   4 <!ENTITY Methods SYSTEM "Methods.xml">
   5 ]>
   6
   7 <book>
   8   <bookinfo>
   9     <title>PlanetLab Central API Documentation</title>
  10   </bookinfo>
  11
  12   <chapter id="Introduction">
  13     <title>Introduction</title>
  14
  15     <para>The PlanetLab Central API (PLCAPI) is the interface through
  16     which the PlanetLab Central database should be accessed and
  17     maintained. The API is used by the website, by nodes, by automated
  18     scripts, and by users to access and update information about
  19     users, nodes, sites, slices, and other entities maintained by the
  20     database.</para>
  21
  22     <section id="Authentication">
  23       <title>Authentication</title>
  24
  25       <para>The API should be accessed via XML-RPC over HTTPS. The API
  26       supports the standard introspection calls <link
  27       linkend="system.listMethods">system.listMethods</link>, <link
  28       linkend="system.methodSignature">system.methodSignature</link>,
  29       and <link linkend="system.methodHelp">system.methodHelp</link>,
  30       and the standard batching call <link
  31       linkend="system.multicall">system.multicall</link>. With the
  32       exception of these calls, all PLCAPI calls take an
  33       authentication structure as their first argument. All
  34       authentication structures require the specification of
  35       <parameter>AuthMethod</parameter>. If the documentation for a
  36       call does not further specify the authentication structure, then
  37       any of (but only) the following authentication structures may be
  38       used:</para>
  39
  40       <itemizedlist>
  41         <listitem>
  42           <para>Session authentication. User sessions are typically
  43           valid for 24 hours. Node sessions are valid until the next
  44           reboot. Obtain a session key with <link
  45           linkend="GetSession">GetSession</link> using another form of
  46           authentication, such as password or GnuPG
  47           authentication.</para>
  48           <informaltable frame="none" rules="rows">
  49             <tgroup cols="3">
  50               <tbody>
  51                 <row><entry>AuthMethod</entry><entry><literal>session</literal></entry></row>
  52                 <row><entry>session</entry><entry>Session key</entry></row>
  53               </tbody>
  54             </tgroup>
  55           </informaltable>
  56         </listitem>
  57         <listitem>
  58           <para>Password authentication.</para>
  59           <informaltable frame="none" rules="rows">
  60             <tgroup cols="3">
  61               <tbody>
  62                 <row><entry>AuthMethod</entry><entry><literal>password</literal></entry></row>
  63                 <row><entry>Username</entry><entry>Username, typically an e-mail address</entry></row>
  64                 <row><entry>AuthString</entry><entry>Authentication string, typically a password</entry></row>
  65               </tbody>
  66             </tgroup>
  67           </informaltable>
  68         </listitem>
  69         <listitem>
  70           <para>GnuPG authentication. Users may upload a GPG public key
  71           using <link linkend="AddPersonKey">AddPersonKey</link>. Peer
  72           GPG keys should be added with <link
  73           linkend="AddPeer">AddPeer</link> or <link
  74           linkend="UpdatePeer">UpdatePeer</link>.
  75           </para>
  76           <informaltable frame="none" rules="rows">
  77             <tgroup cols="3">
  78               <tbody>
  79                 <row><entry>AuthMethod</entry><entry><literal>gpg</literal></entry></row>
  80                 <row><entry>name</entry><entry>Peer or user name</entry></row>
  81                 <row><entry>signature</entry><entry>GnuPG signature of
  82                 the <ulink
  83                 url="http://www.w3.org/TR/xml-c14n">canonicalized</ulink>
  84                 <ulink url="http://www.xmlrpc.com/spec">XML-RPC</ulink>
  85                 representation of the rest of the arguments to the
  86                 call.</entry></row>
  87               </tbody>
  88             </tgroup>
  89           </informaltable>
  90         </listitem>
  91         <listitem>
  92           <para>Anonymous authentication.</para>
  93           <informaltable frame="none" rules="rows">
  94             <tgroup cols="3">
  95               <tbody>
  96                 <row><entry>AuthMethod</entry><entry><literal>anonymous</literal></entry></row>
  97               </tbody>
  98             </tgroup>
  99           </informaltable>
 100         </listitem>
 101       </itemizedlist>
 102     </section>
 103
 104     <section id="Roles">
 105       <title>Roles</title>
 106
 107       <para>Some functions may only be called by users with certain
 108       roles (see <link linkend="GetRoles">GetRoles</link>), and others
 109       may return different information to different callers depending
 110       on the role(s) of the caller.</para>
 111
 112       <para>The <literal>node</literal> and
 113       <literal>anonymous</literal> roles are pseudo-roles. A function
 114       that allows the <literal>node</literal> role may be called by
 115       automated scripts running on a node, such as the Boot and Node
 116       Managers. A function that allows the
 117       <literal>anonymous</literal> role may be called by anyone; an
 118       API authentication structure must still be specified (see <xref
 119       linkend="Authentication"/>).</para>
 120     </section>
 121
 122     <section id="Filters">
 123       <title>Filters</title>
 124
 125       <para>Most of the <function>Get</function> functions take a
 126       filter argument. Filters may be arrays of integer (and sometimes
 127       string) identifiers, or a struct representing a filter on the
 128       attributes of the entities being queried. For example,</para>
 129
 130 <programlisting>
 131 # plcsh code fragment (see below)
 132 GetNodes([1,2,3])
 133 GetNodes({'node_id': [1,2,3]})
 134 </programlisting>
 135
 136       <para>Would be equivalent queries. Attributes that are
 137       themselves arrays (such as <literal>nodenetwork_ids</literal>
 138       and <literal>slice_ids</literal> for nodes) cannot be used in
 139       filters.</para>
 140
 141       <para> Filters support a few extra features illustrated in the following examples.</para>
 142       <itemizedlist>
 143         <listitem>
 144           <para> <emphasis> Pattern Matching </emphasis> </para>
 145           <programlisting>GetNodes ( { 'hostname' : '*.fr' } ) </programlisting>
 146         </listitem>
 147         <listitem>
 148           <para> <emphasis> Negation </emphasis> </para>
 149           <programlisting>GetNodes( { '~peer_id' : None } ) </programlisting>
 150         </listitem>
 151         <listitem>
 152           <para> <emphasis> Numeric comparisons </emphasis> </para>
 153           <programlisting>GetEvents( { '>time' : 1178531418 } ) </programlisting>
 154           <programlisting>GetEvents( { ']event_id' : 2305 } ) </programlisting>
 155         </listitem>
 156         <listitem>
 157           <para> <emphasis> Sorting and Clipping </emphasis> </para>
 158           <programlisting> GetNodes( { '-SORT' : 'hostname' , '-OFFSET' : 30 , '-LIMIT' : 25 }</programlisting>
 159         </listitem>
 160       </itemizedlist>
 161     </section>
 162
 163     <section>
 164       <title>PlanetLab shell</title>
 165
 166       <para>A command-line program called <command>plcsh</command>
 167       simplifies authentication structure handling, and is useful for
 168       scripting. This program is distributed as a Linux RPM called
 169       PLCAPI and requires Python &ge;2.4.</para>
 170
 171       <programlisting>
 172 usage: plcsh [options]
 173
 174 options:
 175   -f CONFIG, --config=CONFIG
 176                         PLC configuration file
 177   -h URL, --url=URL     API URL
 178   -c CACERT, --cacert=CACERT
 179                         API SSL certificate
 180   -k INSECURE, --insecure=INSECURE
 181                         Do not check SSL certificate
 182   -m METHOD, --method=METHOD
 183                         API authentication method
 184   -s SESSION, --session=SESSION
 185                         API session key
 186   -u USER, --user=USER  API user name
 187   -p PASSWORD, --password=PASSWORD
 188                         API password
 189   -r ROLE, --role=ROLE  API role
 190   -x, --xmlrpc          Use XML-RPC interface
 191   --help                show this help message and exit
 192       </programlisting>
 193
 194       <para>Specify at least the API URL and your user name:</para>
 195
 196       <programlisting>
 197 plcsh --url https://www.planet-lab.org/PLCAPI/ -u user@site.edu
 198       </programlisting>
 199
 200       <para>You will be presented with a prompt. From here, you can
 201       invoke API calls and omit the authentication structure, as it will
 202       be filled in automatically.</para>
 203
 204       <programlisting>
 205 user@site.edu connected using password authentication
 206 Type "system.listMethods()" or "help(method)" for more information.
 207 [user@site.edu]>>> AuthCheck()
 208 1
 209 [user@site.edu]>>> GetNodes([121], ['node_id', 'hostname'])
 210 [{'node_id': 121, 'hostname': 'planetlab-1.cs.princeton.edu'}]
 211       </programlisting>
 212
 213       <para>As this program is actually a Python interpreter, you may
 214       create variables, execute for loops, import other packages, etc.,
 215       directly on the command line as you would using the regular Python
 216       shell.</para>
 217
 218       <para>To use <command>plcsh</command> programmatically, import
 219       the <function>PLC.Shell</function> module:</para>
 220
 221       <programlisting>
 222 #!/usr/bin/python
 223
 224 import sys
 225
 226 # Default location that the PLCAPI RPM installs the PLC class
 227 sys.path.append('/usr/share/plc_api')
 228
 229 # Initialize shell environment. Shell() will define all PLCAPI methods
 230 # in the specified namespace (specifying globals() will define them
 231 # globally).
 232 from PLC.Shell import Shell
 233 plc = Shell(globals(),
 234             url = "https://www.planet-lab.org/PLCAPI/",
 235             user = "user@site.edu",
 236             password = "password")
 237
 238 # Both are equivalent
 239 nodes = GetNodes([121], ['node_id', 'hostname'])
 240 nodes = plc.GetNodes([121], ['node_id', 'hostname'])
 241       </programlisting>
 242     </section>
 243   </chapter>
 244
 245   <chapter id="Methods">
 246     <title>PlanetLab API Methods</title>
 247     <para></para>
 248
 249     &Methods;
 250   </chapter>
 251
 252 </book>
 253
 254 <!-- LocalWords:  PlanetLab API PLCAPI RPC HTTPS listMethods methodSignature
 255 -->
 256 <!-- LocalWords:  methodHelp multicall AuthMethod GetSession GnuPG Username GPG
 257 -->
 258 <!-- LocalWords:  AuthString AddPersonKey AddPeer UpdatePeer gpg
 259 -->