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

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.

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

2.1. AddAddressType

Prototype:

AddAddressType (auth, address_type_fields)

Description:

Adds a new address type. Fields specified in address_type_fields are used.

Returns the new address_type_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• address_type_fields : struct

  • name : string, Address type

  • description : string, Address type description

Returns:

• int, New address_type_id (> 0) if successful

2.2. AddAddressTypeToAddress

Prototype:

AddAddressTypeToAddress (auth, address_type_id_or_name, address_id)

Description:

Adds an address type to the specified address.

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_type_id_or_name : int or string

  • int, Address type identifier

  • string, Address type

• address_id : int, Address identifier

Returns:

• int, 1 if successful

2.3. AddBootState

Prototype:

AddBootState (auth, name)

Description:

Adds a new node boot state.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Boot state

Returns:

• int, 1 if successful

2.4. AddConfFile

Prototype:

AddConfFile (auth, conf_file_fields)

Description:

Adds a new node configuration file. Any fields specified in conf_file_fields are used, otherwise defaults are used.

Returns the new conf_file_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• conf_file_fields : struct

  • file_owner : string, chown(1) owner

  • postinstall_cmd : string, Shell command to execute after installing

  • error_cmd : string, Shell command to execute if any error occurs

  • preinstall_cmd : string, Shell command to execute prior to installing

  • dest : string, Absolute path where file should be installed

  • ignore_cmd_errors : boolean, Install file anyway even if an error occurs

  • enabled : boolean, Configuration file is active

  • file_permissions : string, chmod(1) permissions

  • source : string, Relative path on the boot server where file can be downloaded

  • always_update : boolean, Always attempt to install file even if unchanged

  • file_group : string, chgrp(1) owner

Returns:

• int, New conf_file_id (> 0) if successful

2.5. AddConfFileToNodeGroup

Prototype:

AddConfFileToNodeGroup (auth, conf_file_id, nodegroup_id_or_name)

Description:

Adds a configuration file to the specified node group. If the node group is already linked to the configuration file, no errors are returned.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• conf_file_id : int, Configuration file identifier

• nodegroup_id_or_name : int or string

  • int, Node group identifier

  • string, Node group name

Returns:

• int, 1 if successful

2.6. AddConfFileToNode

Prototype:

AddConfFileToNode (auth, conf_file_id, node_id_or_hostname)

Description:

Adds a configuration file to the specified node. If the node is already linked to the configuration file, no errors are returned.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• conf_file_id : int, Configuration file identifier

• node_id_or_hostname : int or string

  • int, Node identifier

  • string, Fully qualified hostname

Returns:

• int, 1 if successful

2.7. AddKeyType

Prototype:

AddKeyType (auth, name)

Description:

Adds a new key type.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Key type

Returns:

• int, 1 if successful

2.8. AddMessage

Prototype:

AddMessage (auth, message_fields)

Description:

Adds a new message template. Any values specified in message_fields are used, otherwise defaults are used.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• message_fields : struct

  • enabled : boolean, Message is enabled

  • message_id : string, Message identifier

  • template : string, Message template

  • subject : string, Message summary

Returns:

• int, 1 if successful

2.9. AddNetworkMethod

Prototype:

AddNetworkMethod (auth, name)

Description:

Adds a new network method.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Network method

Returns:

• int, 1 if successful

2.10. AddNetworkType

Prototype:

AddNetworkType (auth, name)

Description:

Adds a new network type.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Network type

Returns:

• int, 1 if successful

2.11. AddNodeGroup

Prototype:

AddNodeGroup (auth, nodegroup_fields)

Description:

Adds a new node group. Any values specified in nodegroup_fields are used, otherwise defaults are used.

Returns the new nodegroup_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• nodegroup_fields : struct

  • name : string, Node group name

  • description : string, Node group description

Returns:

• int, New nodegroup_id (> 0) if successful

2.12. AddNodeNetwork

Prototype:

