Policy-Based Agent Settings Control

Advanced configuration of KEPM Agent Settings

Audience: IT admins. This example shows how to use a policy to set or change agent or plugin settings so many endpoints get the same configuration from a central place.

---

Overview

You can push configuration to endpoints using a SettingsUpdate policy. The policy defines which plugin (or file) to update and what JSON to write. A job on the agent—Process Configuration Policies—reads these policies and writes the configuration to the target plugin JSON file (e.g. Plugins/KeeperPolicy.json, Plugins/RedirectEvaluator.json). After that, you may need to revert plugin settings (so in-memory settings match the new file) and restart the plugin for changes to take effect.

When to use this:

• Roll out the same plugin settings to many machines (e.g. enforce policies for admins, redirect rules, KeeperClient language override).

• Change settings from the dashboard or policy store instead of editing files on each endpoint.

---

1

Create a SettingsUpdate policy

A SettingsUpdate policy has:

• PolicyType: "SettingsUpdate".

• Extension: At least PluginName (or TargetFile) and SettingsJson (the full plugin JSON as a string).

Option A — Target a plugin by name

Use Extension.PluginName so the processor writes to Plugins/{PluginName}.json:

{
  "PolicyId": "my-settings-update-policy",
  "PolicyName": "Push KeeperPolicy enforce-for-admins setting",
  "PolicyType": "SettingsUpdate",
  "Status": "enabled",
  "Extension": {
    "PluginName": "KeeperPolicy",
    "Action": "Update",
    "SettingsJson": "{ ... full KeeperPolicy.json content as a single string ... }"
  }
}

Option B — Target a file by path

Use Extension.TargetFile (path relative to the app root) instead of PluginName:

"Extension": {
  "TargetFile": "Plugins/KeeperPolicy.json",
  "Action": "Update",
  "SettingsJson": "{ ... }"
}

Important: SettingsJson is the entire plugin JSON. The processor replaces the whole file. So you must include all required fields (e.g. id, name, executablePath, Subscription, metadata) or the plugin may fail to start. Easiest approach: copy the current plugin JSON from one endpoint, change only the settings you care about, then put that full JSON into SettingsJson (as a string—escape inner double quotes as \").

2

Example — KeeperPolicy “enforce for administrators”

To turn on “enforce policies for administrators” (so admins are denied when no policy matches):

1. Get the full contents of Plugins/KeeperPolicy.json from an endpoint (or from your template).

2. Set metadata.admin.enforce_policies_for_administrators to true (or the key your product uses).

3. Create a SettingsUpdate policy with PluginName: "KeeperPolicy" and SettingsJson set to that full JSON (as a string). Use your policy store or dashboard to add this policy and assign it to the right collections/machines.

4. On the agent, run the Process Configuration Policies job (scheduled or on demand). It will write the new JSON to Plugins/KeeperPolicy.json.

5. Revert plugin settings so runtime matches the file: POST /api/PluginSettings/KeeperPolicy/revert (or revert-all). Then restart the KeeperPolicy plugin: POST /api/plugins/KeeperPolicy/restart.

3

Example — RedirectEvaluator (e.g. ncpa.cpl redirect)

To push redirect configuration (e.g. redirect ncpa.cpl to Keeper.NetworkConnections):

1. Build the full RedirectEvaluator plugin JSON you want (including id, name, executablePath, Subscription, and metadata.redirect with enabled: true and your rules). See Reference: Redirect and Reference: Plugin & Task Settings.

2. Create a SettingsUpdate policy with PluginName: "RedirectEvaluator" and SettingsJson equal to that full JSON as a string (escape quotes: \", and in regex patterns use \\\\ for a single backslash).

3. Deploy the policy and run Process Configuration Policies on the agent.

4. Revert and restart if needed: POST /api/PluginSettings/RedirectEvaluator/revert, then POST /api/plugins/RedirectEvaluator/restart.

4

Run the Configuration Processor

The agent must run the job that processes SettingsUpdate policies. That job is usually named something like Process Configuration Policies or configuration-policy-processor. It:

• Reads policy templates (from the policy store or synced policies).

• Finds policies with PolicyType "SettingsUpdate".

• For each, writes Extension.SettingsJson to the file determined by PluginName or TargetFile.

You can:

• Trigger the job on a schedule (if it’s already set up).

• Run it once via the API: POST /api/Jobs/{jobId}/run (use the job id for the Process Configuration Policies job).

After it runs, the plugin JSON files on disk are updated. Use revert and restart as above so the running plugin uses the new settings.

Summary

Step	Action
1	Create a policy with PolicyType "SettingsUpdate" and Extension containing PluginName (or TargetFile) and SettingsJson (full plugin JSON as string).
2	Deploy the policy to the right collections/machines.
3	Run the Process Configuration Policies job on the agent (schedule or API).
4	Revert plugin settings so runtime matches the file: POST /api/PluginSettings/{pluginName}/revert.
5	Restart the plugin if needed: POST /api/plugins/{name}/restart.