PlanetLab Central API Documentation

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.

1.1. 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.
AuthMethod session
session Session key
Password authentication.
AuthMethod password
Username Username, typically an e-mail address
AuthString Authentication 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.
AuthMethod gpg
name Peer or user name
signature GnuPG signature of the canonicalized XML-RPC representation of the rest of the arguments to the call.
Anonymous authentication.
AuthMethod anonymous

1.2. 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 Section 1.1, “Authentication”).

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

Filters support a number of special features:

Filters support negation. A field starting with the ~ character means negation. Example
```
filter = { '~peer_id' : None } 
```
Filters support greater than or less than operators. A field starting with < [ ] or > means lower than or greater than. < > uses strict comparison while [ ] is for using <= or >= instead. Example
```
filter = { ']node_id' : 2305 }    # node_id  >= 2305
filter = { '>node_id' : 2305 }    # node_id > 2305
```
Filters support wildcard searches. A (string) value containing either a * or a % character is treated as a (sql) pattern; * are replaced with % that is the SQL wildcard character. Example:
```
filter = { 'hostname' : '*.jp' }
```

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

1.5. Interfaces

PlanetLab's PLC API is actually the composition of three distinct interfaces:

Registry Interface: Record and retrive info about objects.
Management Interface: Configure/reboot components and learn their status.
Slice Interface: Provision and control slices/slivers.

This document is organized around these three interfaces.

In principle, each individual PlanetLab node, through its Node Manager (NM), exports the slice and management interfaces. Currently, the NM exports only the sliver-related calls defined by the slice interface. Eventually, the sliver-related calls and the slice-wide calls exported by the slice interface will be unified, such that PLC and each NM will support the same set of slice-related calls.

Each of these three interfaces is divided into a Public subset (calls exported to a wide-range of principals) and an Admin subset (calls available only to the PlanetLab support team). In principle, alternative implementations of PLC would need only support the Public calls to be to interoperate (federate) with PlanetLab; the Admin calls could change to meet the operational needs of any given PlanetLab deployment.

Chapter 2. Registry Interface

Table of Contents

2.1. Public

2.1.1. Addresses

2.1.1.1. AddSiteAddress
2.1.1.2. DeleteAddress
2.1.1.3. GetAddresses
2.1.1.4. UpdateAddress

2.1.2. Slices

2.1.2.1. AddSlice
2.1.2.2. DeleteSlice
2.1.2.3. GetSlices
2.1.2.4. UpdateSlice

2.1.3. Keys

2.1.3.1. AddPersonKey
2.1.3.2. DeleteKey
2.1.3.3. GetKeys
2.1.3.4. UpdateKey

2.1.4. People

2.1.4.1. AddPerson
2.1.4.2. DeletePerson
2.1.4.3. GetPersons
2.1.4.4. UpdatePerson

2.1.5. Sites

2.1.5.1. AddSite
2.1.5.2. DeleteSite
2.1.5.3. GetSites
2.1.5.4. UpdateSite

2.1.6. Nodes

2.1.6.1. AddNode
2.1.6.2. DeleteNode
2.1.6.3. GetNodes
2.1.6.4. UpdateNode

2.2. Admin

2.2.1. Keys

2.2.1.1. AddKeyType
2.2.1.2. DeleteKeyType
2.2.1.3. GetKeyTypes
2.2.1.4. BlacklistKey

2.2.2. Addresses

2.2.2.1. AddAddressType
2.2.2.2. DeleteAddressType
2.2.2.3. GetAddressTypes
2.2.2.4. UpdateAddressType
2.2.2.5. AddAddressTypeToAddress
2.2.2.6. DeleteAddressTypeFromAddress

2.2.3. Roles

2.2.3.1. AddRole
2.2.3.2. DeleteRole
2.2.3.3. GetRoles

2.2.4. People

2.2.4.1. VerifyPerson
2.2.4.2. NotifyPersons
2.2.4.3. ResetPassword

2.1. Public

2.1.1. Addresses

2.1.1.1. AddSiteAddress

Prototype:

