JSON RPC API

Serverboards Core API

This is a list of all serverboards calls that the core provides and are accessible via JSON RPC. Each plugin can provide extra calls that will be documented on each module.

This calls are performed via the plugin module at the frontend, using API bindings, or manually via stdio communication and the JSON RPC Protocol.

Module create get list update delete other…
Action action. trigger action. trigger_wait action. get action. ps action. list      
Auth   auth. user   auth. set_password   auth. auth auth. reset_password
Auth Group group. create group. user. add group. perm. add group. get group. list   group. delete group. user. delete group. perm. delete  
Auth Permissions     perm. list      
Auth Token auth. token. create     auth. token. update    
Auth User user. create   user. list user. update    
Core     dir     ping
Dashboard dashboard. create dashboard. get dashboard. list dashboard. update dashboard. delete  
Dashboard Widget dashboard. widget. create dashboard. widget. get dashboard. widget. extract dashboard. widget. list dashboard. widget. update dashboard. widget. delete    
Events event. emit event. subscribe   event. subscriptions   event. unsubscribe  
HTTP            
Issues issues. create issues. get issues. list issues. update    
Logs logs. debug logs. info logs. warning logs. error   logs. list      
Notifications notifications. create notifications. get notifications. config. get notifications. list notifications. config. update    
Plugins     plugin. catalog plugin. component. catalog plugin. ps     plugin. reload plugin. start plugin. stop plugin. kill plugin. alias plugin. call plugin. is_running
Plugin Data   plugin. data. get plugin. data. list plugin. data. items plugin. data. update plugin. data. delete  
Project project. create project. get project. list project. update project. delete  
Rules   rules. get rules. list rules. update rules. delete rules. trigger
Rules v2 rules_v2. create rules_v2. get rules_v2. list rules_v2. update rules_v2. delete  
Services service. create service. get service. list service. update service. attach service. detach service. delete  
Settings   settings. get settings. list settings. update    
User Settings   settings. user. get   settings. user. update    
Query   query. query        

Action

action.get(action_id)

Returns full details of the given action

action.list(filter)

Returns all the action history: past and current

The filter may be:

  • count – Default 100
  • start – Last uuid from previous listing (which is the smallest id number)

action.ps()

Lists all running processes with running info.

action.trigger(action_id, params)

Manually executes an action.

Returns an UUID that can be used for action watching.

Example:

action.trigger("core.actions/ping", { ip: "192.168.1.1" })
// "8f3e8f70-acf4-4b2d-b929-ec8efed82c26"

action.trigger_wait(action_id, params)

Manually executes and action, and waits for response.

This is useful in plugins to perform actions and get the answer.

action.trigger_wait("core.actions/ping", {ip: "192.168.1.1"})
// { response_time: 100 }

Auth

auth.auth({type, ...})

Tries to do login. If succesfull returns a struct with

  • email
  • perms

If not success, returns false.

auth.auth({
  type: "basic",
  username: "test@serverboards.io",
  password: "aaaaaaaa"
})
// returns user data as in auth.user
auth.auth({
  type: "token",
  token: "2b8c390c-12ba-4948-819e-bda8d834c1db"
})
// or false

The ony required parameter is type, all the others depend on the authentication method selected.

auth.reset_password(email)

Initiates the reset password procedure.

auth.set_password(oldpassword, newpassword)

Changes current user password

auth.set_password("oldpassword", "newpassword")

auth.user()

Returns current user

auth.user()

Result:

{
  "is_active": true,
  "first_name": "David",
  "last_name": "Moreno",
  "id": 115,
  "email": "dmoreno@serverboards.io",
  "perms": [
    "auth.modify_self",
    "auth.token.create",
    "auth.manage_groups",
    "auth.modify_any",
    "auth.create_user",
    "auth.info_any_user",
    "auth.modify_groups",
    "auth.modify_self",
    "auth.token.update",
    "plugin"
  ],
  "groups": [
    "admin",
    "user",
    "other"
  ]
}

Auth Group

group.create(name)

Required permissions:
  • group.manage_groups

Adds a new group

