Skip to Content

Plugins

The plugins the server has, and updating them.

OperationKindHTTP
plugins.listcallGET /v1/plugins
plugins.addcallPOST /v1/plugins
plugins.uploadcallPOST /v1/plugins/package
plugins.removecallDELETE /v1/plugins/{id}
plugins.checkcallGET /v1/plugins/updates
plugins.updatecallPOST /v1/plugins/update

plugins.list

The plugins: those that come with rookery and the server's own.

Needs the role admin.

Result

FieldTypeDescription
dirstringThe directory of its own plugins; a folder copied there is one too.
pluginsPluginInfo[]
Request
{
  "id": 1,
  "op": "plugins.list"
}
Reply
{
  "id": 1,
  "result": {
    "dir": "text",
    "plugins": [
      {
        "dir": "text",
        "id": "k3v9qz2m8w1x",
        "label": "text",
        "origin": "shipped",
        "package": "text",
        "version": "0.6.0"
      }
    ]
  }
}

plugins.add

Install a plugin with npm from a registry or an address.

Needs the role admin.

Input

What to install

FieldTypeDescription
specstringA package of the server's npm registry, [@SCOPE/]NAME[@VERSION], or the https address of a .tgz.

Result

FieldTypeDescription
behind (optional)HostBehind[]After an update: the hosts whose configuration is now behind.
linesstring[]

Errors

StatusWhen
400Not a package or address, or npm failed; the message has its output
Request
{
  "id": 1,
  "op": "plugins.add",
  "data": {
    "spec": "text"
  }
}
Reply
{
  "id": 1,
  "result": {
    "behind": [
      {
        "changes": [
          {}
        ],
        "name": "status"
      }
    ],
    "lines": [
      "text"
    ]
  }
}

plugins.upload

Install a plugin from a .tgz, as npm pack makes one, which the server keeps.

Needs the role admin.

Input

Bytes: {"base64": …} on the portal, the request body over HTTP.

Result

FieldTypeDescription
behind (optional)HostBehind[]After an update: the hosts whose configuration is now behind.
linesstring[]

Errors

StatusWhen
400Not a .tgz, or npm failed; the message has its output
Request
{
  "id": 1,
  "op": "plugins.upload",
  "data": {
    "base64": "aGVsbG8K"
  }
}
Reply
{
  "id": 1,
  "result": {
    "behind": [
      {
        "changes": [
          {}
        ],
        "name": "status"
      }
    ],
    "lines": [
      "text"
    ]
  }
}

plugins.remove

Remove one of the server's own plugins.

Needs the role admin.

Arguments

NameWhereRequiredDescription
idpathyesThe plugin's id

Result

FieldTypeDescription
behind (optional)HostBehind[]After an update: the hosts whose configuration is now behind.
linesstring[]

Errors

StatusWhen
404No such plugin
409It comes with rookery and stays
Request
{
  "id": 1,
  "op": "plugins.remove",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "id": 1,
  "result": {
    "behind": [
      {
        "changes": [
          {}
        ],
        "name": "status"
      }
    ],
    "lines": [
      "text"
    ]
  }
}

plugins.check

Ask the registries the server's own plugins came from whether they have newer versions.

Needs the role admin.

Result

FieldTypeDescription
pluginsPluginUpdate[]

Errors

StatusWhen
400npm could not be run
Request
{
  "id": 1,
  "op": "plugins.check"
}
Reply
{
  "id": 1,
  "result": {
    "plugins": [
      {
        "id": "k3v9qz2m8w1x",
        "latest": "text",
        "note": "text",
        "package": "text",
        "version": "0.6.0"
      }
    ]
  }
}

plugins.update

Update one of the server's own plugins, or all, to the latest version of their registry, and say which hosts are behind then.

Needs the role admin.

Input

The plugin, by id or npm name; all without one

PluginUpdateSpec | null

Result

FieldTypeDescription
behind (optional)HostBehind[]After an update: the hosts whose configuration is now behind.
linesstring[]

Errors