AddSiteAddress (auth, site_id_or_login_base, address_fields)

Description:

Adds a new address to a site. Fields specified in address_fields are used; some are not optional.
PIs may only add addresses to their own sites.
Returns the new address_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin, pi

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
site_id_or_login_base : int or string
- int, Site identifier
- string, Site slice prefix
address_fields : struct
- city : string, City
- country : string, Country
- line3 : string, Address line 3
- line2 : string, Address line 2
- line1 : string, Address line 1
- state : string, State or province
- postalcode : string, Postal code

Returns:

int, New address_id (> 0) if successful

2.1.1.2. DeleteAddress

Prototype:

DeleteAddress (auth, address_id)

Description:

Deletes an address.
PIs may only delete addresses from their own sites.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
address_id : int, Address identifier

Returns:

int, 1 if successful

2.1.1.3. GetAddresses

Prototype:

GetAddresses (auth, address_filter, return_fields)

Description:

Returns an array of structs containing details about addresses. If address_filter is specified and is an array of address identifiers, or a struct of address attributes, only addresses matching the filter will be returned. If return_fields is specified, only the specified details will be returned.

Allowed Roles:

admin, pi, user, tech, node

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
address_filter : array of int or struct
- array of int, Address identifier
- struct, Attribute filter
  - city : string or array of string
    string, City
    array of string, City
  - address_id : int or array of int
    int, Address identifier
    array of int, Address identifier
  - country : string or array of string
    string, Country
    array of string, Country
  - line3 : string or array of string
    string, Address line 3
    array of string, Address line 3
  - line2 : string or array of string
    string, Address line 2
    array of string, Address line 2
  - line1 : string or array of string
    string, Address line 1
    array of string, Address line 1
  - state : string or array of string
    string, State or province
    array of string, State or province
  - postalcode : string or array of string
    string, Postal code
    array of string, Postal code
return_fields : array, List of fields to return
- string

Returns:

array of struct
- city : string, City
- address_id : int, Address identifier
- country : string, Country
- line3 : string, Address line 3
- line2 : string, Address line 2
- line1 : string, Address line 1
- address_type_ids : array, Address type identifiers
  - int
- state : string, State or province
- postalcode : string, Postal code
- address_types : array, Address types
  - string

2.1.1.4. UpdateAddress

Prototype:

UpdateAddress (auth, address_id, address_fields)

Description:

Updates the parameters of an existing address with the values in address_fields.
PIs may only update addresses of their own sites.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
address_id : int, Address identifier
address_fields : struct
- city : string, City
- country : string, Country
- line3 : string, Address line 3
- line2 : string, Address line 2
- line1 : string, Address line 1
- state : string, State or province
- postalcode : string, Postal code

Returns:

int, 1 if successful

2.1.2. Slices

2.1.2.1. AddSlice

Prototype:

AddSlice (auth, slice_fields)

Description:

Adds a new slice. Any fields specified in slice_fields are used, otherwise defaults are used.
Valid slice names are lowercase and begin with the login_base (slice prefix) of a valid site, followed by a single underscore. Thereafter, only letters, numbers, or additional underscores may be used.
PIs may only add slices associated with their own sites (i.e., slice prefixes must always be the login_base of one of their sites).
Returns the new slice_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin, pi

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
slice_fields : struct
- url : string, URL further describing this slice
- max_nodes : int, Maximum number of nodes that can be assigned to this slice
- instantiation : string, Slice instantiation state
- name : string, Slice name
- description : string, Slice description

Returns:

int, New slice_id (> 0) if successful

2.1.2.2. DeleteSlice

Prototype:

DeleteSlice (auth, slice_id_or_name)

Description:

Deletes the specified slice.
Users may only delete slices of which they are members. PIs may delete any of the slices at their sites, or any slices of which they are members. Admins may delete any slice.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, user

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
slice_id_or_name : int or string
- int, Slice identifier
- string, Slice name

Returns:

int, 1 if successful

2.1.2.3. GetSlices

Prototype:

GetSlices (auth, slice_filter, return_fields)

Description:

Returns an array of structs containing details about slices. If slice_filter is specified and is an array of slice identifiers or slice names, or a struct of slice attributes, only slices matching the filter will be returned. If return_fields is specified, only the specified details will be returned.
Users may only query slices of which they are members. PIs may query any of the slices at their sites. Admins and nodes may query any slice. If a slice that cannot be queried is specified in slice_filter, details about that slice will not be returned.

Allowed Roles:

admin, pi, user, node

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
slice_filter : array of int or string or string or int or struct
- array of int or string
  - int, Slice identifier
  - string, Slice name
- string, name
- int, slice_id
- struct, Attribute filter
  - creator_person_id : int or array of int
    int, Identifier of the account that created this slice
    array of int, Identifier of the account that created this slice
  - instantiation : string or array of string
    string, Slice instantiation state
    array of string, Slice instantiation state
  - name : string or array of string
    string, Slice name
    array of string, Slice name
  - slice_id : int or array of int
    int, Slice identifier
    array of int, Slice identifier
  - created : int or array of int
    int, Date and time when slice was created, in seconds since UNIX epoch
    array of int, Date and time when slice was created, in seconds since UNIX epoch
  - url : string or array of string
    string, URL further describing this slice
    array of string, URL further describing this slice
  - max_nodes : int or array of int
    int, Maximum number of nodes that can be assigned to this slice
    array of int, Maximum number of nodes that can be assigned to this slice
  - expires : int or array of int
    int, Date and time when slice expires, in seconds since UNIX epoch
    array of int, Date and time when slice expires, in seconds since UNIX epoch
  - site_id : int or array of int
    int, Identifier of the site to which this slice belongs
    array of int, Identifier of the site to which this slice belongs
  - peer_slice_id : int or array of int
    int, Foreign slice identifier at peer
    array of int, Foreign slice identifier at peer
  - peer_id : int or array of int
    int, Peer to which this slice belongs
    array of int, Peer to which this slice belongs
  - description : string or array of string
    string, Slice description
    array of string, Slice description
return_fields : array, List of fields to return
- string

Returns:

array of struct
- creator_person_id : int, Identifier of the account that created this slice
- instantiation : string, Slice instantiation state
- slice_attribute_ids : array, List of slice attributes
  - int
- name : string, Slice name
- slice_id : int, Slice identifier
- created : int, Date and time when slice was created, in seconds since UNIX epoch
- url : string, URL further describing this slice
- max_nodes : int, Maximum number of nodes that can be assigned to this slice
- person_ids : array, List of accounts that can use this slice
  - int
- expires : int, Date and time when slice expires, in seconds since UNIX epoch
- site_id : int, Identifier of the site to which this slice belongs
- peer_slice_id : int, Foreign slice identifier at peer
- node_ids : array, List of nodes in this slice
  - int
- peer_id : int, Peer to which this slice belongs
- description : string, Slice description

2.1.2.4. UpdateSlice

Prototype:

UpdateSlice (auth, slice_id_or_name, slice_fields)

Description:

Updates the parameters of an existing slice with the values in slice_fields.
Users may only update slices of which they are members. PIs may update any of the slices at their sites, or any slices of which they are members. Admins may update any slice.
Only PIs and admins may update max_nodes. Slices cannot be renewed (by updating the expires parameter) more than 8 weeks into the future.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, user

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
slice_id_or_name : int or string
- int, Slice identifier
- string, Slice name
slice_fields : struct
- instantiation : string, Slice instantiation state
- description : string, Slice description
- url : string, URL further describing this slice
- max_nodes : int, Maximum number of nodes that can be assigned to this slice
- expires : int, Date and time when slice expires, in seconds since UNIX epoch
- persons : array of int or string
  - int, Person identifier
  - string, Email address
- nodes : array of int or string
  - int, Node identifier
  - string, Fully qualified hostname

Returns:

int, 1 if successful

2.1.3. Keys

2.1.3.1. AddPersonKey

Prototype:

AddPersonKey (auth, person_id_or_email, key_fields)

Description:

