doc/PLCAPI.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 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 GetNodes({'node_id': 1}) + GetNodes({'node_id': 2}) + GetNodes({'node_id': 3})
 135 </programlisting>
 136
 137       <para>Would all be equivalent queries. Attributes that are
 138       themselves arrays (such as <literal>nodenetwork_ids</literal>
 139       and <literal>slice_ids</literal> for nodes) cannot be used in
 140       filters.</para>
 141     </section>
 142
 143     <section>
 144       <title>PlanetLab shell</title>
 145
 146       <para>A command-line program called <command>plcsh</command>
 147       simplifies authentication structure handling, and is useful for
 148       scripting. This program is distributed as a Linux RPM called
 149       PLCAPI and requires Python &ge;2.4.</para>
 150
 151       <programlisting>
 152 usage: plcsh [options]
 153
 154 options:
 155   -f CONFIG, --config=CONFIG
 156                         PLC configuration file
 157   -h URL, --url=URL     API URL
 158   -c CACERT, --cacert=CACERT
 159                         API SSL certificate
 160   -k INSECURE, --insecure=INSECURE
 161                         Do not check SSL certificate
 162   -m METHOD, --method=METHOD
 163                         API authentication method
 164   -s SESSION, --session=SESSION
 165                         API session key
 166   -u USER, --user=USER  API user name
 167   -p PASSWORD, --password=PASSWORD
 168                         API password
 169   -r ROLE, --role=ROLE  API role
 170   -x, --xmlrpc          Use XML-RPC interface
 171   --help                show this help message and exit
 172       </programlisting>
 173
 174       <para>Specify at least the API URL and your user name:</para>
 175
 176       <programlisting>
 177 plcsh --url https://www.planet-lab.org/PLCAPI/ -u user@site.edu
 178       </programlisting>
 179
 180       <para>You will be presented with a prompt. From here, you can
 181       invoke API calls and omit the authentication structure, as it will
 182       be filled in automatically.</para>
 183
 184       <programlisting>
 185 user@site.edu connected using password authentication
 186 Type "system.listMethods()" or "help(method)" for more information.
 187 [user@site.edu]>>> AuthCheck()
 188 1
 189 [user@site.edu]>>> GetNodes([121], ['node_id', 'hostname'])
 190 [{'node_id': 121, 'hostname': 'planetlab-1.cs.princeton.edu'}]
 191       </programlisting>
 192
 193       <para>As this program is actually a Python interpreter, you may
 194       create variables, execute for loops, import other packages, etc.,
 195       directly on the command line as you would using the regular Python
 196       shell.</para>
 197
 198       <para>To use <command>plcsh</command> programmatically, import
 199       the <function>PLC.Shell</function> module:</para>
 200
 201       <programlisting>
 202 #!/usr/bin/python
 203
 204 import sys
 205
 206 # Default location that the PLCAPI RPM installs the PLC class
 207 sys.path.append('/usr/share/plc_api')
 208
 209 # Initialize shell environment. Shell() will define all PLCAPI methods
 210 # in the specified namespace (specifying globals() will define them
 211 # globally).
 212 from PLC.Shell import Shell
 213 plc = Shell(globals(),
 214             url = "https://www.planet-lab.org/PLCAPI/",
 215             user = "user@site.edu",
 216             password = "password")
 217
 218 # Both are equivalent
 219 nodes = GetNodes([121], ['node_id', 'hostname'])
 220 nodes = plc.GetNodes([121], ['node_id', 'hostname'])
 221       </programlisting>
 222     </section>
 223   </chapter>
 224
 225   <chapter id="Methods">
 226     <title>PlanetLab API Methods</title>
 227     <para></para>
 228
 229     &Methods;
 230   </chapter>
 231
 232 </book>
 233
 234 <!-- LocalWords:  PlanetLab API PLCAPI RPC HTTPS listMethods methodSignature
 235 -->
 236 <!-- LocalWords:  methodHelp multicall AuthMethod GetSession GnuPG Username GPG
 237 -->
 238 <!-- LocalWords:  AuthString AddPersonKey AddPeer UpdatePeer gpg
 239 -->