group.create("newgroup")

Result:

"ok"

group.delete(name)

Required permissions:
  • group.manage_groups

Deletes a group

group.delete("group")

Result:

"ok"

group.get(group)

Lsits all permissions and users in that group.

group.list

Returns the list of all groups in the system.

group.list()

Result:

[
  "admin",
  "user",
  "developers",
  "external",
  "other"
]

group.perm.add(group, perm)

Adds a permissions to that group.

group.perm.delete(group, perm)

Removes a permission from the group.

group.user.add(group, email)

Adds a user to the group

group.user.delete(group, email)

Removes a user from the group.

Auth Permissions

perm.list()

Returns a list of all the permissions known by the system.

Auth Token

auth.token.create

Creates an access token for current user

auth.token.create()

Result:

"2b8c390c-12ba-4948-819e-bda8d834c1db"

Tokens can be used to authenticate, using:

auth.auth({type:"token", token:[MY-TOKEN]})

auth.token.update(token)

Refreshes the token for another day.

May be called by the frontend to keep it working.

Auth User

user.create(user_struct)

Adds a user.

user.list

Returns a list of users with email, name, is_active and groups.

user.update(email, operations)

User struct is a dict with: {email, name, is_active}

Updates user data, for example {"is_active": false, "name": "new name"}.

Note that there is no user delete, there is only deactivation via is_active: false.

Core

These functions are basic JSON functions that all clients should implement.

dir()

Returns list current available methods

dir()

ping( msg )

Returns the given msg. It can be used to check conectivity and to force the daemon not to timeout for no activity in communications.

Check commands for more information on timeouts.

ping()

Dashboard

Management of the dashboards

dashboard.create({name, project, order})

Required permissions:
  • dashboard.create

Creates a dashboard in the given project.

Returns the new dashboard uuid.

dashboard.delete({uuid})

Required permissions:
  • dashboard.delete

Deletes a given dashboard

dashboard.get({uuid})

Required permissions:
  • dashboard.get

Returns all the related data for the given dashboard.

dashboard.list({project})

Required permissions:
  • dashboard.get

Returns all the dashboards for a given project, with minimal information (name, uuid).

dashboard.update({uuid, name, config, order})

Required permissions:
  • dashboard.update

Updates an attribute of the dashboard

Dashboard Widgets

Management of the dashboard widgets.

dashboard.widget.create(attrs)

Required permissions:
  • dashboard.widget.create

Adds a new widget with the given attributes:

  • config – Internal config of the widget
  • ui – UI configuration, as dashboard position
  • widget – Widget id.
  • dashboard – Add to this dashboard

Returns the widget UUID.

dashboard.widget.get(widget_uuid)

Required permissions:
  • project.get

Gets data from and individual widget.

dashboard.widget.list(project_shortname)

Required permissions:
  • project.get

Lists all widgets of the given project.

dashboard.widget.update(changes)

Required permissions:
  • dashboard.widget.update

Updates any of the given widget attributes. Requires the uuid attribute to reference the proper widget.

Events

Clients can subscribe to an event type, and will be notified when that event happens.

Events can have guards to prevent being sent to clients without the proper permissions.

event.emit(event_type, extra, guards)

Required permissions:
  • event.emit
  • event_type – Type of the event, properly scoped (plugin.type)
    • extra – Extra values required to properly update the status
    • guards – Guard expression to prevent being sent to not allowed clients

The guards can be:

  • A list of user required permissions.
  • A dict with perms and context keys. Perms is the list of required perms, and context is a path describing the context, for example: /serverboard/test.

Example:

// Has a global foo.bar permission
event.emit("foo.bar", {"text":"hello world"}, ["foo.add"] )
// Has a foo.bar permission at /service/FOO
event.emit("foo.bar", {"text":"hello world"}, {
  "context" : "/service/FOO",
  "perms" : ["foo.add"]
})

event.subscribe(event_type)

Subscribes to a event_type. All events that this client is allowed to see on of that type will be emited.

event.subscribe("user.updated")

event.subscriptions()

Returns a list with all the subscriptions.