Adds a new key to the specified account.
Non-admins can only modify their own keys.
Returns the new key_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin, pi, tech, user

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
person_id_or_email : int or string
- int, User identifier
- string, Primary e-mail address
key_fields : struct
- key_type : string, Key type
- key : string, Key value

Returns:

int, New key_id (> 0) if successful

2.1.3.2. DeleteKey

Prototype:

DeleteKey (auth, key_id)

Description:

Deletes a key.
Non-admins may only delete their own keys.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, tech, user

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
key_id : int, Key identifier

Returns:

int, 1 if successful

2.1.3.3. GetKeys

Prototype:

GetKeys (auth, key_filter, return_fields)

Description:

Returns an array of structs containing details about keys. If key_filter is specified and is an array of key identifiers, or a struct of key attributes, only keys matching the filter will be returned. If return_fields is specified, only the specified details will be returned.
Admin may query all keys. Non-admins may only query their own keys.

Allowed Roles:

admin, pi, user, tech, node

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
key_filter : array of int or struct
- array of int
  - int, Key identifier
- struct, Attribute filter
  - peer_key_id : int or array of int
    int, Foreign key identifier at peer
    array of int, Foreign key identifier at peer
  - key_type : string or array of string
    string, Key type
    array of string, Key type
  - key : string or array of string
    string, Key value
    array of string, Key value
  - person_id : int or array of int
    int, User to which this key belongs
    array of int, User to which this key belongs
  - key_id : int or array of int
    int, Key identifier
    array of int, Key identifier
  - peer_id : int or array of int
    int, Peer to which this key belongs
    array of int, Peer to which this key belongs
return_fields : array, List of fields to return
- string

Returns:

array of struct
- peer_id : int, Peer to which this key belongs
- key_type : string, Key type
- key : string, Key value
- person_id : int, User to which this key belongs
- key_id : int, Key identifier
- peer_key_id : int, Foreign key identifier at peer

2.1.3.4. UpdateKey

Prototype:

UpdateKey (auth, key_id, key_fields)

Description:

Updates the parameters of an existing key with the values in key_fields.
Non-admins may only update their own keys.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, tech, user

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
key_id : int, Key identifier
key_fields : struct
- key_type : string, Key type
- key : string, Key value

Returns:

int, 1 if successful

2.1.4. People

2.1.4.1. AddPerson

Prototype:

AddPerson (auth, person_fields)

Description:

Adds a new account. Any fields specified in person_fields are used, otherwise defaults are used.
Accounts are disabled by default. To enable an account, use UpdatePerson().
Returns the new person_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin, pi

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
person_fields : struct
- bio : string, Biography
- first_name : string, Given name
- last_name : string, Surname
- title : string, Title
- url : string, Home page
- phone : string, Telephone number
- password : string, Account password in crypt() form
- email : string, Primary e-mail address

Returns:

int, New person_id (> 0) if successful

2.1.4.2. DeletePerson

Prototype:

DeletePerson (auth, person_id_or_email)

Description:

Mark an existing account as deleted.
Users and techs can only delete themselves. PIs can only delete themselves and other non-PIs at their sites. ins can delete anyone.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, user, tech

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
person_id_or_email : int or string
- int, User identifier
- string, Primary e-mail address

Returns:

int, 1 if successful

2.1.4.3. GetPersons

Prototype:

GetPersons (auth, person_filter, return_fields)

Description:

Returns an array of structs containing details about users. If person_filter is specified and is an array of user identifiers or usernames, or a struct of user attributes, only users matching the filter will be returned. If return_fields is specified, only the specified details will be returned.
Users and techs may only retrieve details about themselves. PIs may retrieve details about themselves and others at their sites. Admins and nodes may retrieve details about all accounts.

Allowed Roles:

admin, pi, user, tech, node

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
person_filter : array of int or string or string or int or struct
- array of int or string
  - int, User identifier
  - string, Primary e-mail address