StatusWhen
400It has no registry to ask, comes with rookery, or npm failed; the message says which
404No such plugin
Request
{
  "id": 1,
  "op": "plugins.update",
  "data": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "id": 1,
  "result": {
    "behind": [
      {
        "changes": [
          {}
        ],
        "name": "status"
      }
    ],
    "lines": [
      "text"
    ]
  }
}

Types

The named types used on this page.

PluginInfo

A plugin that was found, with what it can install.

FieldTypeDescription
description (optional)string
dirstringWhere it is on the machine that has it.
features (optional)PluginFeature[]
idstring
labelstring
originPluginOriginWhere a plugin comes from, which says whether it can be removed.
packagestringIts npm name.
provisioners (optional)ProvisionerInfo[]What it can create machines with.
versionstring

HostBehind

A host whose configuration is behind, and how.

HostBehind

A host whose configuration is behind, and how.

PluginUpdate

Whether a newer version of a plugin is there, as its registry says.

FieldTypeDescription
idstring
latest (optional)string | nullThe registry's latest version, when it is another one.
note (optional)stringWhy there is nothing to ask, or what asking said: a plugin from a .tgz or a folder has no registry to ask.
packagestring
versionstringThe version installed.

PluginUpdateSpec

What to update: one plugin by its id or npm name, or all of them.

FieldTypeDescription
id (optional)string | null

PluginFeature

Something a plugin installs, switched on per host.

FieldTypeDescription
actions (optional)PluginAction[]
channels (optional)string[]Channel topics, without the plugin's id.
groupstringThe group of the Features page it is listed in.
help (optional)string
idstringA profile names it PLUGIN/ID.
labelstring
services (optional)PluginService[]

PluginOrigin

Where a plugin comes from, which says whether it can be removed.

PluginOrigin

Where a plugin comes from, which says whether it can be removed.

ProvisionerInfo

Something a plugin creates machines with, for a saved host's profile.

FieldTypeDescription
actions (optional)Action[]Its plugin's own actions, such as listing images or pruning.
arguments (optional)Argument[]What creating a machine takes: the provisioner's own arguments first, then those of its machines.
collections (optional)Collection[]What it holds that can be listed, such as storage pools, each with the actions of its items.
description (optional)string
idstringIts id, which stays when it is renamed. In the list of types, the type itself.
kinds (optional)ProvisionerKind[]What it can make: machine, and kinds its plugin names.
labelstring
missing_secrets (optional)string[]The required ones that have no value. Not looked at in a plugin's listing.
name (optional)stringThe name it is registered under, such as ovh-incus. In the list of types, the type itself.
node (optional)stringThe node it lives on, when a feature of that host offered it, by name.
node_id (optional)stringThe id of that node.
own (optional)string[]The names of the provisioner's own arguments, which say where it is, such as an Incus server. Their values are kept as its settings.
problem (optional)stringWhy it cannot be used here, as a sentence that says what to change. Empty when it can.
secrets (optional)string[]The rookery secrets it is given.
settings (optional)map of stringThe values of its own arguments that are kept, by name.
setupstringseed: the machine boots with rookery's cloud seed and sets itself up. apply: rookery applies the profile over SSH once the machine answers.
type (optional)stringThe plugin's provisioner it is, as PLUGIN/ID, such as incus/vm.
verbs (optional)string[]What it can do besides create, status and destroy: start, stop, list, log.

PluginAction

An action a feature adds to a host.

FieldTypeDescription
agent (optional)booleanThe agent may run it with box run.
arguments (optional)string[]The names of the arguments it asks for.
extends (optional)string[]Actions of rookery it runs after, with no row of its own.
labelstring
namestringThe action is PLUGIN:NAME on the host.
userstringagent, operator or root.

PluginService

A program a feature keeps running on the host to answer calls.

FieldTypeDescription
methods (optional)string[]
namestringThe service is PLUGIN/NAME on the host.
userstring

Action

Something that can be done to a subject: a host, the installation, and later a provisioner or a resource. It says enough to build a form from.

