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>, orhardware:<id>) covers this node. - Manifest — validates that
manifest.jsondeclares 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.
See also
- Building Plugins — create, scope, sign, and ship your own plugin with
cnvstrpack. - CLI Reference — the full
plugincommand surface. - Licensing — how license enforcement affects plugin installs when a node is frozen.