- string, email
- int, person_id
- struct, Attribute filter
  - bio : string or array of string
    string, Biography
    array of string, Biography
  - first_name : string or array of string
    string, Given name
    array of string, Given name
  - last_name : string or array of string
    string, Surname
    array of string, Surname
  - last_updated : int or array of int
    int, Date and time of last update
    array of int, Date and time of last update
  - title : string or array of string
    string, Title
    array of string, Title
  - url : string or array of string
    string, Home page
    array of string, Home page
  - verification_key : string or array of string
    string, Reset password key
    array of string, Reset password key
  - enabled : boolean or array of boolean
    boolean, Has been enabled
    array of boolean, Has been enabled
  - phone : string or array of string
    string, Telephone number
    array of string, Telephone number
  - peer_person_id : int or array of int
    int, Foreign user identifier at peer
    array of int, Foreign user identifier at peer
  - password : string or array of string
    string, Account password in crypt() form
    array of string, Account password in crypt() form
  - person_id : int or array of int
    int, User identifier
    array of int, User identifier
  - date_created : int or array of int
    int, Date and time when account was created
    array of int, Date and time when account was created
  - peer_id : int or array of int
    int, Peer to which this user belongs
    array of int, Peer to which this user belongs
  - verification_expires : int or array of int
    int, Date and time when verification_key expires
    array of int, Date and time when verification_key expires
  - email : string or array of string
    string, Primary e-mail address
    array of string, Primary e-mail address
return_fields : array, List of fields to return
- string

Returns:

array of struct
- bio : string, Biography
- first_name : string, Given name
- last_name : string, Surname
- last_updated : int, Date and time of last update
- roles : array, List of roles
  - string
- title : string, Title
- url : string, Home page
- key_ids : array, List of key identifiers
  - int
- enabled : boolean, Has been enabled
- slice_ids : array, List of slice identifiers
  - int
- phone : string, Telephone number
- peer_person_id : int, Foreign user identifier at peer
- role_ids : array, List of role identifiers
  - int
- person_id : int, User identifier
- date_created : int, Date and time when account was created
- site_ids : array, List of site identifiers
  - int
- peer_id : int, Peer to which this user belongs
- email : string, Primary e-mail address

2.1.4.4. UpdatePerson

Prototype:

UpdatePerson (auth, person_id_or_email, person_fields)

Description:

Updates a person. Only the fields specified in person_fields are updated, all other fields are left untouched.
Users and techs can only update themselves. PIs can only update themselves and other non-PIs at their sites.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, user, tech

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
person_id_or_email : int or string
- int, User identifier
- string, Primary e-mail address
person_fields : struct
- bio : string, Biography
- first_name : string, Given name
- last_name : string, Surname
- keys : array of int or struct
  - int, Key identifier
  - struct, Attribute filter
    peer_key_id : int or array of int
    int, Foreign key identifier at peer
    array of int, Foreign key identifier at peer
    key_type : string or array of string
    string, Key type
    array of string, Key type
    key : string or array of string
    string, Key value
    array of string, Key value
    person_id : int or array of int
    int, User to which this key belongs
    array of int, User to which this key belongs
    key_id : int or array of int
    int, Key identifier
    array of int, Key identifier
    peer_id : int or array of int
    int, Peer to which this key belongs
    array of int, Peer to which this key belongs
- roles : array of int or string
  - int, Role identifier
  - string, Role name
- title : string, Title
- url : string, Home page
- slices : array of int or string
  - int, Slice identifier
  - string, Slice name
- enabled : boolean, Has been enabled
- sites : array of int or string
  - int, Site identifier
  - string, Site name
- phone : string, Telephone number
- password : string, Account password in crypt() form
- email : string, Primary e-mail address

Returns:

int, 1 if successful

2.1.5. Sites

2.1.5.1. AddSite

Prototype:

AddSite (auth, site_fields)

Description:

Adds a new site, and creates a node group for that site. Any fields specified in site_fields are used, otherwise defaults are used.
Returns the new site_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
site_fields : struct
- name : string, Full site name
- url : string, URL of a page that describes the site
- enabled : boolean, Has been enabled
- longitude : double, Decimal longitude of the site
- latitude : double, Decimal latitude of the site
- max_slices : int, Maximum number of slices that the site is able to create
- login_base : string, Site slice prefix
- max_slivers : int, Maximum number of slivers that the site is able to create
- is_public : boolean, Publicly viewable site
- abbreviated_name : string, Abbreviated site name

