Commands

Commands are executables that are run whenever a component needs some dynamic information or work. May things can be defined in static terms, as new service types, but in some moment the plugin needs some dynamic action. In this moment Serverboards can run the command and communicate via JSON RPC.

Manifest component structure

- name: Core actions.
  type: cmd
  id: cmd
  timeout: 1000s
  strategy: one_for_one
  perms: settings.view[serverboards.core.actions/settings]
  command: serverboards-core.py
  user_perms: plugin
Field Description  
name Name of the component  
type cmd  
id id of the component inside the plugin  
timeout If present the process will be kept alive this time and only invoked once. If not present when needed will be executed and finalized intermediately (as if timeout 0). Can be arbitrary large but not forever. Can use time shortcuts: 1000ms, 1s, 1m, 1h, 1d, 1M or 1y.  
perms List of permissions provided to this plugin. This may have special context (in between []) to allow that permission in that context. Not all permissions allow contexts.  
command Relative path executable to execute.  
strategy Daemon start/restart strategy: singleton one_for_one
user_perms Required permissions from user to be able to call this plugin.  

Backend processes

Plugins in Serverboards are independent executable commands that perform communication with the core using JSON-RPC on the standard input and output.

Serverboards AIM to be JSON RPC 2.0, but some limitation apply:

  • No jsonrpc version code
  • Not using error struct always. Sometimes just a string.
  • One line per request. Most JSON encoders use this as default.

This means plugins can be developed in the programming language of your choice, with any internal architecture you need.

Communication is two way: clients can both receive request and perform them.

There are strict limits on how long can a request take (5 seconds). If it takes more time the process will be terminated and the calling side will receive an error. Because of this if your call can take long time, you may use some continuation technique for long requests, for example using client events.

Strategy and timeout

The daemon can be started with a given strategy. Default is one_for_one.

  • one_for_one – Start a new process every time a plugin.start requires this daemon
  • singleton – Start the first time this daemon is required, and reuse. Do not stop until timeout.

Timeout is applied only for one_for_one and singleton strategies, and means that if in the specified time there are no requests it is stopped. It can have some timespec description, setting a suffix with s, m, h, d, M or y. For example for one week use 7d.

If any daemon fails it will not be automatically restarted. Check init services

Client events

All clients can subscribe and emit new events that all other clients will receive.

This events can be restricted by permissions or clients. Check the RPC API reference for more information.

Commands must be stateless

All commands must be able to deal with termination and expected continuation.

Normally at start you will load (from the core or somewhere else) last known required status, and keep going with it.

It is not always possible because of for example depending on external communication and state, but it should be prepared because it may happen. In these cases this situation must be part of the provided API so it must be explicitly contemplated.

Remote connections

Plugins can request SSH access to accessible servers.

There is also a work mode that sends the plugin to the server and executes it there, using the JSON RPC over SSH.

Individual plugins can create their own communication methods, but the SSH connection is the prefered one as SSH is a battle tested secure protocol.

Permissions

There is a execute-all-plugins permissions: plugin. Other that this, each command may set specific permissions that the caller must comply using user_perms.

If the caller does not have that permissions, the call will fail.

For example a command may need a ssh or plugin permission to execute commands on the serverboards.core.ssh plugin.

Every command has an implicit user_perms with the id of the command, for example serverboards.core.ssh/daemon permission. This helps with boilerplate on required plugins.

user_perms can be set to a empty list to allow all users to call this command. Developers are advised to be careful as it may be unsecure.