From 974295120b013552c3554cedba6c2ba6746ee614 Mon Sep 17 00:00:00 2001 From: Mark Huang Date: Mon, 19 Feb 2007 17:59:45 +0000 Subject: [PATCH] - add introduction and general discussion --- doc/PLCAPI.xml | 224 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 220 insertions(+), 4 deletions(-) diff --git a/doc/PLCAPI.xml b/doc/PLCAPI.xml index 27cc43d..f778525 100644 --- a/doc/PLCAPI.xml +++ b/doc/PLCAPI.xml @@ -7,12 +7,221 @@ PlanetLab Central API Documentation - - AaronKlingaman - MarkHuang - + + Introduction + + The PlanetLab Central API (PLCAPI) is the interface through + which the PlanetLab Central database should be accessed and + maintained. The API is used by the website, by nodes, by automated + scripts, and by users to access and update information about + users, nodes, sites, slices, and other entities maintained by the + database. + +
+ Authentication + + The API should be accessed via XML-RPC over HTTPS. The API + supports the standard introspection calls system.listMethods, system.methodSignature, + and system.methodHelp, + and the standard batching call system.multicall. With the + exception of these calls, all PLCAPI calls take an + authentication structure as their first argument. All + authentication structures require the specification of + AuthMethod. If the documentation for a + call does not further specify the authentication structure, then + any of (but only) the following authentication structures may be + used: + + + + Session authentication. User sessions are typically + valid for 24 hours. Node sessions are valid until the next + reboot. Obtain a session key with GetSession using another form of + authentication, such as password or GnuPG + authentication. + + + + AuthMethodsession + sessionSession key + + + + + + Password authentication. + + + + AuthMethodpassword + UsernameUsername, typically an e-mail address + AuthStringAuthentication string, typically a password + + + + + + GnuPG authentication. Users may upload a GPG public key + using AddPersonKey. Peer + GPG keys should be added with AddPeer or UpdatePeer. + + + + + AuthMethodgpg + namePeer or user name + signatureGnuPG signature of + the canonicalized + XML-RPC + representation of the rest of the arguments to the + call. + + + + + + Anonymous authentication. + + + + AuthMethodanonymous + + + + + +
+ +
+ Roles + + Some functions may only be called by users with certain + roles (see GetRoles), and others + may return different information to different callers depending + on the role(s) of the caller. + + The node and + anonymous roles are pseudo-roles. A function + that allows the node role may be called by + automated scripts running on a node, such as the Boot and Node + Managers. A function that allows the + anonymous role may be called by anyone; an + API authentication structure must still be specified (see ). +
+ +
+ Filters + + Most of the Get functions take a + filter argument. Filters may be arrays of integer (and sometimes + string) identifiers, or a struct representing a filter on the + attributes of the entities being queried. For example, + + +# plcsh code fragment (see below) +GetNodes([1,2,3]) +GetNodes({'node_id': [1,2,3]}) +GetNodes({'node_id': 1}) + GetNodes({'node_id': 2}) + GetNodes({'node_id': 3}) + + + Would all be equivalent queries. Attributes that are + themselves arrays (such as nodenetwork_ids + and slice_ids for nodes) cannot be used in + filters. +
+ +
+ PlanetLab shell + + A command-line program called plcsh + simplifies authentication structure handling, and is useful for + scripting. This program is distributed as a Linux RPM called + PLCAPI and requires Python ≥2.4. + + +usage: plcsh [options] + +options: + -f CONFIG, --config=CONFIG + PLC configuration file + -h URL, --url=URL API URL + -c CACERT, --cacert=CACERT + API SSL certificate + -k INSECURE, --insecure=INSECURE + Do not check SSL certificate + -m METHOD, --method=METHOD + API authentication method + -s SESSION, --session=SESSION + API session key + -u USER, --user=USER API user name + -p PASSWORD, --password=PASSWORD + API password + -r ROLE, --role=ROLE API role + -x, --xmlrpc Use XML-RPC interface + --help show this help message and exit + + + Specify at least the API URL and your user name: + + +plcsh --url https://www.planet-lab.org/PLCAPI/ -u user@site.edu + + + You will be presented with a prompt. From here, you can + invoke API calls and omit the authentication structure, as it will + be filled in automatically. + + +user@site.edu connected using password authentication +Type "system.listMethods()" or "help(method)" for more information. +[user@site.edu]>>> AuthCheck() +1 +[user@site.edu]>>> GetNodes([121], ['node_id', 'hostname']) +[{'node_id': 121, 'hostname': 'planetlab-1.cs.princeton.edu'}] + + + As this program is actually a Python interpreter, you may + create variables, execute for loops, import other packages, etc., + directly on the command line as you would using the regular Python + shell. + + To use plcsh programmatically, import + the PLC.Shell module: + + +#!/usr/bin/python + +import sys + +# Default location that the PLCAPI RPM installs the PLC class +sys.path.append('/usr/share/plc_api') + +# Initialize shell environment. Shell() will define all PLCAPI methods +# in the specified namespace (specifying globals() will define them +# globally). +from PLC.Shell import Shell +plc = Shell(globals(), + url = "https://www.planet-lab.org/PLCAPI/", + user = "user@site.edu", + password = "password") + +# Both are equivalent +nodes = GetNodes([121], ['node_id', 'hostname']) +nodes = plc.GetNodes([121], ['node_id', 'hostname']) + +
+ + PlanetLab API Methods @@ -21,3 +230,10 @@ + + + + -- 2.43.0