Returns:

int, New site_id (> 0) if successful

2.1.5.2. DeleteSite

Prototype:

DeleteSite (auth, site_id_or_login_base)

Description:

Mark an existing site as deleted. The accounts of people who are not members of at least one other non-deleted site will also be marked as deleted. Nodes, PCUs, and slices associated with the site will be deleted.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
site_id_or_login_base : int or string
- int, Site identifier
- string, Site slice prefix

Returns:

int, 1 if successful

2.1.5.3. GetSites

Prototype:

GetSites (auth, site_filter, return_fields)

Description:

Returns an array of structs containing details about sites. If site_filter is specified and is an array of site identifiers or hostnames, or a struct of site attributes, only sites matching the filter will be returned. If return_fields is specified, only the specified details will be returned.

Allowed Roles:

admin, pi, user, tech, node, anonymous

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
site_filter : array of int or string or string or int or struct
- array of int or string
  - int, Site identifier
  - string, Site slice prefix
- string, login_base
- int, site_id
- struct, Attribute filter
  - last_updated : int or array of int
    int, Date and time when site entry was last updated, in seconds since UNIX epoch
    array of int, Date and time when site entry was last updated, in seconds since UNIX epoch
  - name : string or array of string
    string, Full site name
    array of string, Full site name
  - url : string or array of string
    string, URL of a page that describes the site
    array of string, URL of a page that describes the site
  - site_id : int or array of int
    int, Site identifier
    array of int, Site identifier
  - enabled : boolean or array of boolean
    boolean, Has been enabled
    array of boolean, Has been enabled
  - longitude : double or array of double
    double, Decimal longitude of the site
    array of double, Decimal longitude of the site
  - latitude : double or array of double
    double, Decimal latitude of the site
    array of double, Decimal latitude of the site
  - max_slices : int or array of int
    int, Maximum number of slices that the site is able to create
    array of int, Maximum number of slices that the site is able to create
  - login_base : string or array of string
    string, Site slice prefix
    array of string, Site slice prefix
  - ext_consortium_id : int or array of int
    int, external consortium id
    array of int, external consortium id
  - is_public : boolean or array of boolean
    boolean, Publicly viewable site
    array of boolean, Publicly viewable site
  - max_slivers : int or array of int
    int, Maximum number of slivers that the site is able to create
    array of int, Maximum number of slivers that the site is able to create
  - date_created : int or array of int
    int, Date and time when site entry was created, in seconds since UNIX epoch
    array of int, Date and time when site entry was created, in seconds since UNIX epoch
  - peer_site_id : int or array of int
    int, Foreign site identifier at peer
    array of int, Foreign site identifier at peer
  - peer_id : int or array of int
    int, Peer to which this site belongs
    array of int, Peer to which this site belongs
  - abbreviated_name : string or array of string
    string, Abbreviated site name
    array of string, Abbreviated site name
return_fields : array, List of fields to return
- string

Returns:

array of struct
- address_ids : array, List of address identifiers
  - int
- pcu_ids : array, List of PCU identifiers
  - int
- last_updated : int, Date and time when site entry was last updated, in seconds since UNIX epoch
- name : string, Full site name
- node_ids : array, List of site node identifiers
  - int
- url : string, URL of a page that describes the site
- enabled : boolean, Has been enabled
- person_ids : array, List of account identifiers
  - int
- site_id : int, Site identifier
- longitude : double, Decimal longitude of the site
- slice_ids : array, List of slice identifiers
  - int
- max_slivers : int, Maximum number of slivers that the site is able to create
- max_slices : int, Maximum number of slices that the site is able to create
- login_base : string, Site slice prefix
- ext_consortium_id : int, external consortium id
- date_created : int, Date and time when site entry was created, in seconds since UNIX epoch
- latitude : double, Decimal latitude of the site
- is_public : boolean, Publicly viewable site
- peer_site_id : int, Foreign site identifier at peer
- peer_id : int, Peer to which this site belongs
- abbreviated_name : string, Abbreviated site name

