Plugin & Job Registration

Audience: IT admins who need to know how plugins and jobs are discovered, registered, and loaded.

---

Plugin Registration

How Plugins are Registered

Plugins are discovered from configuration files in the Plugins directory. Each plugin has a JSON file that describes the plugin and how to run it.

• Location: {approot}/Plugins/ (e.g. C:\Program Files\KeeperPrivilegeManager\Plugins).

• File name: {PluginName}.json (e.g. KeeperPolicy.json, KeeperAPI.json).

• Content: Plugin id, name, type (Executable or Service), executable path (if applicable), MQTT subscription, startup priority, autoStart, and other metadata.

The main service reads these JSON files at startup, validates them, and then starts plugins according to startupPriority and autoStart. Plugins that are Executable are launched as separate processes; those that are Service run inside the main process.

Plugin JSON (main fields)

Typical structure:

{
  "id": "KeeperPolicy",
  "name": "Keeper Policy Service",
  "pluginType": "Executable",
  "executablePath": "{pluginroot}/KeeperPolicy/bin/Release/net8.0/KeeperPolicy",
  "supportedPlatforms": ["Windows", "Linux", "macOS"],
  "Subscription": {
    "Topic": "KeeperPolicy",
    "Qos": 2,
    "CleanSession": true
  },
  "startupPriority": 20,
  "autoStart": true,
  "executionContext": "Service"
}

• id — Unique plugin ID; must match the plugin’s identity in the system.

• pluginType — Executable (separate process) or Service (in-process).

• executablePath — Path to the plugin executable; can use variables like {pluginroot}. Omit for in-process plugins.

• supportedPlatforms — List of OS names; the agent may skip the plugin on unsupported platforms.

• Subscription — MQTT topic and options for messaging.

• startupPriority — Lower numbers start first.

• autoStart — If true, the plugin is started when the service starts.

• executionContext — Service, User, or Interactive (where the plugin runs).

Adding a new plugin usually means: add the plugin’s binaries under Plugins/{PluginName}/ and add or edit Plugins/{PluginName}.json. After a service restart (or plugin reload if supported), the new plugin is registered and can be started.

Plugin Lifecycle

• Start: The main service starts the plugin (launches the executable or loads the in-process component). The plugin subscribes to MQTT and performs its work.

• Stop / Restart: Admins can stop or restart a plugin via the local management API (e.g. POST to /api/plugins/{name}/stop or /restart). The service may also restart plugins if they crash (when autoRestart is enabled).

• Settings: Plugin settings can be stored in unified storage or in the plugin JSON. Updates (from dashboard or config policy) may require a plugin restart to take effect.

Plugin Registration: MQTT subscription & publish settings

KEPM plugins declare their MQTT access as part of plugin registration (in the plugin’s JSON definition). Each plugin registers a primary subscription topic under Subscription.Topic (required), along with optional additional subscribe topics and publish permissions under metadata.mqttTopics. When the service starts, it loads plugin definitions, launches auto-start plugins, and uses these MQTT settings to determine which topics the plugin is allowed to listen to and which topics it is allowed to send messages to.

1) Primary subscription (required) Every plugin must register one primary MQTT topic using the Subscription block. This is the plugin’s main inbound topic for requests/control messages (for example, a policy plugin may use KeeperPolicy).

"Subscription": {
  "Topic": "KeeperPolicy",
  "Qos": 0,
  "CleanSession": true
}

2) Additional topic permissions (optional) Plugins can also register topic permissions in metadata.mqttTopics:

• metadata.mqttTopics.subscribe: extra topics the plugin may subscribe to (in addition to Subscription.Topic)

• metadata.mqttTopics.publish: topics the plugin is allowed to publish to

These lists support MQTT wildcards (+ and #) where appropriate.

"metadata": {
  "mqttTopics": {
    "subscribe": [ "AuditMessage", "EventMessages" ],
    "publish": [ "KeeperLogger", "EventMessages" ]
  }
}

How KEPM applies these settings KEPM combines the plugin’s primary subscription topic (Subscription.Topic) with any additional subscribe topics (metadata.mqttTopics.subscribe) to form the plugin’s effective subscription set, and it enforces publish permissions using metadata.mqttTopics.publish. Topic validation is enforced so a plugin can only subscribe/publish to topics permitted by its registration configuration.

---

Job Registration

How Jobs are Registered

Jobs are discovered from the Jobs directory. Each job is a single JSON file.

• Location: {approot}/Jobs/ (e.g. C:\Program Files\KeeperPrivilegeManager\Jobs).

• Naming: {job-id}.json. The id inside the file must match the filename.

• Loading: The job service (or equivalent) scans the directory at startup and when files change, parses each JSON file, validates it, and registers the job. Valid jobs are then available for events and scheduling; invalid files may be skipped and an error logged.

What “Registration” Means for Jobs

• Registered = the job is loaded, has a valid structure, and is known to the job runner. It will run when its trigger (event or schedule) fires, provided it’s enabled and any condition is met.

• Not registered = the file is missing, invalid, or not loaded (e.g. wrong directory or parse error). The job will not run.

You do not need to “register” jobs in a separate step: placing a valid {id}.json in the Jobs directory and (if required) restarting or waiting for the loader to rescan is enough. Some products also support creating or updating jobs via HTTP API (POST/PUT), which may write the JSON to the Jobs directory or an internal store.

Job Loading Order and Precedence

• Jobs are typically loaded in no guaranteed order; dependencies should be expressed via events and alternateJobId, not load order.

• If the same job id appears in more than one place (e.g. file and API), the product’s behavior (last-write-wins or file-wins) depends on implementation. Prefer a single source of truth (e.g. files for on-agent jobs, or dashboard/API for managed jobs).

Job Registration: MQTT subscription & publish settings

If a task/job needs to communicate over MQTT (either publishing messages or subscribing to topics), it must be registered the same way as other KEPM plugins: by placing a registration JSON file in the Keeper Privilege Manager plugins folder (for example, the KeeperPrivilegeManager/Plugins directory used by your deployment). This registration file defines the task’s identity and (when applicable) its MQTT topic permissions so the service can recognize and control the task’s messaging behavior.

Use KeeperInventoryBasic.json as a reference example. In most environments, tasks are not long-running services, so their registration typically sets AutoStart = false and RequiresMonitoring = false. This indicates the task should be invoked on demand (or by an orchestrated workflow) rather than started automatically and continuously monitored like a persistent plugin.

---

Summary

• Plugins: Registered by reading Plugins/*.json; each file describes one plugin (id, executablePath, Subscription, autoStart, etc.). Add or edit plugin JSON and restart (or reload) to register or change plugins.

• Jobs: Registered by reading Jobs/*.json; each file is one job (id, tasks, schedule or events). Add or edit job JSON in the Jobs directory (or via API if supported) so the job runner can load and run them.

Return to Reference Index