FieldTypeDescription
arguments (optional)Argument[]
available (optional)booleanFalse, with why, when the subject's state rules it out now.
changes (optional)booleanFalse when it only reads, and may be called at any time.
collection (optional)stringThe id of the provisioner's collection it belongs to, whose items it makes, acts on or lists. The screens offer it there and not on the provisioner's page.
confirm (optional)string | nullThe question to answer yes to before it runs.
group (optional)stringThe group of the page it is listed in; Host when empty.
help (optional)string
label (optional)string
namestring
role (optional)RoleThe least role that may run it.
runs (optional)RunsWhere an action runs.
steps (optional)ActionStep[]What plugins add to it, in the order they run.
terminal (optional)booleanIt needs a terminal session attached; only a host runs these.
why (optional)string

Argument

FieldTypeDescription
choices (optional)stringA command whose lines are the values to offer.
confirm (optional)stringFor a yes or no: the question to answer yes to before the action runs with it on, instead of the action's own.
default (optional)string
fixed (optional)stringWhy it keeps its default here and cannot be given another value, such as destroying a machine no provisioner made. The screens show it greyed and say this instead of changing it. Empty when it can be changed.
help (optional)stringWhat it is for, in a sentence or two, beside its short label.
kind (optional)stringresource for an argument of a provisioner that sizes the machine: its CPUs, memory or disk. text for one whose value has several lines. boolean for a yes or no, which the screens show as a switch. Empty for any other argument.
label (optional)string
namestring
required (optional)boolean
secret (optional)booleanWhat is given is a secret, such as a password: it is not shown as it is typed, nor kept, nor written to a job's output.
values (optional)string[]The values a provisioner's argument takes, when it is a choice of a few. Empty for one that takes any text.

Collection

A list of things a provisioner holds, such as the storage pools of a server. Its items come with the provisioner's status, and its actions are the provisioner's own: some make an item, some act on one item, whose key fills their arguments, and some act on the whole list.

FieldTypeDescription
columns (optional)CollectionColumn[]The values each item shows besides its name, in order.
group (optional)stringThe group of the provisioner's page it is listed in.
help (optional)string
idstring
item (optional)CollectionAction[]The actions on one item.
keystring[]The names that identify an item, such as pool and volume. A collection within another starts with that one's key.
kinds (optional)string[]The kinds of resource that are its items, such as machine, in place of items the status gives: its item actions are offered on the page of each resource of those kinds the provisioner made.
label (optional)stringWhat one item is called, such as Storage pool.
list (optional)CollectionAction[]The actions on the whole list, such as pruning.
new (optional)CollectionAction[]The actions that make a new item.
plural (optional)stringWhat several are called, such as Storage pools.
remove (optional)stringThe item action that removes one.
show (optional)stringThe action that prints the list for the command line, which the screens show as the table instead.
within (optional)stringThe collection whose items hold these, such as the pools that hold volumes. Each item of that one lists those that belong to it.

ProvisionerKind

A kind of thing a provisioner makes.

FieldTypeDescription
actions (optional)Action[]What its plugin can do to one, each run with the verb act and the resource's id.
arguments (optional)Argument[]
idstringmachine, or a kind the plugin names, such as deployment.
label (optional)string
setup (optional)stringFor a machine: seed or apply, as for the provisioner.
spec (optional)anyThe specification one is made from, for a kind that has one: its format and label, as the plugin declares them.
verbs (optional)string[]What can be done to one besides create, status and destroy: start, stop, change, logs.

Role

What a caller has to be allowed for an operation. Each role includes the ones before it.

Role

What a caller has to be allowed for an operation. Each role includes the ones before it.

Runs

Where an action runs.

Runs

Where an action runs.

ActionStep

What a plugin adds to an action: a step run after it in the same run.

FieldTypeDescription
help (optional)string
labelstring

CollectionColumn

A value an item of a collection shows.

FieldTypeDescription
label (optional)string
namestring

CollectionAction

An action of a provisioner as one of a collection's.

FieldTypeDescription
actionstringThe provisioner's action, by its name.
arguments (optional)map of stringThe argument of the action each part of the key fills, where its name is not the part's own: {"volume": "name"}.
label (optional)stringWhat it is called where its item is known already, such as Grow. The action's own label when empty.

On this page