2.1.5.4. UpdateSite

Prototype:

UpdateSite (auth, site_id_or_login_base, site_fields)

Description:

Updates a site. Only the fields specified in update_fields are updated, all other fields are left untouched.
PIs can only update sites they are a member of. Only admins can update max_slices, max_slivers, and login_base.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
site_id_or_login_base : int or string
- int, Site identifier
- string, Site slice prefix
site_fields : struct
- name : string, Full site name
- persons : array of int or string
  - int, Person identifier
  - string, Email address
- url : string, URL of a page that describes the site
- enabled : boolean, Has been enabled
- longitude : double, Decimal longitude of the site
- latitude : double, Decimal latitude of the site
- max_slices : int, Maximum number of slices that the site is able to create
- login_base : string, Site slice prefix
- ext_consortium_id : int, external consortium id
- max_slivers : int, Maximum number of slivers that the site is able to create
- is_public : boolean, Publicly viewable site
- abbreviated_name : string, Abbreviated site name
- addresses : array of int or struct
  - int, Address identifer
  - struct, Attribute filter
    city : string or array of string
    string, City
    array of string, City
    address_id : int or array of int
    int, Address identifier
    array of int, Address identifier
    country : string or array of string
    string, Country
    array of string, Country
    line3 : string or array of string
    string, Address line 3
    array of string, Address line 3
    line2 : string or array of string
    string, Address line 2
    array of string, Address line 2
    line1 : string or array of string
    string, Address line 1
    array of string, Address line 1
    state : string or array of string
    string, State or province
    array of string, State or province
    postalcode : string or array of string
    string, Postal code
    array of string, Postal code

Returns:

int, 1 if successful

2.1.6. Nodes

2.1.6.1. AddNode

Prototype:

AddNode (auth, site_id_or_login_base, node_fields)

Description:

Adds a new node. Any values specified in node_fields are used, otherwise defaults are used.
PIs and techs may only add nodes to their own sites. Admins may add nodes to any site.
Returns the new node_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin, pi, tech

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
site_id_or_login_base : int or string
- int, Site identifier
- string, Site slice prefix
node_fields : struct
- boot_state : string, Boot state
- model : string, Make and model of the actual machine
- hostname : string, Fully qualified hostname
- version : string, Apparent Boot CD version

Returns:

int, New node_id (> 0) if successful

2.1.6.2. DeleteNode

Prototype:

DeleteNode (auth, node_id_or_hostname)

Description:

Mark an existing node as deleted.
PIs and techs may only delete nodes at their own sites. ins may delete nodes at any site.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, tech

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
node_id_or_hostname : int or string
- int, Node identifier
- string, Fully qualified hostname

Returns:

int, 1 if successful

2.1.6.3. GetNodes

Prototype:

GetNodes (auth, node_filter, return_fields)

Description:

Returns an array of structs containing details about nodes. If node_filter is specified and is an array of node identifiers or hostnames, or a struct of node attributes, only nodes matching the filter will be returned. If return_fields is specified, only the specified details will be returned.
Some fields may only be viewed by admins.

Allowed Roles:

admin, pi, user, tech, node, anonymous

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
node_filter : array of int or string or string or int or struct
- array of int or string
  - int, Node identifier
  - string, Fully qualified hostname