AddNodeNetwork (auth, node_id_or_hostname, nodenetwork_fields)

Description:

Adds a new network for a node. Any values specified in nodenetwork_fields are used, otherwise defaults are used. Acceptable values for method may be retrieved via GetNetworkMethods. Acceptable values for type may be retrieved via GetNetworkTypes.

If type is static, ip, gateway, network, broadcast, netmask, and dns1 must all be specified in nodenetwork_fields. If type is dhcp, these parameters, even if specified, are ignored.

PIs and techs may only add networks to their own nodes. Admins may add networks to any node.

Returns the new nodenetwork_id (> 0) 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

• nodenetwork_fields : struct

  • network : string, Subnet address

  • is_primary : boolean, Is the primary interface for this node

  • dns1 : string, IP address of primary DNS server

  • hostname : string, (Optional) Hostname

  • mac : string, MAC address

  • bwlimit : int, Bandwidth limit

  • broadcast : string, Network broadcast address

  • method : string, Addressing method (e.g., 'static' or 'dhcp')

  • netmask : string, Subnet mask

  • dns2 : string, IP address of secondary DNS server

  • ip : string, IP address

  • type : string, Address type (e.g., 'ipv4')

  • gateway : string, IP address of primary gateway

Returns:

• int, New nodenetwork_id (> 0) if successful

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

  • version : string, Apparent Boot CD version

  • hostname : string, Fully qualified hostname

Returns:

• int, New node_id (> 0) if successful

2.14. AddNodeToNodeGroup

Prototype:

AddNodeToNodeGroup (auth, node_id_or_hostname, nodegroup_id_or_name)

Description:

Add a node to the specified node group. If the node is already a member of the nodegroup, no errors are returned.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

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

• nodegroup_id_or_name : int or string

  • int, Node group identifier

  • string, Node group name

Returns:

• int, 1 if successful

2.15. AddNodeToPCU

Prototype:

AddNodeToPCU (auth, node_id_or_hostname, pcu_id, port)

Description:

Adds a node to a port on a PCU. Faults if the node has already been added to the PCU or if the port is already in use.

Non-admins may only update PCUs at their sites.

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

• pcu_id : int, PCU identifier

• port : int, PCU port number

Returns:

• int, 1 if successful

2.16. AddPCU

Prototype:

AddPCU (auth, site_id_or_login_base, pcu_fields)

Description:

Adds a new power control unit (PCU) to the specified site. Any fields specified in pcu_fields are used, otherwise defaults are used.

PIs and technical contacts may only add PCUs to their own sites.

Returns the new pcu_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

• pcu_fields : struct

  • username : string, PCU username

  • protocol : string, PCU protocol, e.g. ssh, https, telnet

  • ip : string, PCU IP address

  • notes : string, Miscellaneous notes

  • hostname : string, PCU hostname

  • model : string, PCU model string

  • password : string, PCU username

Returns:

• int, New pcu_id (> 0) if successful

2.17. AddPeer

Prototype:

AddPeer (auth, peer_fields)

Description:

Adds a new peer.

Returns the new peer_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• peer_fields : struct

  • key : string, Peer GPG public key

  • cacert : string, Peer SSL public certificate

  • peername : string, Peer name

  • peer_url : string, Peer API URL

Returns:

• int, New peer_id (> 0) if successful

2.18. 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.19. 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.20. AddPersonToSite

Prototype:

AddPersonToSite (auth, person_id_or_email, site_id_or_login_base)

Description:

Adds the specified person to the specified site. If the person is already a member of the site, no errors are returned. Does not change the person's primary site.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

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

• site_id_or_login_base : int or string

  • int, Site identifier

  • string, Site slice prefix

Returns:

• int, 1 if successful

2.21. AddPersonToSlice

Prototype:

AddPersonToSlice (auth, person_id_or_email, slice_id_or_name)

Description:

Adds the specified person to the specified slice. If the person is already a member of the slice, no errors are returned.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi

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