event.unsubscribe(event_type)

Stop receiving updates on that event_type topic.

event.unsubscribe("user.updated")

HTTP

http.add_port(port) -> uuid

Adds a port mapping to websockets.

It creates a /ws/[uuid] connection point that will be available for 1 minute or one connection. These limitations are to ensure security, as anybody with the UUID could connect to that port. By limiting it in time and connections we ensure a very limited window of attack opportunity.

Issues

issues.create({title, description, aliases}) -> id

Adds an issue with the given title and description.

Aliases is an optional list with known aliases. Aliases may be serverboard/[Serverboard name], rule/[ruleid] or any user value.

issues.get(id)

Gets all the information about an issue by id.

issues.list(filter \\ {})

Required permissions:
  • issues.view

Returns the list of issues that comply with the given filter. It may be ommited.

Filter accepts:

  • project: Only filters at that project
  • return: What to return: count or issues(default)
  • since: Only issues with activity since the given ISO date.
  • start: Resumes a list from the start id
  • count: Maximum count of items to return

If returns the count, returns a dictionary with count and timestamp, where timestamp is the iso date for latest update on the set.

issues.update(id, {type, data})

Type:

  • comment – text
  • set_label – list of labels to set
  • unset_labels – list of labels to unset
  • change_status – new status
  • alias – list of alias to add
  • unalias – list of alias to remove

Logs

log.debug(msg, extra \\ [])

Event.

log.error(msg, extra \\ [])

Event.

extra may contain: file, line, function, to properly log origin.

log.info(msg, extra \\ [])

Event.

log.warning(msg, extra \\ [])

Event.

logs.list(filter)

Returns the history of logs, first the latest, according to filter

Filter options:

  • start – Min id to return, if not present last id
  • count – How many to return, 50 by default
  • until – Max id to return
  • q – Return only items that contain the q string.
  • service – Return only items related to the given service uuid
  • offset – Skip n items.

id is always incrementing, and can be used for paginating: For first page do not set any filter, for following return the minimal id returned on last page, as start, which should be the last id.

If you are looking for log entries since an entry, use this entry id for the until parameter.

It returns a dict with:

  • total – Total number of lines
  • lines – The returned lines in this batch Each entry has:
    • id
    • message
    • timestamp
    • level
    • meta

Notifications

Notifications send messgaes via the user configured channels

notifications.config.get(email)

Returns the notification channels configured by this user

notifications.config.update(email, channel, config, is_active)

notifications.create(email, subject, body, extra)

extra is some extra information that may be used by the channels to adapt to the message, for example, alert level.

notifications.get(id)

Returns the full details of a given notification

notifications.list(filter)

Returns the notifications acording to this filter, which may contain:

  • tags – List of tags that must match
  • count – How many to return. By default 50.
  • start – Start at id X, in decreasing order. This is because the first listing return the most recents notifications.

Plugin Data

This module stores data about a given plugin.

In all calls the plugin id is optional when called from an plugin, as it will be assumed is the calling plugin.

It given, it checks for proper permissions to access such data (access to current plugin is always allowed).

There is no data.add, as updating non existing data creates it.

plugin.data.delete(id, key)

Required permissions:
  • plugins.data
  • plugins.data[pluginid]

Removes permanently a key from the plugin data.

plugin.data.get(id, key) // plugin.data.get(key)

Required permissions:
  • plugins.data
  • plugins.data[pluginid]

Returns the data of the given section

plugins.data.get("serverboards.core.notifications/telegram", "user_to_map")
{
  "dmoreno@serverboards.io": 12312312312
}

As with plugin.data.set the id is optional but checked against the current plugin, if called froma plugin cmd.

plugin.data.items(plugin, keyprefix) // plugin.data.items(keyprefix)

Required permissions:
  • plugins.data
  • plugins.data[pluginid]

Returns a list of tuples with the key and value for the matching items.

plugin.data.list(id, key_prefix) // plugin.data.list(key_prefix)

Required permissions:
  • plugins.data
  • plugins.data[pluginid]

Returns all the keys for that plugin id that have the given prefix. This allows to have some list of elements configurations, and group them.

