Installing Plugins

This page covers the full plugin lifecycle on a node: installing a package, verifying the signing chain, 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 under a dedicated cenvero-str-plugin user — never inside the agent and never as root. 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.

Before launching, the agent performs these checks in order:

Signature chain — verifies the plugin's Ed25519 signature, then the developer certificate, then the intermediate, then validates the chain terminates at the root key compiled into the agent binary.
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 compatible agent API version, a valid entrypoint, and only known requested capabilities.
Dependencies — checks that all declared dependencies are installed and satisfy the version constraints.

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 agent prints a specific rejection reason. The agent state is unchanged.

error: plugin install failed
  reason: developer certificate scope mismatch
  scope:  license:ENT-2024-00042
  node:   license ENT-2024-00099
  action: obtain a plugin package signed with a certificate scoped to your license serial

On success, the agent loads the plugin and confirms:

plugin my-plugin 1.2.0 installed and loaded
  signed by: Acme Corp Developer Certificate
  scope:      any
  api:        stratum/plugin/v2

Verifying a plugin before installing

Inspect a .cenvero-plugin file without installing it:

cenvero-str-ctl plugin verify /path/to/my-plugin-1.2.0.cenvero-plugin

FIELD            VALUE
Name             my-plugin
Version          1.2.0
API version      stratum/plugin/v2
Developer        Acme Corp
Certificate      valid (expires 2026-12-31)
Scope            any
Chain            root → intermediate → developer  [all valid]
Dependencies     (none)
Compatible       yes

This is a read-only operation and does not require root. Use it to check a plugin before distribution or before installing on a production node.

Listing installed plugins

cenvero-str-ctl plugin list

NAME           VERSION  STATE   SCOPE               DEVELOPER
my-plugin      1.2.0    loaded  any                 Acme Corp
audit-export   0.8.1    loaded  license:ENT-2024-00042  Cenvero
debug-tools    1.0.0    loaded  hardware:a3f2...    Cenvero

State	Meaning
`loaded`	Plugin's sandboxed child process is running normally (and is restarted with backoff if it crashes).
`error`	Plugin failed to start or its child kept crashing — check `cenvero-str-ctl plugin show <name>` for the error and the captured child stderr.
`disabled`	Plugin was manually disabled; its child is stopped but its files are kept.

Show full detail for one plugin:

cenvero-str-ctl plugin show my-plugin

This prints the manifest, certificate detail, load time, and any runtime log lines the plugin has emitted.

Disabling and re-enabling

Disable a plugin without removing it. The plugin binary and its configuration stay on disk; it is simply not loaded on the next agent start:

sudo cenvero-str-ctl plugin disable my-plugin

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

A disabled plugin's signature chain is re-verified when it is re-enabled, so an expired developer certificate will cause a re-enable to fail even if the plugin was installed successfully before the certificate expired.

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. If other installed plugins depend on the one being removed, the command will refuse:

error: cannot remove my-plugin — required by: audit-export
  remove audit-export first, or use --force to override

Use --force only if you are sure the dependents can tolerate the missing plugin:

sudo cenvero-str-ctl plugin remove my-plugin --force

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. On success it unloads the old version and loads the new one with no agent restart. The old version's files are removed.

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