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]})
134 GetNodes({'node_id': 1}) + GetNodes({'node_id': 2}) + GetNodes({'node_id': 3})
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
144 <title>PlanetLab shell</title>
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 ≥2.4.</para>
152 usage: plcsh [options]
155 -f CONFIG, --config=CONFIG
156 PLC configuration file
157 -h URL, --url=URL API URL
158 -c CACERT, --cacert=CACERT
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
166 -u USER, --user=USER API user name
167 -p PASSWORD, --password=PASSWORD
169 -r ROLE, --role=ROLE API role
170 -x, --xmlrpc Use XML-RPC interface
171 --help show this help message and exit
174 <para>Specify at least the API URL and your user name:</para>
177 plcsh --url https://www.planet-lab.org/PLCAPI/ -u user@site.edu
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>
185 user@site.edu connected using password authentication
186 Type "system.listMethods()" or "help(method)" for more information.
187 [user@site.edu]>>> AuthCheck()
189 [user@site.edu]>>> GetNodes([121], ['node_id', 'hostname'])
190 [{'node_id': 121, 'hostname': 'planetlab-1.cs.princeton.edu'}]
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
198 <para>To use <command>plcsh</command> programmatically, import
199 the <function>PLC.Shell</function> module:</para>
206 # Default location that the PLCAPI RPM installs the PLC class
207 sys.path.append('/usr/share/plc_api')
209 # Initialize shell environment. Shell() will define all PLCAPI methods
210 # in the specified namespace (specifying globals() will define them
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")
218 # Both are equivalent
219 nodes = GetNodes([121], ['node_id', 'hostname'])
220 nodes = plc.GetNodes([121], ['node_id', 'hostname'])
225 <chapter id="Methods">
226 <title>PlanetLab API Methods</title>
234 <!-- LocalWords: PlanetLab API PLCAPI RPC HTTPS listMethods methodSignature
236 <!-- LocalWords: methodHelp multicall AuthMethod GetSession GnuPG Username GPG
238 <!-- LocalWords: AuthString AddPersonKey AddPeer UpdatePeer gpg