Plugin & Task: Settings
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 undermetadata. 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}/revertorrevert-all.SettingsUpdate policy — A
SettingsUpdateconfiguration 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}orGET /api/PluginSettings/{pluginName}/{settingName}. Update individual keys withPUT /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 Job & Plugin: Settings Keys and the HTTP Reference.
Global Settings (appsettings.json)
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.
KestrelHttpPort
integer
6888
HTTP port for the local management API (loopback only)
1024–65535; must be free on the machine
KestrelHttpsPort
integer
6889
HTTPS port for the local management API (loopback only)
1024–65535; must be free
system.logging.level
string
"Warning"
Minimum log level for the main service and KeeperLogger fallback
"Critical", "Error", "Warning", "Information", "Debug", "Trace" — use "Warning" or "Information" in production; "Debug" for troubleshooting
RepositoryPath
string
"KeeperStorage"
Directory for system configuration storage
Valid path; supports path variables such as {approot}/KeeperStorage
PluginPath
string
"Plugins"
Directory containing plugin JSON files and executables
Valid path; supports path variables
ServiceName
string
"KeeperPrivilegeManager"
Windows service display name
Any non-empty string
MaintainKeeperAccount
boolean
false
When true on Windows, the ephemeral KeeperUserSession account is maintained across service restarts — for hybrid Azure AD + Intune environments
true or false
MQTT broker settings live under MqttBrokerSettings in appsettings.json:
IpAddress
string
"127.0.0.1"
MQTT broker bind address
"127.0.0.1" or "localhost" — must remain loopback for security
Port
integer
8675
MQTT broker port
1024–65535; must be free
KeeperPolicy Plugin
Config file: Plugins/KeeperPolicy.json
Settings are read at plugin startup and govern MQTT connection, API calls, and policy evaluation behavior.
broker.host
string
"127.0.0.1"
MQTT broker hostname the plugin connects to
Hostname or IP of the local MQTT broker — typically 127.0.0.1
broker.port
integer
8675
MQTT broker port
1024–65535; must match MqttBrokerSettings.Port
subscription.topic
string
"KeeperPolicy"
Primary MQTT topic the plugin subscribes to for policy requests
Non-empty topic name
subscription.topics
string
varies
Comma-separated list of additional MQTT topics to subscribe to
Comma-separated topic names
system.service.https_port
integer
6889
HTTPS port used for local API calls such as custom filter and job trigger
Same as KestrelHttpsPort
customfilter.timeout_seconds
integer
30
Timeout in seconds for HTTP calls to custom filter jobs
Positive integer, typically 15–60
ratelimit.max_requests_per_minute
integer
100
Maximum policy evaluation requests per minute per source
Positive integer; increase if legitimate traffic is being throttled
metadata.admin.enforce_policies_for_administrators
boolean
false
When no policy matches a privilege elevation request and the requesting user is an administrator: false allows the action (OS default behavior); true denies it
false — admins are not subject to deny-by-default when no policy matches; true — admins follow the same deny-by-default as standard users
KeeperAPI Plugin
Config file: Plugins/KeeperApi.json
Used for communication with the Keeper backend — registration, policy sync, and audit.
broker.host
string
"127.0.0.1"
MQTT broker hostname
127.0.0.1 or localhost
broker.port
integer
8675
MQTT broker port
Must match MqttBrokerSettings.Port
api.base_url
string
from environment
Base URL for the Keeper backend API
Full HTTPS URL — for example, https://api.keepersecurity.com
sync.interval_minutes
integer
varies
Minutes between policy and settings sync from the backend
Positive integer, typically 15–60
KeeperLogger Plugin
Config file: Plugins/KeeperLogger.json
Controls where and how log messages are written — file output, HTTP endpoint forwarding, retention, and rotation.
logToFile
boolean
true
When true, log messages are written to a file
true or false
logFileName
string
"Log/KeeperLogger.log"
Path for the log file — relative to the plugin working directory or absolute. Supports path variables.
Valid path — for example, {approot}/Log/KeeperLogger.log
maxFileSizeMB
number
100
Maximum log file size in MB before rotation
Positive number, typically 50–500
logRetentionDays
integer
15
Number of days to keep rotated log files before deletion
Positive integer, typically 7–90
logToHttpEndpoint
boolean
false
When true, log messages are also sent to an HTTP endpoint
true or false
loggingHttpEndpoint
string
""
URL to POST log messages to when logToHttpEndpoint is true
Full HTTP or HTTPS URL, or empty
log.level
string
varies
Minimum level for messages written to file or HTTP
"Critical", "Error", "Warning", "Information", "Debug", "Trace" — use "Warning" or "Information" in production; "Debug" for troubleshooting
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 for the full flow.
metadata.redirect.enabled
boolean
configurable
When true, the LaunchPrivilegeElevation job runs the check-redirect task and evaluates the rules below. When a rule matches, the original request is denied and the targetExe is launched elevated instead. When false, check-redirect is skipped.
true to enable redirect; false for normal launch-elevated behavior only
metadata.redirect.rules
array
[]
List of redirect rules. First matching rule wins.
Array of rule objects — see below. Leave [] if no redirects are needed.
metadata.redirect.rulesPath
string
optional
Path to a file containing redirect rules, as an alternative to inline rules
Valid file path, or empty
Redirect rule fields (each object in metadata.redirect.rules):
sourceExePattern
string (regex)
Matched against the executable name in the elevation request. Case-insensitive.
Regex — use \\. for a literal dot, for example "rundll32\\.exe"
commandLinePattern
string (regex)
Matched against the full command line. Case-insensitive.
Regex — for example "ncpa\\.cpl"
elevationOnly
boolean
When true, the rule applies only to Privilege Elevation events
true for typical redirect rules
nonAdminOnly
boolean
When true, the rule applies only when the requesting user is not an administrator
true to redirect standard users only; false to redirect admins as well
targetExe
string
Plugin ID or executable name of the substitute, resolved from Jobs/bin or Plugins/bin
For example, "Keeper.NetworkConnections" — must be deployed on the endpoint
targetArguments
string
Command-line arguments for the substitute executable
Any string; often ""
KeeperClient Plugin
Config file: Plugins/KeeperClient.json
The system tray client — notifications, menu, and health checks. Many options are set under metadata.
broker.host
string
"127.0.0.1"
MQTT broker hostname
127.0.0.1
broker.port
integer
8675
MQTT broker port
Must match broker
metadata.menu.refreshIntervalMinutes
integer
5
How often the tray menu is refreshed from the API
Positive integer, typically 1–30
metadata.menu.autoRefresh
boolean
true
Whether the menu refreshes automatically on a timer
true or false
metadata.LanguageOverride
string
"DEFAULT"
Override the UI display language
"DEFAULT" or a valid culture code such as "en-US"
metadata.showInTray
boolean
true
Whether to show an icon in the system tray
true or false
keeperAgent Plugin
Config file: Plugins/keeperAgent.json
Standalone UI for managing privilege elevation and file access requests — approvals, history, and expiration.
approvalExpirationHours
integer
72
Hours after which a pending approval request expires
Positive integer, typically 24–168
approvedRequestExpirationHours
integer
24
Hours after which an approved request expires and can no longer be launched
Positive integer, typically 1–72
historyRetentionDays
integer
30
Number of days to keep history items in the UI
Positive integer, typically 7–90
maxPayloadSizeBytes
integer
1048576
Maximum payload size for messages (1 MB)
Positive integer
maxRequestItems
integer
20
Maximum number of pending request items shown
Positive integer
maxHistoryItems
integer
20
Maximum number of history items shown
Positive integer
maxExceptionMessageLength
integer
500
Maximum length of exception messages displayed
Positive integer
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.
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
Global settings (ports, paths, log level)
appsettings.json → Settings and MqttBrokerSettings
Requires service restart for port and path changes
KeeperPolicy (broker, admin fallback, rate limit)
Plugins/KeeperPolicy.json or PUT /api/PluginSettings/KeeperPolicy/{key}
Restart KeeperPolicy after changing
KeeperAPI (broker, API URL, sync interval)
Plugins/KeeperApi.json or Plugin Settings API
Restart KeeperAPI after changing
KeeperLogger (file path, retention, log level)
Plugins/KeeperLogger.json or Plugin Settings API
Restart KeeperLogger after changing
Redirect (enabled flag, rules)
Plugins/RedirectEvaluator.json or Plugin Settings API
Rule changes take effect on the next evaluation; restart not required
KeeperClient (menu, tray)
Plugins/KeeperClient.json
Restart KeeperClient to apply
keeperAgent (expiration, limits)
Plugins/keeperAgent.json
Restart keeperAgent to apply
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.
Last updated