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 Central API Documentation</title>
12 <chapter id="Introduction">
13 <title>Introduction</title>
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
22 <section id="Authentication">
23 <title>Authentication</title>
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
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">
51 <row><entry>AuthMethod</entry><entry><literal>session</literal></entry></row>
52 <row><entry>session</entry><entry>Session key</entry></row>
58 <para>Password authentication.</para>
59 <informaltable frame="none" rules="rows">
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>
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>.
76 <informaltable frame="none" rules="rows">
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
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
92 <para>Anonymous authentication.</para>
93 <informaltable frame="none" rules="rows">
96 <row><entry>AuthMethod</entry><entry><literal>anonymous</literal></entry></row>
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>
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>
122 <section id="Filters">
123 <title>Filters</title>
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>
131 # plcsh code fragment (see below)
133 GetNodes({'node_id': [1,2,3]})
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
141 <para> Filters support a few extra features illustrated in the following examples.</para>
144 <para> <emphasis> Pattern Matching </emphasis> </para>
145 <programlisting>GetNodes ( { 'hostname' : '*.fr' } ) </programlisting>
148 <para> <emphasis> Negation </emphasis> </para>
149 <programlisting>GetNodes( { '~peer_id' : None } ) </programlisting>
152 <para> <emphasis> Numeric comparisons </emphasis> </para>
153 <programlisting>GetEvents( { '>time' : 1178531418 } ) </programlisting>
154 <programlisting>GetEvents( { ']event_id' : 2305 } ) </programlisting>
157 <para> <emphasis> Sorting and Clipping </emphasis> </para>
158 <programlisting> GetNodes( { '-SORT' : 'hostname' , '-OFFSET' : 30 , '-LIMIT' : 25 }</programlisting>
164 <title>PlanetLab shell</title>
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 ≥2.4.</para>
172 usage: plcsh [options]
175 -f CONFIG, --config=CONFIG
176 PLC configuration file
177 -h URL, --url=URL API URL
178 -c CACERT, --cacert=CACERT
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
186 -u USER, --user=USER API user name
187 -p PASSWORD, --password=PASSWORD
189 -r ROLE, --role=ROLE API role
190 -x, --xmlrpc Use XML-RPC interface
191 --help show this help message and exit
194 <para>Specify at least the API URL and your user name:</para>
197 plcsh --url https://www.planet-lab.org/PLCAPI/ -u user@site.edu
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>
205 user@site.edu connected using password authentication
206 Type "system.listMethods()" or "help(method)" for more information.
207 [user@site.edu]>>> AuthCheck()
209 [user@site.edu]>>> GetNodes([121], ['node_id', 'hostname'])
210 [{'node_id': 121, 'hostname': 'planetlab-1.cs.princeton.edu'}]
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
218 <para>To use <command>plcsh</command> programmatically, import
219 the <function>PLC.Shell</function> module:</para>
226 # Default location that the PLCAPI RPM installs the PLC class
227 sys.path.append('/usr/share/plc_api')
229 # Initialize shell environment. Shell() will define all PLCAPI methods
230 # in the specified namespace (specifying globals() will define them
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")
238 # Both are equivalent
239 nodes = GetNodes([121], ['node_id', 'hostname'])
240 nodes = plc.GetNodes([121], ['node_id', 'hostname'])
245 <chapter id="Methods">
246 <title>PlanetLab API Methods</title>
254 <!-- LocalWords: PlanetLab API PLCAPI RPC HTTPS listMethods methodSignature
256 <!-- LocalWords: methodHelp multicall AuthMethod GetSession GnuPG Username GPG
258 <!-- LocalWords: AuthString AddPersonKey AddPeer UpdatePeer gpg