• slice_id_or_name : int or string

  • int, Slice identifier

  • string, Slice name

Returns:

• int, 1 if successful

2.22. AddRole

Prototype:

AddRole (auth, role_id, name)

Description:

Adds a new role.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• role_id : int, Role identifier

• name : string, Role

Returns:

• int, 1 if successful

2.23. AddRoleToPerson

Prototype:

AddRoleToPerson (auth, role_id_or_name, person_id_or_email)

Description:

Grants the specified role to the person.

PIs can only grant the tech and user roles to users and techs at their sites. Admins can grant any role to any user.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• role_id_or_name : int or string

  • int, Role identifier

  • string, Role

• person_id_or_email : int or string

  • int, User identifier

  • string, Primary e-mail address

Returns:

• int, 1 if successful

2.24. 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.25. 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.26. AddSliceAttribute

Prototype:

AddSliceAttribute (auth, slice_id_or_name, attribute_type_id_or_name, value, node_id_or_hostname)

Description:

Sets the specified attribute of the slice (or sliver, if node_id_or_hostname is specified) to the specified value.

Attributes may require the caller to have a particular role in order to be set or changed. Users may only set attributes of slices or slivers of which they are members. PIs may only set attributes of slices or slivers at their sites, or of which they are members. Admins may set attributes of any slice or sliver.

Returns the new slice_attribute_id (> 0) 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 attribute type name

• attribute_type_id_or_name : int or string

  • int, Slice attribute type identifier

  • string, Slice attribute type name

• value : string, Slice attribute value

• node_id_or_hostname : int or string

  • int, Node identifier

  • string, Fully qualified hostname

Returns:

• int, New slice_attribute_id (> 0) if successful

2.27. AddSliceAttributeType

Prototype:

AddSliceAttributeType (auth, attribute_type_fields)

Description:

Adds a new type of slice attribute. Any fields specified in attribute_type_fields are used, otherwise defaults are used.

Returns the new attribute_type_id (> 0) if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• attribute_type_fields : struct

  • min_role_id : int, Minimum (least powerful) role that can set or change this attribute

  • name : string, Slice attribute type name

  • description : string, Slice attribute type description

Returns:

• int, New attribute_id (> 0) if successful

2.28. AddSliceInstantiation

Prototype:

AddSliceInstantiation (auth, name)

Description:

Adds a new slice instantiation state.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Slice instantiation state

Returns:

• int, 1 if successful

2.29. 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.30. AddSliceToNodes

Prototype:

AddSliceToNodes (auth, slice_id_or_name, node_id_or_hostname_list)

Description:

Adds the specified slice to the specified nodes. Nodes may be either local or foreign nodes.

If the slice is already associated with a node, no errors are returned.

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

• node_id_or_hostname_list : array of int or string

  • int, Node identifier

  • string, Fully qualified hostname

Returns:

• int, 1 if successful

2.31. AuthCheck

Prototype:

AuthCheck (auth)

Description:

Returns 1 if the user or node authenticated successfully, faults otherwise.

Allowed Roles:

admin, pi, user, tech, node

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

Returns:

• int, 1 if successful

2.32. BlacklistKey

Prototype:

BlacklistKey (auth, key_id)

Description:

Blacklists a key, disassociating it and all others identical to it from all accounts and preventing it from ever being added again.

WARNING: Identical keys associated with other accounts with also be blacklisted.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• key_id : int, Key identifier

Returns:

• int, 1 if successful

2.33. BootGetNodeDetails

Prototype:

BootGetNodeDetails (auth)

Description:

Returns a set of details about the calling node, including a new node session value.

Allowed Roles:

node

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use, always 'hmac'

  • value : string, HMAC of node key and method call

  • node_id : int, Node identifier

Returns:

• struct

  • boot_state : string, Boot state

  • model : string, Make and model of the actual machine

  • hostname : string, Fully qualified hostname

  • networks : array of struct

    • broadcast : string, Network broadcast address

    • is_primary : boolean, Is the primary interface for this node

    • network : string, Subnet address

    • ip : string, IP address

    • dns1 : string, IP address of primary DNS server

    • hostname : string, (Optional) Hostname

    • netmask : string, Subnet mask

    • gateway : string, IP address of primary gateway

    • nodenetwork_id : int, Node interface identifier

    • mac : string, MAC address

    • node_id : int, Node associated with this interface

    • dns2 : string, IP address of secondary DNS server

    • bwlimit : int, Bandwidth limit

    • type : string, Address type (e.g., 'ipv4')

    • method : string, Addressing method (e.g., 'static' or 'dhcp')

  • session : string, Session key

2.34. BootNotifyOwners

Prototype:

BootNotifyOwners (auth, message_id, include_pis, include_techs, include_support)

Description:

Notify the owners of the node, and/or support about an event that happened on the machine.

Returns 1 if successful.

Allowed Roles:

node

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use, always 'hmac'

  • value : string, HMAC of node key and method call

  • node_id : int, Node identifier

• message_id : string, Message identifier

• include_pis : int, Notify PIs

• include_techs : int, Notify technical contacts

• include_support : int, Notify support

Returns:

• int, 1 if successful

2.35. BootUpdateNode

Prototype:

BootUpdateNode (auth, node_fields)

Description:

Allows the calling node to update its own record. Only the primary network can be updated, and the node IP cannot be changed.

Returns 1 if updated successfully.

Allowed Roles:

node

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use, always 'hmac'

  • value : string, HMAC of node key and method call

  • node_id : int, Node identifier

• node_fields : struct

  • boot_state : string, Boot state

  • primary_network : struct

    • network : string, Subnet address

    • dns2 : string, IP address of secondary DNS server

    • dns1 : string, IP address of primary DNS server

    • netmask : string, Subnet mask

    • method : string, Addressing method (e.g., 'static' or 'dhcp')

    • broadcast : string, Network broadcast address

    • mac : string, MAC address

    • gateway : string, IP address of primary gateway

  • ssh_host_key : string, Last known SSH host key

Returns:

• int, 1 if successful

2.36. 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.37. DeleteAddressTypeFromAddress

Prototype:

DeleteAddressTypeFromAddress (auth, address_type_id_or_name, address_id)

Description:

Deletes an address type from the specified address.

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_type_id_or_name : int or string

  • int, Address type identifier

  • string, Address type

• address_id : int, Address identifier

Returns:

• int, 1 if successful

2.38. DeleteAddressType

Prototype:

DeleteAddressType (auth, address_type_id_or_name)

Description:

Deletes an address type.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• address_type_id_or_name : int or string

  • int, Address type identifier

  • string, Address type

Returns:

• int, 1 if successful

2.39. DeleteBootState

Prototype:

DeleteBootState (auth, name)

Description:

Deletes a node boot state.

WARNING: This will cause the deletion of all nodes in this boot state.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Boot state

Returns:

• int, 1 if successful

2.40. DeleteConfFileFromNodeGroup

Prototype:

DeleteConfFileFromNodeGroup (auth, conf_file_id, nodegroup_id_or_name)

Description:

Deletes a configuration file from the specified nodegroup. If the nodegroup is not linked to the configuration file, no errors are returned.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• conf_file_id : int, Configuration file identifier

• nodegroup_id_or_name : int or string

  • int, Node group identifier

  • string, Node group name

Returns:

• int, 1 if successful

2.41. DeleteConfFileFromNode

Prototype:

DeleteConfFileFromNode (auth, conf_file_id, node_id_or_hostname)

Description:

Deletes a configuration file from the specified node. If the node is not linked to the configuration file, no errors are returned.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• conf_file_id : int, Configuration file identifier

• node_id_or_hostname : int or string

  • int, Node identifier

  • string, Fully qualified hostname

Returns:

• int, 1 if successful

2.42. DeleteConfFile

Prototype:

