# Plugin & Task: Settings

<figure><img src="/files/HiNofoZezXkPjbf3RPD6" alt=""><figcaption></figcaption></figure>

**Audience:** IT admins who need to configure settings for individual KEPM plugins or understand which settings affect specific job tasks. For each setting this page states how it is used, its type, its default, and appropriate values.

Settings can be stored in the plugin JSON file (`Plugins/{PluginName}.json`) or in unified storage. At runtime, unified storage values take precedence over the JSON file until reverted.

## How Settings Are Applied

* **Plugin JSON** — Each plugin has a JSON file under `Plugins/` (for example, `Plugins/KeeperPolicy.json`). Settings can appear in the root or under `metadata`. Editing the file and restarting the plugin applies them.
* **Unified storage** — The agent can store plugin settings in unified storage. Those values override the plugin JSON until you run a revert — for example, `POST /api/PluginSettings/{pluginName}/revert` or `revert-all`.
* **SettingsUpdate policy** — A `SettingsUpdate` configuration policy can write the full plugin JSON to disk. After the Configuration Policy Processor runs, use Revert if you want runtime storage to reflect the new file, then restart the plugin.
* **API** — Read settings with `GET /api/PluginSettings/{pluginName}` or `GET /api/PluginSettings/{pluginName}/{settingName}`. Update individual keys with `PUT /api/PluginSettings/{pluginName}/{settingName}`. Value format is JSON — a string, number, or boolean as appropriate for the setting.