- string, hostname
- int, node_id
- struct, Attribute filter
  - key : string or array of string
    string, (Admin only) Node key
    array of string, (Admin only) Node key
  - node_id : int or array of int
    int, Node identifier
    array of int, Node identifier
  - last_updated : int or array of int
    int, Date and time when node entry was created
    array of int, Date and time when node entry was created
  - last_contact : int or array of int
    int, Date and time when node last contacted plc
    array of int, Date and time when node last contacted plc
  - boot_state : string or array of string
    string, Boot state
    array of string, Boot state
  - peer_node_id : int or array of int
    int, Foreign node identifier at peer
    array of int, Foreign node identifier at peer
  - hostname : string or array of string
    string, Fully qualified hostname
    array of string, Fully qualified hostname
  - site_id : int or array of int
    int, Site at which this node is located
    array of int, Site at which this node is located
  - boot_nonce : string or array of string
    string, (Admin only) Random value generated by the node at last boot
    array of string, (Admin only) Random value generated by the node at last boot
  - session : string or array of string
    string, (Admin only) Node session value
    array of string, (Admin only) Node session value
  - version : string or array of string
    string, Apparent Boot CD version
    array of string, Apparent Boot CD version
  - date_created : int or array of int
    int, Date and time when node entry was created
    array of int, Date and time when node entry was created
  - model : string or array of string
    string, Make and model of the actual machine
    array of string, Make and model of the actual machine
  - peer_id : int or array of int
    int, Peer to which this node belongs
    array of int, Peer to which this node belongs
  - ssh_rsa_key : string or array of string
    string, Last known SSH host key
    array of string, Last known SSH host key
return_fields : array, List of fields to return
- string

Returns:

array of struct
- last_updated : int, Date and time when node entry was created
- boot_state : string, Boot state
- site_id : int, Site at which this node is located
- pcu_ids : array, List of PCUs that control this node
  - int
- session : string, (Admin only) Node session value
- ssh_rsa_key : string, Last known SSH host key
- last_contact : int, Date and time when node last contacted plc
- peer_node_id : int, Foreign node identifier at peer
- hostname : string, Fully qualified hostname
- slice_ids : array, List of slices on this node
  - int
- version : string, Apparent Boot CD version
- peer_id : int, Peer to which this node belongs
- node_id : int, Node identifier
- key : string, (Admin only) Node key
- conf_file_ids : array, List of configuration files specific to this node
  - int
- nodegroup_ids : array, List of node groups that this node is in
  - int
- slice_ids_whitelist : array, List of slices allowed on this node
  - int
- nodenetwork_ids : array, List of network interfaces that this node has
  - int
- boot_nonce : string, (Admin only) Random value generated by the node at last boot
- date_created : int, Date and time when node entry was created
- model : string, Make and model of the actual machine
- ports : array, List of PCU ports that this node is connected to
  - int

2.1.6.4. UpdateNode

Prototype:

UpdateNode (auth, node_id_or_hostname, node_fields)

Description:

Updates a node. Only the fields specified in node_fields are updated, all other fields are left untouched.
PIs and techs can update only the nodes at their sites. Only admins can update the key, session, and boot_nonce fields.
Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, tech

Parameters:

auth : struct, API authentication structure
- AuthMethod : string, Authentication method to use
node_id_or_hostname : int or string
- int, Node identifier
- string, Fully qualified hostname
node_fields : struct
- version : string, Apparent Boot CD version
- nodegroups : array of int or string
  - int, NodeGroup identifier
  - string, NodeGroup name
- slices : array of int or string
  - int, Slice identifier
  - string, Slice name
- boot_state : string, Boot state
- hostname : string, Fully qualified hostname
- conf_files : array of int, ConfFile identifier
- boot_nonce : string, (Admin only) Random value generated by the node at last boot
- session : string, (Admin only) Node session value
- key : string, (Admin only) Node key
- model : string, Make and model of the actual machine
- nodenetworks : array of int or struct
  - int, NodeNetwork identifier
  - struct, Attribute filter
    nodenetwork_id : int or array of int
    int, Node interface identifier
    array of int, Node interface identifier
    network : string or array of string
    string, Subnet address
    array of string, Subnet address
    is_primary : boolean or array of boolean
    boolean, Is the primary interface for this node
    array of boolean, Is the primary interface for this node
    dns1 : string or array of string
    string, IP address of primary DNS server
    array of string, IP address of primary DNS server
    hostname : string or array of string
    string, (Optional) Hostname
    array of string, (Optional) Hostname
    mac : string or array of string
    string, MAC address
    array of string

PlanetLab

Search