DeleteConfFile (auth, conf_file_id)

Description:

Returns an array of structs containing details about node configuration files. If conf_file_ids is specified, only the specified configuration files will be queried.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• conf_file_id : int, Configuration file identifier

Returns:

• int, 1 if successful

2.43. 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.44. DeleteKeyType

Prototype:

DeleteKeyType (auth, name)

Description:

Deletes a key type.

WARNING: This will cause the deletion of all keys of this type.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Key type

Returns:

• int, 1 if successful

2.45. DeleteMessage

Prototype:

DeleteMessage (auth, message_id)

Description:

Deletes a message template.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• message_id : string, Message identifier

Returns:

• int, 1 if successful

2.46. DeleteNetworkMethod

Prototype:

DeleteNetworkMethod (auth, name)

Description:

Deletes a network method.

WARNING: This will cause the deletion of all network interfaces that use this method.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Network method

Returns:

• int, 1 if successful

2.47. DeleteNetworkType

Prototype:

DeleteNetworkType (auth, name)

Description:

Deletes a network type.

WARNING: This will cause the deletion of all network interfaces that use this type.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• name : string, Network type

Returns:

• int, 1 if successful

2.48. DeleteNodeFromNodeGroup

Prototype:

DeleteNodeFromNodeGroup (auth, node_id_or_hostname, nodegroup_id_or_name)

Description:

Removes a node from the specified node group.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

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

• nodegroup_id_or_name : int or string

  • int, Node group identifier

  • string, Node group name

Returns:

• int, 1 if successful

2.49. DeleteNodeFromPCU

Prototype:

DeleteNodeFromPCU (auth, node_id_or_hostname, pcu_id)

Description:

Deletes a node from a PCU.

Non-admins may only update PCUs at their sites.

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

• pcu_id : int, PCU identifier

Returns:

• int, 1 if successful

2.50. DeleteNodeGroup

Prototype:

DeleteNodeGroup (auth, node_group_id_or_name)

Description:

Delete an existing Node Group.

ins may delete any node group

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• node_group_id_or_name : int or string

  • int, Node group identifier

  • string, Node group name

Returns:

• int, 1 if successful

2.51. DeleteNodeNetwork

Prototype:

DeleteNodeNetwork (auth, nodenetwork_id)

Description:

Deletes an existing node network interface.

Admins may delete any node network. PIs and techs may only delete node network interfaces associated with nodes at their sites.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, tech

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• nodenetwork_id : int, Node interface identifier

Returns:

• int, 1 if successful

2.52. 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.53. DeletePCU

Prototype:

DeletePCU (auth, pcu_id)

Description:

Deletes a PCU.

Non-admins may only delete PCUs at their sites.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, tech

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• pcu_id : int, PCU identifier

Returns:

• int, 1 if successful

2.54. DeletePeer

Prototype:

DeletePeer (auth, peer_id_or_name)

Description:

Mark an existing peer as deleted. All entities (e.g., slices, keys, nodes, etc.) for which this peer is authoritative will also be deleted or marked as deleted.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• peer_id_or_name : int or string

  • int, Peer identifier

  • string, Peer name

Returns:

• int, 1 if successful

2.55. DeletePersonFromSite

Prototype:

DeletePersonFromSite (auth, person_id_or_email, site_id_or_login_base)

Description:

Removes the specified person from the specified site. If the person is not a member of the specified site, no error is returned.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

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

• site_id_or_login_base : int or string

  • int, Site identifier

  • string, Site slice prefix

Returns:

• int, 1 if successful

2.56. DeletePersonFromSlice

Prototype:

DeletePersonFromSlice (auth, person_id_or_email, slice_id_or_name)

Description:

Deletes the specified person from the specified slice. If the person is not a member of the slice, no errors are returned.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi

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

• slice_id_or_name : int or string

  • int, Slice identifier

  • string, Slice name

Returns:

• int, 1 if successful

2.57. 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.58. DeleteRoleFromPerson

