# Policy-Based Agent Settings Control

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FeSxdNBGFp5KTJfW9PQ9W%2Fimage.png?alt=media&#x26;token=c3b37d39-998f-4d8d-9d7a-9b07a9e3c0e2" alt=""><figcaption></figcaption></figure>

**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.

***

{% stepper %}
{% step %}
**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 `\"`).
{% endstep %}

{% step %}
**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`.
   {% endstep %}

{% step %}
**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](/keeperpam/endpoint-privilege-manager/reference/redirect-capability.md) and [Reference: Plugin & Task Settings](/keeperpam/endpoint-privilege-manager/reference/plugin-and-task-settings.md).
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`.
   {% endstep %}

{% step %}
**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.
{% endstep %}
{% endstepper %}

### Summary

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="91.3333740234375">Step</th><th>Action</th></tr></thead><tbody><tr><td>1</td><td>Create a policy with <strong>PolicyType</strong> <code>"SettingsUpdate"</code> and <strong>Extension</strong> containing <strong>PluginName</strong> (or <strong>TargetFile</strong>) and <strong>SettingsJson</strong> (full plugin JSON as string).</td></tr><tr><td>2</td><td>Deploy the policy to the right collections/machines.</td></tr><tr><td>3</td><td>Run the <strong>Process Configuration Policies</strong> job on the agent (schedule or API).</td></tr><tr><td>4</td><td>Revert plugin settings so runtime matches the file: <strong>POST /api/PluginSettings/{pluginName}/revert</strong>.</td></tr><tr><td>5</td><td>Restart the plugin if needed: <strong>POST /api/plugins/{name}/restart</strong>.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/endpoint-privilege-manager/policies/policy-examples/advanced-examples/policy-create-a-policy-to-set-settings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.