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
|name||Name of the component|
|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.|
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:
- 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
If any daemon fails it will not be automatically restarted. Check init services
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.
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.
There is a execute-all-plugins permissions:
plugin. Other that this, each
command may set specific permissions that the caller must comply using
If the caller does not have that permissions, the call will fail.
For example a command may need a
plugin permission to execute
commands on the
Every command has an implicit
user_perms with the id of the command, for
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.