For the integrator-focused view of Plugin Settings — including how a job task binary calls this API at runtime to read broker configuration — see [Settings Keys](https://claude.ai/chat/settings-keys) and the [HTTP Reference](https://claude.ai/integration/http-reference#plugin-settings-api).

## Global Settings (`appsettings.json`)

These settings live under the `Settings` section of `appsettings.json` next to the agent service executable and apply to the whole service. A service restart is required for changes to take effect.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="198.85186767578125">Setting</th><th width="91.036865234375">Type</th><th width="105.0369873046875">Default</th><th>How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>KestrelHttpPort</code></td><td>integer</td><td><code>6888</code></td><td>HTTP port for the local management API (loopback only)</td><td>1024–65535; must be free on the machine</td></tr><tr><td><code>KestrelHttpsPort</code></td><td>integer</td><td><code>6889</code></td><td>HTTPS port for the local management API (loopback only)</td><td>1024–65535; must be free</td></tr><tr><td><code>system.logging.level</code></td><td>string</td><td><code>"Warning"</code></td><td>Minimum log level for the main service and KeeperLogger fallback</td><td><code>"Critical"</code>, <code>"Error"</code>, <code>"Warning"</code>, <code>"Information"</code>, <code>"Debug"</code>, <code>"Trace"</code> — use <code>"Warning"</code> or <code>"Information"</code> in production; <code>"Debug"</code> for troubleshooting</td></tr><tr><td><code>RepositoryPath</code></td><td>string</td><td><code>"KeeperStorage"</code></td><td>Directory for system configuration storage</td><td>Valid path; supports path variables such as <code>{approot}/KeeperStorage</code></td></tr><tr><td><code>PluginPath</code></td><td>string</td><td><code>"Plugins"</code></td><td>Directory containing plugin JSON files and executables</td><td>Valid path; supports path variables</td></tr><tr><td><code>ServiceName</code></td><td>string</td><td><code>"KeeperPrivilegeManager"</code></td><td>Windows service display name</td><td>Any non-empty string</td></tr><tr><td><code>MaintainKeeperAccount</code></td><td>boolean</td><td><code>false</code></td><td>When <code>true</code> on Windows, the ephemeral KeeperUserSession account is maintained across service restarts — for hybrid Azure AD + Intune environments</td><td><code>true</code> or <code>false</code></td></tr></tbody></table>

**MQTT broker** settings live under `MqttBrokerSettings` in `appsettings.json`:

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="121.5926513671875">Setting</th><th width="81.926025390625">Type</th><th width="131.370361328125">Default</th><th width="171.9259033203125">How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>IpAddress</code></td><td>string</td><td><code>"127.0.0.1"</code></td><td>MQTT broker bind address</td><td><code>"127.0.0.1"</code> or <code>"localhost"</code> — must remain loopback for security</td></tr><tr><td><code>Port</code></td><td>integer</td><td><code>8675</code></td><td>MQTT broker port</td><td>1024–65535; must be free</td></tr></tbody></table>

## KeeperPolicy Plugin

**Config file:** `Plugins/KeeperPolicy.json`

Settings are read at plugin startup and govern MQTT connection, API calls, and policy evaluation behavior.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Setting</th><th width="93.4444580078125">Type</th><th width="149.6666259765625">Default</th><th>How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>broker.host</code></td><td>string</td><td><code>"127.0.0.1"</code></td><td>MQTT broker hostname the plugin connects to</td><td>Hostname or IP of the local MQTT broker — typically <code>127.0.0.1</code></td></tr><tr><td><code>broker.port</code></td><td>integer</td><td><code>8675</code></td><td>MQTT broker port</td><td>1024–65535; must match <code>MqttBrokerSettings.Port</code></td></tr><tr><td><code>subscription.topic</code></td><td>string</td><td><code>"KeeperPolicy"</code></td><td>Primary MQTT topic the plugin subscribes to for policy requests</td><td>Non-empty topic name</td></tr><tr><td><code>subscription.topics</code></td><td>string</td><td>varies</td><td>Comma-separated list of additional MQTT topics to subscribe to</td><td>Comma-separated topic names</td></tr><tr><td><code>system.service.https_port</code></td><td>integer</td><td><code>6889</code></td><td>HTTPS port used for local API calls such as custom filter and job trigger</td><td>Same as <code>KestrelHttpsPort</code></td></tr><tr><td><code>customfilter.timeout_seconds</code></td><td>integer</td><td><code>30</code></td><td>Timeout in seconds for HTTP calls to custom filter jobs</td><td>Positive integer, typically 15–60</td></tr><tr><td><code>ratelimit.max_requests_per_minute</code></td><td>integer</td><td><code>100</code></td><td>Maximum policy evaluation requests per minute per source</td><td>Positive integer; increase if legitimate traffic is being throttled</td></tr><tr><td><code>metadata.admin.enforce_policies_for_administrators</code></td><td>boolean</td><td><code>false</code></td><td>When no policy matches a privilege elevation request and the requesting user is an administrator: <code>false</code> allows the action (OS default behavior); <code>true</code> denies it</td><td><code>false</code> — admins are not subject to deny-by-default when no policy matches; <code>true</code> — admins follow the same deny-by-default as standard users</td></tr></tbody></table>

## KeeperAPI Plugin

**Config file:** `Plugins/KeeperApi.json`

Used for communication with the Keeper backend — registration, policy sync, and audit.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Setting</th><th>Type</th><th>Default</th><th>How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>broker.host</code></td><td>string</td><td><code>"127.0.0.1"</code></td><td>MQTT broker hostname</td><td><code>127.0.0.1</code> or <code>localhost</code></td></tr><tr><td><code>broker.port</code></td><td>integer</td><td><code>8675</code></td><td>MQTT broker port</td><td>Must match <code>MqttBrokerSettings.Port</code></td></tr><tr><td><code>api.base_url</code></td><td>string</td><td>from environment</td><td>Base URL for the Keeper backend API</td><td>Full HTTPS URL — for example, <code>https://api.keepersecurity.com</code></td></tr><tr><td><code>sync.interval_minutes</code></td><td>integer</td><td>varies</td><td>Minutes between policy and settings sync from the backend</td><td>Positive integer, typically 15–60</td></tr></tbody></table>

## KeeperLogger Plugin

**Config file:** `Plugins/KeeperLogger.json`

Controls where and how log messages are written — file output, HTTP endpoint forwarding, retention, and rotation.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Setting</th><th>Type</th><th>Default</th><th>How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>logToFile</code></td><td>boolean</td><td><code>true</code></td><td>When <code>true</code>, log messages are written to a file</td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>logFileName</code></td><td>string</td><td><code>"Log/KeeperLogger.log"</code></td><td>Path for the log file — relative to the plugin working directory or absolute. Supports path variables.</td><td>Valid path — for example, <code>{approot}/Log/KeeperLogger.log</code></td></tr><tr><td><code>maxFileSizeMB</code></td><td>number</td><td><code>100</code></td><td>Maximum log file size in MB before rotation</td><td>Positive number, typically 50–500</td></tr><tr><td><code>logRetentionDays</code></td><td>integer</td><td><code>15</code></td><td>Number of days to keep rotated log files before deletion</td><td>Positive integer, typically 7–90</td></tr><tr><td><code>logToHttpEndpoint</code></td><td>boolean</td><td><code>false</code></td><td>When <code>true</code>, log messages are also sent to an HTTP endpoint</td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>loggingHttpEndpoint</code></td><td>string</td><td><code>""</code></td><td>URL to POST log messages to when <code>logToHttpEndpoint</code> is <code>true</code></td><td>Full HTTP or HTTPS URL, or empty</td></tr><tr><td><code>log.level</code></td><td>string</td><td>varies</td><td>Minimum level for messages written to file or HTTP</td><td><code>"Critical"</code>, <code>"Error"</code>, <code>"Warning"</code>, <code>"Information"</code>, <code>"Debug"</code>, <code>"Trace"</code> — use <code>"Warning"</code> or <code>"Information"</code> in production; <code>"Debug"</code> for troubleshooting</td></tr></tbody></table>

## RedirectEvaluator Plugin

**Config file:** `Plugins/RedirectEvaluator.json`

Redirect settings control whether the `LaunchPrivilegeElevation` job substitutes a different executable when a rule matches — for example, redirecting `ncpa.cpl` to a Keeper-managed network connections UI. See [Redirect Capability](https://claude.ai/chat/redirect-capability) for the full flow.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Setting</th><th>Type</th><th>Default</th><th>How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>metadata.redirect.enabled</code></td><td>boolean</td><td>configurable</td><td>When <code>true</code>, the <code>LaunchPrivilegeElevation</code> job runs the check-redirect task and evaluates the rules below. When a rule matches, the original request is denied and the <code>targetExe</code> is launched elevated instead. When <code>false</code>, check-redirect is skipped.</td><td><code>true</code> to enable redirect; <code>false</code> for normal launch-elevated behavior only</td></tr><tr><td><code>metadata.redirect.rules</code></td><td>array</td><td><code>[]</code></td><td>List of redirect rules. First matching rule wins.</td><td>Array of rule objects — see below. Leave <code>[]</code> if no redirects are needed.</td></tr><tr><td><code>metadata.redirect.rulesPath</code></td><td>string</td><td>optional</td><td>Path to a file containing redirect rules, as an alternative to inline <code>rules</code></td><td>Valid file path, or empty</td></tr></tbody></table>

**Redirect rule fields** (each object in `metadata.redirect.rules`):

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Field</th><th>Type</th><th>How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>sourceExePattern</code></td><td>string (regex)</td><td>Matched against the executable name in the elevation request. Case-insensitive.</td><td>Regex — use <code>\\.</code> for a literal dot, for example <code>"rundll32\\.exe"</code></td></tr><tr><td><code>commandLinePattern</code></td><td>string (regex)</td><td>Matched against the full command line. Case-insensitive.</td><td>Regex — for example <code>"ncpa\\.cpl"</code></td></tr><tr><td><code>elevationOnly</code></td><td>boolean</td><td>When <code>true</code>, the rule applies only to Privilege Elevation events</td><td><code>true</code> for typical redirect rules</td></tr><tr><td><code>nonAdminOnly</code></td><td>boolean</td><td>When <code>true</code>, the rule applies only when the requesting user is not an administrator</td><td><code>true</code> to redirect standard users only; <code>false</code> to redirect admins as well</td></tr><tr><td><code>targetExe</code></td><td>string</td><td>Plugin ID or executable name of the substitute, resolved from <code>Jobs/bin</code> or <code>Plugins/bin</code></td><td>For example, <code>"Keeper.NetworkConnections"</code> — must be deployed on the endpoint</td></tr><tr><td><code>targetArguments</code></td><td>string</td><td>Command-line arguments for the substitute executable</td><td>Any string; often <code>""</code></td></tr></tbody></table>

## KeeperClient Plugin

**Config file:** `Plugins/KeeperClient.json`

The system tray client — notifications, menu, and health checks. Many options are set under `metadata`.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Setting</th><th>Type</th><th>Default</th><th>How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>broker.host</code></td><td>string</td><td><code>"127.0.0.1"</code></td><td>MQTT broker hostname</td><td><code>127.0.0.1</code></td></tr><tr><td><code>broker.port</code></td><td>integer</td><td><code>8675</code></td><td>MQTT broker port</td><td>Must match broker</td></tr><tr><td><code>metadata.menu.refreshIntervalMinutes</code></td><td>integer</td><td><code>5</code></td><td>How often the tray menu is refreshed from the API</td><td>Positive integer, typically 1–30</td></tr><tr><td><code>metadata.menu.autoRefresh</code></td><td>boolean</td><td><code>true</code></td><td>Whether the menu refreshes automatically on a timer</td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>metadata.LanguageOverride</code></td><td>string</td><td><code>"DEFAULT"</code></td><td>Override the UI display language</td><td><code>"DEFAULT"</code> or a valid culture code such as <code>"en-US"</code></td></tr><tr><td><code>metadata.showInTray</code></td><td>boolean</td><td><code>true</code></td><td>Whether to show an icon in the system tray</td><td><code>true</code> or <code>false</code></td></tr></tbody></table>

## keeperAgent Plugin

**Config file:** `Plugins/keeperAgent.json`

Standalone UI for managing privilege elevation and file access requests — approvals, history, and expiration.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Setting</th><th>Type</th><th>Default</th><th>How It's Used</th><th>Appropriate Values</th></tr></thead><tbody><tr><td><code>approvalExpirationHours</code></td><td>integer</td><td><code>72</code></td><td>Hours after which a pending approval request expires</td><td>Positive integer, typically 24–168</td></tr><tr><td><code>approvedRequestExpirationHours</code></td><td>integer</td><td><code>24</code></td><td>Hours after which an approved request expires and can no longer be launched</td><td>Positive integer, typically 1–72</td></tr><tr><td><code>historyRetentionDays</code></td><td>integer</td><td><code>30</code></td><td>Number of days to keep history items in the UI</td><td>Positive integer, typically 7–90</td></tr><tr><td><code>maxPayloadSizeBytes</code></td><td>integer</td><td><code>1048576</code></td><td>Maximum payload size for messages (1 MB)</td><td>Positive integer</td></tr><tr><td><code>maxRequestItems</code></td><td>integer</td><td><code>20</code></td><td>Maximum number of pending request items shown</td><td>Positive integer</td></tr><tr><td><code>maxHistoryItems</code></td><td>integer</td><td><code>20</code></td><td>Maximum number of history items shown</td><td>Positive integer</td></tr><tr><td><code>maxExceptionMessageLength</code></td><td>integer</td><td><code>500</code></td><td>Maximum length of exception messages displayed</td><td>Positive integer</td></tr></tbody></table>

## Tasks That Use Plugin Settings

Some job tasks read plugin settings to determine their behavior. The table below documents which settings affect which tasks so you know where to look when a task is not behaving as expected.

| Job                        | Task             | Setting                                        | How It's Used                                                                                                                                                               |
| -------------------------- | ---------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LaunchPrivilegeElevation` | `check-redirect` | `RedirectEvaluator: metadata.redirect.enabled` | When `true`, the task runs the RedirectEvaluator and evaluates redirect rules. When `false`, the task is skipped and the job proceeds with normal elevated launch behavior. |

Other policy-control jobs — such as `privilege-elevation-policy-controls` and `default-policy-controls` — invoke `KeeperMfa`, `KeeperJustification`, and `KeeperApproval` as task executables. Their behavior is driven by job parameters and policy, not by plugin settings tables.

### Where to Configure

<table data-header-hidden="false" data-header-sticky><thead><tr><th>What</th><th>Where</th><th>Notes</th></tr></thead><tbody><tr><td>Global settings (ports, paths, log level)</td><td><code>appsettings.json</code> → <code>Settings</code> and <code>MqttBrokerSettings</code></td><td>Requires service restart for port and path changes</td></tr><tr><td>KeeperPolicy (broker, admin fallback, rate limit)</td><td><code>Plugins/KeeperPolicy.json</code> or <code>PUT /api/PluginSettings/KeeperPolicy/{key}</code></td><td>Restart KeeperPolicy after changing</td></tr><tr><td>KeeperAPI (broker, API URL, sync interval)</td><td><code>Plugins/KeeperApi.json</code> or Plugin Settings API</td><td>Restart KeeperAPI after changing</td></tr><tr><td>KeeperLogger (file path, retention, log level)</td><td><code>Plugins/KeeperLogger.json</code> or Plugin Settings API</td><td>Restart KeeperLogger after changing</td></tr><tr><td>Redirect (enabled flag, rules)</td><td><code>Plugins/RedirectEvaluator.json</code> or Plugin Settings API</td><td>Rule changes take effect on the next evaluation; restart not required</td></tr><tr><td>KeeperClient (menu, tray)</td><td><code>Plugins/KeeperClient.json</code></td><td>Restart KeeperClient to apply</td></tr><tr><td>keeperAgent (expiration, limits)</td><td><code>Plugins/keeperAgent.json</code></td><td>Restart keeperAgent to apply</td></tr></tbody></table>

After editing a plugin JSON file on disk, use `POST /api/PluginSettings/{pluginName}/revert` (or `revert-all`) to reload from the file into unified storage. Then restart the plugin so it picks up the new values. If `autoRestart: true` is set, stopping the plugin causes it to restart automatically.


---

# 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/reference/plugin-and-task-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.