Installing Plugins

This page covers the full plugin lifecycle on a node: installing a package, verifying its signature, listing what is loaded, and removing a plugin cleanly. All plugin commands require root for mutations.

Installing a plugin

Plugins are distributed as .cenvero-plugin files. To install one:

sudo cenvero-str-ctl plugin install /path/to/my-plugin-1.2.0.cenvero-plugin

Plugins run sandboxed. A plugin is a signed executable that the agent launches as a supervised, unprivileged child process — never inside the agent and never as root. Each plugin runs as an account of its own: a user and group id no other plugin shares, so plugins cannot read one another's files or reach one another's processes. The agent picks the id from a range it reserves (60578–61183), skips any id an account, group or running process on the server already uses, and keeps it for the plugin across restarts and upgrades; removing the plugin frees it. No login account is created for it. plugin list shows each plugin's id. The agent verifies everything below before it launches the executable, so a bad package never starts a process. See Building Plugins → How plugins run for the security model.

Do not narrow the privileges of the agent's service (for example with a systemd drop-in that limits what it may hold): the agent needs them to set up each plugin's sandbox, and without them it starts no plugin: plugin list shows each one DISABLED, with a reason saying why.

Before launching, the agent performs these checks in order:

Signature — verifies that the package is intact and was genuinely signed with the developer certificate Cenvero issued, and that the certificate is authentic. A package that is tampered with, or signed with a key Cenvero never certified, is rejected.
Certificate validity — checks that the developer certificate has not expired and has not been revoked.
Scope — checks that the developer certificate's scope (any, license:<serial>, or hardware:<id>) covers this node.
Manifest — validates that manifest.json declares a valid entrypoint and only known requested capabilities.
Agent version — if the manifest sets min_agent_version or max_agent_version, this node's agent version must fall inside that range. A release candidate counts as the version it leads up to: a 1.4.0-rc.2 agent meets a minimum of 1.4.0.
Dependencies — every plugin named in the manifest's dependencies must already be installed and enabled on this node.

A refusal says exactly what to fix, for example:

plugin: my-plugin 1.2.0 needs agent version 1.5.0 or newer; this agent is 1.4.0 — upgrade the agent or install a version of the plugin built for 1.4.0
plugin: my-plugin 1.2.0 needs these plugins installed and enabled first: base-exporter (not installed), geo-db (installed but disabled)

The agent does not fetch dependencies for you — install (or enable) the ones listed, then install the plugin again.

Only after all checks pass does the agent write the files and launch the sandboxed child. The capabilities the plugin is actually granted are the intersection of its requested capabilities and what its certificate's scope allows. If any check fails, nothing is written, no child is launched, and the command fails with the reason — for example a certificate whose scope does not cover this node. The agent state is unchanged.

On success the command confirms which plugin and version were installed, and where from:

{
  "data": {
    "message": "plugin \"my-plugin\" 1.2.0 installed from /path/to/my-plugin-1.2.0.cenvero-plugin",
    "name": "my-plugin",
    "ok": true,
    "previous_version": "",
    "restarted": false,
    "version": "1.2.0"
  },
  "status": "ok"
}

plugin install also takes a plugin name instead of a path: a bare <name> installs from the official Cenvero store, and <username>/<name> from an external store you have added with plugin store add. The download is verified exactly like a local file.

Adding a store

Every node already trusts the official Cenvero store, so its plugins install by bare name with nothing to add first. A developer's own store has to be added once per node before its plugins install by name:

Ask the store's publisher for its signed store file. Publishers download it from their Developer portal; the marketplace page of a plugin names who publishes it.
Add it on the node. The node checks the file's signature itself, offline, before it trusts the store:

sudo cenvero-str-ctl plugin store add ./acme-store.cenvero-store-v1.json

Install any plugin from it as <username>/<name>, the install id its marketplace page shows.

plugin store list shows the stores a node trusts, and plugin store remove <username> stops trusting one.

Verifying a plugin

plugin verify re-checks a plugin on the node and exits non-zero if it does not pass, so you can use it in scripts.

Give it the name of an installed plugin to check that its files on disk are still the ones that were signed, and that its developer certificate is genuine, covers this node and has not been revoked — the same check the agent makes before it starts a plugin:

cenvero-str-ctl plugin verify my-plugin

{
  "data": {
    "developer_key_id": "dev-7f3a",
    "message": "plugin \"my-plugin\" 1.2.0 verifies: its files are the ones that were signed, and developer certificate dev-7f3a (scope any) is genuine, covers this node and is not revoked",
    "name": "my-plugin",
    "ok": true,
    "scope": "any",
    "source": "installed",
    "verified": true,
    "version": "1.2.0"
  },
  "status": "ok"
}

Give it the path of a package file to run every check an install would make — including the agent-version range and dependencies — without installing anything:

sudo cenvero-str-ctl plugin verify /var/lib/cenvero-str/my-plugin-1.3.0.cenvero-plugin

If the check fails, the error says why, for example that a file was changed after install or that the certificate has been revoked. To check a package's signature on your own machine instead, use the packer's verify command with the developer's public key:

cnvstrpack verify /path/to/my-plugin-1.2.0.cenvero-plugin --pub developer.pub

Listing installed plugins

cenvero-str-ctl plugin list

Each plugin is listed with its manifest, its state, where it is installed, when it was loaded, and the capabilities it was granted. A plugin that is not running although you did not disable it also carries a reason, a sentence saying why.

State	Meaning
`INSTALLED`	Installed and enabled: its sandboxed child process is running (and is restarted with backoff if it crashes).
`PENDING`	The agent has just started and is checking the plugin before it starts it (see After a restart or an upgrade).
`DISABLED`	Stopped, with its files kept. Disabled by you; stopped because its developer certificate was revoked; or not started when the agent started — its `reason` says why.

Show full detail for one plugin:

cenvero-str-ctl plugin show my-plugin

Disabling and re-enabling

Disable a plugin without removing it. Its child process is stopped, its hooks are withdrawn, and its files stay on disk:

sudo cenvero-str-ctl plugin disable my-plugin

# Re-enable later
sudo cenvero-str-ctl plugin enable my-plugin

plugin enable re-verifies the plugin before starting it — the signing chain, the certificate's scope, whether it has been revoked, and its agent-version range — exactly as when the agent restarts it. A plugin whose certificate has since expired or been revoked, or whose files were altered while it was disabled, is refused, and you need to install a current version instead.

An enabled plugin keeps the capabilities it was granted when you installed it. Enabling a plugin left by an earlier agent version (see below) grants it what installing the same package grants.

After a restart or an upgrade

When the agent restarts — after an agent update, a systemctl restart, or a reboot of the server — it starts again every plugin that was enabled, and nothing else:

Each plugin is checked first. Before it starts a plugin, the agent checks its files on disk exactly as plugin enable does: they are the ones that were signed, the developer certificate is genuine, covers this node and is not revoked, and the plugin supports this agent version. The plugin then runs with the capabilities it was granted when you installed or enabled it, never more. While the checks run, plugin list shows it as PENDING.
A plugin that fails is not started. plugin list shows it as DISABLED with a reason, for example that its files were changed or its developer certificate was revoked. It is checked again at the next restart; once you have fixed the cause, plugin enable starts it without a restart.
A plugin you disabled stays disabled, and so does one whose certificate was revoked while the agent ran.
No plugin starts while revocations cannot be checked. The node keeps the list of revoked developer certificates it last fetched. If that saved list cannot be verified when the agent starts, no plugin is started, and each one says so in its reason. The agent fetches a current list when it starts and at least every six hours; enable your plugins once it has.
A plugin scoped to this server's licence is checked once the licence has loaded, so it is not refused merely because the agent was still starting.

Plugins installed by an earlier agent version

Earlier agent versions kept no record of installed plugins, so their plugins stopped at every restart and dropped out of plugin list while their files stayed on the server. After you upgrade, those plugins are listed again, as DISABLED, with the reason installed by an earlier agent version that did not save plugin state. The upgrade starts none of them on its own. Enable each one you want running:

sudo cenvero-str-ctl plugin enable my-plugin

The enable checks the plugin as above and records it; from then on it comes back after every restart. To remove one you no longer want, use plugin remove.

If you move the agent back to an earlier version, that version starts no plugin after a restart, as before; upgrading again brings them back as they were.

When a developer certificate is revoked

The node refreshes the plugin revocation list periodically — at least every six hours. When a refresh revokes the certificate a running plugin was signed with, the plugin is stopped and disabled straight away, without waiting for a restart, and plugin list gives the revocation as its reason. The agent logs an error naming the plugin and raises a SECURITY event, so it reaches your alerting and webhooks. Its files are kept for you to inspect, and it cannot be enabled again while the revocation stands.

Removing a plugin

sudo cenvero-str-ctl plugin remove my-plugin

The agent unloads the plugin cleanly, removes its files, and updates the plugin registry.

Removal is unconditional. Dependencies are checked when a plugin is installed, not when one is removed or disabled, so nothing stops you removing a plugin that another one lists in its dependencies. Before removing one, check the dependencies of your other plugins (plugin list shows each plugin's manifest), and disable it first with plugin disable if you want to test the effect reversibly.

Updating a plugin

Install the new version over the existing one:

sudo cenvero-str-ctl plugin install /path/to/my-plugin-1.3.0.cenvero-plugin

The agent runs all the same verification steps as a fresh install, before it touches the installed version. If the old version is running, it is stopped, the new files are put in place, and the new version is started — the reply says so:

"message": "plugin \"my-plugin\" 1.3.0 installed from /path/to/my-plugin-1.3.0.cenvero-plugin, replacing 1.2.0: the running 1.2.0 was stopped and 1.3.0 started",
"previous_version": "1.2.0",
"restarted": true,

If the new package fails a check, nothing changes and the old version keeps running. If its files cannot be written, the old version's files are left as they were and it is started again; the error says so.

To roll back to a previous version, install the older .cenvero-plugin file.