]> 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.

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

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 ).

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]}) Would be equivalent queries. Attributes that are themselves arrays (such as interface_ids and slice_ids for nodes) cannot be used in filters. Filters support a few extra features illustrated in the following examples. Pattern Matching GetNodes ( { 'hostname' : '*.fr' } ) Negation GetNodes( { '~peer_id' : None } ) Numeric comparisons GetEvents( { '>time' : 1178531418 } ) GetEvents( { ']event_id' : 2305 } ) Sorting and Clipping GetNodes( { '-SORT' : 'hostname' , '-OFFSET' : 30 , '-LIMIT' : 25 }

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'])

&Methods;