If id is not given, it uses the current plugin.

plugin.data.update(id, key, value) // plugin.data.update(key, value)

Required permissions:
  • plugins.data
  • plugins.data[pluginid]

Sets some data for some plugin id in a given key. Value must be a map.

plugin.data.update("serverboards.core.notifications/telegram", "user_to_map",{
  "dmoreno@serverboards.io": 12312312312
})

When called from a plugin it can avoid the use of id and just store data on the plugin itself. If id is provided it is asserted against the current plugin name.

If called from other channels (UI, TCP) it requires the id.

Plugins

plugin.alias(uuid, alias)

Required permissions:
  • plugin

Creates an alias for that UUID. Only local to caller.

plugin.call(uuid or alias, method, params)

Required permissions:
  • plugin

Performs the call on that uuid or allias

plugin.catalog()

Required permissions:
  • plugin

Lists all the installed plugins and components.

plugin.component.catalog(filter)

Required permissions:
  • plugin

Returns all the components in raw form that comply with the filter.

The filter may have:

  • type – Search for specific type
  • trait – Must have this trait
  • traits – Must have any of these traits
  • id – The component_id or plugin_id/component_id matches

This can be used to have custom components on the client side, without any kind of server implication.

plugin.is_running(uuid)

Required permissions:
  • plugin

Returns true if the plugin is running, false if not.

plugin.reload()

Required permissions:
  • plugin.install

Reloads information of plugins from installed plugins. Normally user never has to call it, as Serverboards watches for changes at the disk, but if a reload is needed ASAP, it can be focefully called.

plugin.start("pluginname/component")

Required permissions:
  • plugin

Starts the required plugin and returns an ID to be referenced as the plugin.

This id can later be used to call any method inside the plugin in the form of ID.METHOD, for example:

id = plugin.start("serverboards.core.actions/daemon")
 # id = 55032508-03de-11e7-b896-742f68cd0608
55032508-03de-11e7-b896-742f68cd0608.dir()
 # [....]

This id can be used also in plugin.stop and plugin.call.

plugin.stop(uuid or alias)

Required permissions:
  • plugin

Stops the plugin.

Project

Project management.

project.create(shortname, [name, tags, description] )

Required permissions:
  • project.create

Can be called with the list of [shortname, attributes], or the object with all data.

Creates a new project with the given shortname and attributes.

Attributes may be:

  • name - Full name
  • tags - Initial project tags
  • description - Project description

project.create(shortname, attributes)

project.delete(shortname)

Required permissions:
  • project.create

Deletes the project

project.get(shortname)

Required permissions:
  • project.get

Returns expanded information for the project, including the services.

project.list()

Required permissions:
  • project.get

Lists all projects, returning all attributes for each.

project.update(shortname, attributes)

Required permissions:
  • project.update

Updates the given attributes of the project:

  • name - Full name
  • tags - Initial project tags
  • description - Project description
  • shortname - Changes the shortname

Query

query.query({query, context})

Performs a manual query with the given context.

Normally dashboard.widget.extract is performed, as it does only require the widget id, but in some cases a direct call of a query is required, as when preparing the widgets, or for reports, or any other case.

The context is a dictionary with the extractors ids as keys, and the extractor data (extractor, config, service), or ‘vars’ with a dict that maps the variable and the value.