Prototype:

DeleteRoleFromPerson (auth, role_id_or_name, person_id_or_email)

Description:

Deletes the specified role from the person.

PIs can only revoke the tech and user roles from users and techs at their sites. ins can revoke any role from any user.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• role_id_or_name : int or string

  • int, Role identifier

  • string, Role

• person_id_or_email : int or string

  • int, User identifier

  • string, Primary e-mail address

Returns:

• int, 1 if successful

2.59. DeleteRole

Prototype:

DeleteRole (auth, role_id_or_name)

Description:

Deletes a role.

WARNING: This will remove the specified role from all accounts that possess it, and from all node and slice attributes that refer to it.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• role_id_or_name : int or string

  • int, Role identifier

  • string, Role

Returns:

• int, 1 if successful

2.60. DeleteSession

Prototype:

DeleteSession (auth)

Description:

Invalidates the current session.

Returns 1 if successful.

Allowed Roles:

admin, pi, user, tech, node

Parameters:

• auth : struct, API authentication structure

  • session : string, Session key

  • AuthMethod : string, Authentication method to use, always 'session'

Returns:

• int, 1 if successful

2.61. 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.62. DeleteSliceAttribute

Prototype:

DeleteSliceAttribute (auth, slice_attribute_id)

Description:

Deletes the specified slice or sliver attribute.

Attributes may require the caller to have a particular role in order to be deleted. Users may only delete attributes of slices or slivers of which they are members. PIs may only delete attributes of slices or slivers at their sites, or of which they are members. Admins may delete attributes of any slice or sliver.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin, pi, user

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• slice_attribute_id : int, Slice attribute identifier

Returns:

• int, 1 if successful

2.63. DeleteSliceAttributeType

Prototype:

DeleteSliceAttributeType (auth, attribute_type_id_or_name)

Description:

Deletes the specified slice attribute.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• attribute_type_id_or_name : int or string

  • int, Slice attribute type identifier

  • string, Slice attribute type name

Returns:

• int, 1 if successful

2.64. DeleteSliceFromNodes

Prototype:

DeleteSliceFromNodes (auth, slice_id_or_name, node_id_or_hostname_list)

Description:

Deletes the specified slice from the specified nodes. If the slice is not associated with a node, no errors are returned.

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

• node_id_or_hostname_list : array of int or string

  • int, Node identifier

  • string, Fully qualified hostname

Returns:

• int, 1 if successful

2.65. DeleteSliceInstantiation

Prototype:

DeleteSliceInstantiation (auth, instantiation)

Description:

Deletes a slice instantiation state.

WARNING: This will cause the deletion of all slices of this instantiation.

Returns 1 if successful, faults otherwise.

Allowed Roles:

admin

Parameters:

• auth : struct, API authentication structure

  • AuthMethod : string, Authentication method to use

• instantiation : string, Slice instantiation state

Returns:

• int, 1 if successful

2.66. 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.67. 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.68. GetAddressTypes

Prototype:

GetAddressTypes (auth, address_type_filter, return_fields)

Description:

Returns an array of structs containing details about address types. If address_type_filter is specified and is an array of address type identifiers, or a struct of address type attributes, only address types 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_type_filter : array of int or string or struct

  • array of int or string

    • int, Address type identifier

    • string, Address type

  • struct, Attribute filter

    • name : string or array of string

      • string, Address type

      • array of string, Address type

    • address_type_id : int or array of int

      • int, Address type identifier

      • array of int, Address type identifier

    • description : string or array of string

      • string, Address type description

      • array of string, Address type description

• return_fields : array, List of fields to return

  • string

Returns:

• array of struct

  • name : string, Address type

  • address_type_id : int, Address type identifier

  • description : string, Address type description

2.69. GetBootStates

Prototype:

GetBootStates (auth)

Description:

Returns an array of all valid node boot states.

Allowed Roles:

admin, pi, user, tech, node

Parameters:

• auth : struct, API authentication struc