query.query({
  query: "SELECT * FROM data",
  context: {
    A: { extractor: "test.extractor/random", config: {min:0, max: 10}},
    __vars__: {
      start: '2018-08-01T10:00',
      end: '2018-08-01T11:00',
      now: '2018-08-01T17:00'
    }
  })

Rules

This method of managing the rules is deprecated but may still work until Serverboards 18.04.

This rules are very limited to just state changes, and can not be retrofitted to be expended. The newer version is based on conditions. Internally since 18.01 all rules use the 18.01 method.

Please use rules_v2.

rules.delete(uuid)

Deletes a rule by uuid.

This only marks the rule as deleted, as it persists in the database for traceability reasons.

rules.get(uuid)

Returns a simple rule by uuid

rules.list(filter)

Returns a list of rules, in the rule format. Applies the given filter:

  • uuid – Only this rule
  • traits – any of the given traits
  • project – Only rules at that project
  • trigger – Only rules that use this trigger
  • deleted – Only show deleted rules (True), or only not deleted (False). Default False.

rules.update(rule)

If uuid is NULL creates the rule. The rule format is:

rules.update( {
  uuid: null,
  service: nil,
  trigger: {
    trigger: "serverboards.test.auth/periodic.timer",
    params: { period: 0.5 }
  },
  actions: {
    tick: {
      action: "serverboards.test.auth/touchfile",
      params: {
        filename: "/tmp/sbds-rule-test"
      }
    }
  }
} )

Rules v2

Second version for rules management.

rules_v2.create(rule: rule_v2) -> uuid

Adds a new rule.

The passed in rule should not have the UUID set, and it returns the new UUID to reference this rule.

rules_v2.delete(uuid)

Marks a rule as deleted.

Rules are not relaly never deleted, as they may be referenced from logs and so on.

rules_v2.get(uuid) -> rule_v2

Returns full data of a specific rule

rules_v2.list(filter: object) -> [rule_v2]

Lists all rules that match the filter object.

Filter options:

  • project – Filter by project shortname
  • deleted – Show deleted rules (true), not deleted (false) or "both".

rules_v2.trigger(id, params...)

Triggers the given rule with that trigger params.

Used when the trigger is not a specific trigger check function, but a cron checker or similar that may trigger at any moment.

rules_v2.trigger_wait(id, params...)

Triggers the given rule with that trigger params. Waits for action chain to finish.

This can be used to force wait until the rule is done, or to send several times the same trigger. If its already executing will not retrigger, but waiting, it will when the currently executing action chain finishes.

rules_v2.update(rule_uuid: uuid, changes: rule_v2) -> ok

Updates the rule by uuid. Changes is any subset of a rule.

Services

service.attach({project, service})

Required permissions:
  • service.attach

Attaches a service to a project. A shared service can be accessed from all the accesible projects.

Project is by shortcode service by uuid.

service.create(attributes) -> UUID

Required permissions:
  • service.create

Creates a new service, returns the new UUID

service.delete(uuid)

Required permissions:
  • service.create

Deletes a service by UUID

service.detach({project, service})

Required permissions:
  • service.attach

Detaches a service from a project. May leave the service detached from any.

Project is by shortcode service by uuid.

service.get(uuid)

Required permissions:
  • service.get

Gets a single service by UUID

service.list(filter \\ [])

Required permissions:
  • service.get

Can filter by:

  • project
  • type
  • traits
  • name

service.update(uuid, attributes)

Required permissions:
  • service.update

Updates the service with the given attributes.

Settings

settings.get(section)

Required permissions:
  • settings.view
  • settings.view[section]

Gets all data from a section

settings.list()

Returns all settings this user can see

settings.update(section, data)

Required permissions:
  • settings.update

Updates one section data, replacing all old data

settings.update(section, key, value)

Required permissions:
  • settings.update

Updates one key of data on the given section.

User Settings

settings.user.get(section) // settings.user.get(email, section)

Required permissions:
  • settings.user.view
  • settings.user.view_all

Gets some data from the user.

email is optional and is used only by admin with permission settings.user.view_all

settings.user.update(section, data) // settings.user.update(email, section, data)

Required permissions:
  • settings.user.update
  • settings.user.update_all

Updates one key of data on the given user data section.

email is optional and is used only by admin with permission settings.user.update_all

dashboard.widget.delete(widget_uuid)

Removes the given widget from its dashboard.

dashboard.widget.extract(uuid, vars)

Returns a dict with all data from the widget resolved.

This means that if there were any queries, it is performed server side and returns the results.

This helps to be able to do queries without having direct access to queries or specific services, as this allows blind access to the results.

Normally vars are:

  • start – start of a time period to analyze (start to end)
  • end – end of the period to analyze (start to end)
  • now – current datatime
  • prev – The begining of the previous period (prev to start)