# Policy: Create a File Redirect
**Audience:** System administrators This guide explains how to configure a **redirect** so that when a user is allowed to elevate a specific application (e.g. PowerShell 7 `pwsh.exe`), the product launches a **substitute** executable (e.g. Windows PowerShell 5.1) instead. You will set up a **Privilege Elevation** policy, a **SettingsUpdate** policy to push redirect rules, and optionally an **UpdateSettings** policy to reload settings without restarting the service. Settings can be reloaded only via **UpdateSettings** policy, **restarting the KEPM service**, or **restarting the machine**—not from terminal or scripts, because KEPM admin endpoints require the calling process to be signed like KEPM. *** ## What is a Redirect? When a **privilege elevation** request is **allowed** by policy, the product normally launches the requested executable with elevation. A **redirect** lets you **substitute a different executable** so the user gets the intended experience (e.g. a supported PowerShell version) while policy stays in control. * **Flow:** User requests elevation for Application A → policy allows it → product runs the **check-redirect** logic → if a rule matches, the product **does not** launch A and instead launches **Target B** elevated (e.g. Windows PowerShell instead of PowerShell 7). * Redirect applies only to **Privilege Elevation** events (not File Access or other event types). * Redirect rules are stored in the **RedirectEvaluator** plugin configuration (`metadata.redirect`). *** ## Redirect Requirements | Requirement | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **LaunchPrivilegeElevation job** | Must be deployed and registered. It contains the **check-redirect** task that calls RedirectEvaluator. | | **RedirectEvaluator plugin** | Plugin config must have `metadata.redirect.enabled: true` and at least one rule in `metadata.redirect.rules`. | | **Privilege Elevation policy** | A policy that **allows** (or allows with controls) the **source** application (e.g. `pwsh.exe`). Without this, the request may be denied and the LaunchPrivilegeElevation job never runs. | | **SettingsUpdate policy** | Pushes the full RedirectEvaluator JSON (including redirect rules) to endpoints so `Plugins/RedirectEvaluator.json` is updated. | | **Process Configuration Policies job** | Runs the ConfigurationPolicyProcessor, which writes SettingsUpdate policy content to plugin files. | | **Reload of plugin settings** | After the JSON file is updated, the service must use the new config. The **only** ways to reload are: **UpdateSettings** policy (triggers revert-all when policies are preprocessed), **restart KEPM service**, or **restart the machine**. KEPM admin endpoints cannot be called from terminal, PowerShell, or similar tools—the calling process must be signed with the same signature as KEPM. | | **UpdateSettings policy (optional)** | When present and preprocessed, triggers **revert-all** so settings are reloaded **without** restarting the service. | ## Rule Formatting Rules live under **metadata.redirect.rules** in the RedirectEvaluator plugin JSON. | Field | Required | Description | | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **sourceExePattern** | Yes | Regex matched against the **executable file name** only (e.g. `pwsh\.exe`, `rundll32\.exe`). Case-insensitive. Use `\\.` for a literal dot. | | **commandLinePattern** | Yes | Regex matched against the full **command line**. Case-insensitive. **Cannot be empty**—use `.*` to match any command line. | | **elevationOnly** | Yes | Set `true` for redirects (rule applies only to Privilege Elevation). | | **nonAdminOnly** | No | If `true`, rule applies only when the requesting user is **not** an administrator. | | **targetExe** | Yes | Substitute executable: full path (e.g. `C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`) or a product-known name (e.g. `Keeper.NetworkConnections`) resolved from Jobs/bin or Plugins/bin. | | **targetArguments** | No | Arguments for the substitute (often `""`). | **Important:** Both **sourceExePattern** and **commandLinePattern** must be **non-empty**. To redirect regardless of command line, use `".*"` for **commandLinePattern**. **Example rule: redirect pwsh.exe to Windows PowerShell 5.1** ``` { "sourceExePattern": "pwsh\\.exe", "commandLinePattern": ".*", "elevationOnly": true, "nonAdminOnly": false, "targetExe": "C:\\\\Windows\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe", "targetArguments": "" } ``` **Order Matters**: the **first** matching rule is used. Precise rules should precede general rules. *** {% stepper %} {% step %} **Privilege Elevation policy** You need a policy that **allows** the application you want to redirect (e.g. `pwsh.exe`). If the request is denied, the LaunchPrivilegeElevation job is not triggered and redirect never runs. 1. Create a **Privilege Elevation** policy in your management console or policy store. 2. Set **PolicyType** to `"PrivilegeElevation"`. 3. Set **Status** to `"enabled"`. 4. Configure **ApplicationCheck** (or equivalent) so it matches the **source** executable path or pattern (e.g. path containing `PowerShell\7\pwsh.exe` or a pattern your product supports). 5. Set **Controls** to allow elevation (e.g. `["ALLOW"]` or include MFA/Justify/Approval as needed). 6. Assign the policy to the right **users** and **machines** (collections). 7. Deploy/sync so the policy is on the endpoints. **Example (conceptual):** ``` { "PolicyId": "allow-pwsh-elevation", "PolicyName": "Allow PowerShell 7 elevation (redirect to 5.1)", "PolicyType": "PrivilegeElevation", "Status": "enabled", "Controls": ["ALLOW"], "Filters": { "ApplicationCheck": { "Applications": ["*pwsh*"] } } } ``` Adjust Filters and ApplicationCheck to match your product's schema (e.g. full paths, patterns, or collection-based application lists). {% endstep %} {% step %} **SettingsUpdate Policy (Redirect Rules)** This policy pushes the **full** RedirectEvaluator plugin JSON (including `metadata.redirect`) to `Plugins/RedirectEvaluator.json` on each endpoint. 1. **Build the full RedirectEvaluator JSON** you want: * Include all required plugin fields: `id`, `name`, `description`, `version`, `pluginType`, `executablePath`, `Subscription`, `metadata`, etc. (copy from an existing `Plugins/RedirectEvaluator.json` if needed.) * Set **metadata.redirect.enabled** to `true`. * Set **metadata.redirect.rules** to an array containing your rule(s) (e.g. the pwsh → Windows PowerShell rule above). 2. **Create a SettingsUpdate policy** with: * **PolicyType:** `"SettingsUpdate"`. * **Status:** `"enabled"` (or `"enforce"` per your console). * **Extension.PluginName:** `"RedirectEvaluator"`. * **Extension.Action:** `"Update"` (optional; default). * **Extension.SettingsJson:** The **entire** RedirectEvaluator plugin JSON. You can supply it either as a **string** (escape inner quotes and backslashes) or as an **object** (nested JSON). Using an **object** is supported and easier to read; the configuration processor accepts both. 3. Assign the policy to the same (or appropriate) **machine/user collections** and deploy/sync. **Example policy (management-console style with SettingsJson as object):** The following shows a real SettingsUpdate policy as created in the management console. **Extension.SettingsJson** is an **object** containing the full RedirectEvaluator plugin JSON (no need to serialize to a string). The policy may also include **Actions**, **Rules**, **UserCheck**, **MachineCheck**, **ApplicationCheck**, and other fields depending on your console. ``` { "PolicyName": "Update RedirectEvaluator settings", "PolicyType": "SettingsUpdate", "PolicyId": "9ZqDaJ4G-murRdtJTHUVvw", "Status": "enforce", "Actions": { "OnSuccess": { "Controls": [] }, "OnFailure": { "Command": "" } }, "Rules": [ { "RuleName": "UserCheck", "RuleExpressionType": "BuiltInAction", "Expression": "CheckUser()" }, { "RuleName": "MachineCheck", "RuleExpressionType": "BuiltInAction", "Expression": "CheckMachine()" }, { "RuleName": "ApplicationCheck", "RuleExpressionType": "BuiltInAction", "Expression": "CheckFile(false)" }, { "RuleName": "DateCheck", "RuleExpressionType": "BuiltInAction", "Expression": "CheckDate()" }, { "RuleName": "TimeCheck", "RuleExpressionType": "BuiltInAction", "Expression": "CheckTime()" }, { "RuleName": "DayCheck", "RuleExpressionType": "BuiltInAction", "Expression": "CheckDay()" }, { "RuleName": "CertificateCheck", "RuleExpressionType": "BuiltInAction", "Expression": "CheckCertificate()" } ], "UserCheck": ["*"], "MachineCheck": ["NSBYFNaHnhkIgVIazYhFXA"], "ApplicationCheck": ["*"], "DayCheck": [], "DateCheck": [], "TimeCheck": [], "CertificationCheck": [], "Extension": { "PluginName": "RedirectEvaluator", "Action": "Update", "SettingsJson": { "id": "RedirectEvaluator", "name": "Redirect Evaluator", "description": "...", "version": "1.0.0", "pluginType": "Executable", "executablePath": "../Jobs/bin/RedirectEvaluator/RedirectEvaluator.exe", "arguments": "--baseurl {KeeperApiBaseUrl}", "Subscription": { "Topic": "RedirectEvaluator" }, "metadata": { "redirect": { "enabled": true, "rules": [ { "sourceExePattern": "rundll32\\.exe", "commandLinePattern": "ncpa\\.cpl", "elevationOnly": true, "nonAdminOnly": false, "targetExe": "Keeper.NetworkConnections", "targetArguments": "" }, { "sourceExePattern": "Notepad\\.exe", "commandLinePattern": "WindowsApps", "elevationOnly": true, "nonAdminOnly": false, "targetExe": "C:\\\\Windows\\\\notepad.exe", "targetArguments": "" }, { "sourceExePattern": "WindowsTerminal\\.exe", "commandLinePattern": ".*", "elevationOnly": true, "nonAdminOnly": false, "targetExe": "C:\\\\Windows\\\\System32\\\\cmd.exe", "targetArguments": "" }, { "sourceExePattern": "pwsh\\.exe", "commandLinePattern": ".*", "elevationOnly": true, "nonAdminOnly": false, "targetExe": "C:\\\\Windows\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe", "targetArguments": "" } ] } } } } } ``` **Note:** `SettingsJson` must be the **full** plugin JSON (all required fields such as `id`, `name`, `executablePath`, `Subscription`, `metadata`). Using an object keeps the policy readable and avoids escaping errors. {% endstep %} {% step %} **Run Process Configuration Policies** The **Process Configuration Policies** job (ConfigurationPolicyProcessor) reads policy templates, finds **SettingsUpdate** policies, and writes **Extension.SettingsJson** to the file indicated by **PluginName** (e.g. `Plugins/RedirectEvaluator.json`). * **Schedule:** If the job is scheduled, it will run automatically; after sync, the next run will apply your SettingsUpdate policy. * **On demand:** Use the **KeeperClient "Refresh"** option. This triggers policy sync and preprocessing; the Process Configuration Policies job runs when applicable. You cannot run this job by calling KEPM endpoints from terminal or PowerShell—the calling process must be signed with the same signature as KEPM. After this step, `Plugins/RedirectEvaluator.json` on the endpoint contains your redirect rules. The running service may still be using the old in-memory config until you reload (Step 4). {% endstep %} {% step %} **Reload Plugin Settings** After the plugin JSON file is updated, the service must load the new settings. The **only** ways to reload are: 1. **UpdateSettings policy** — When policies are preprocessed (e.g. after KeeperClient Refresh or sync), an **UpdateSettings** policy triggers revert-all so plugin settings are re-imported from the current in-memory configuration into storage. See Step 5. 2. **Restart KEPM service** — Stops and starts the service; on startup, plugin config is read from disk. This always picks up the new file (and avoids config-protection/tampering issues that can block hot reload). 3. **Restart the machine** — Same effect as restarting KEPM for loading plugin config. You cannot trigger a reload from terminal, PowerShell, curl, or other unsigned tools—KEPM admin endpoints require the calling process to be signed like KEPM. {% endstep %} {% step %} **Optional: UpdateSettings Policy for Reload without Restart** To trigger a **reload of all plugin settings** (same effect as **POST /api/PluginSettings/revert-all**) **without restarting the service**, use an **UpdateSettings** policy. 1. Create a policy with **PolicyType** `"UpdateSettings"` and **Status** `"enabled"`. 2. Assign it to the same (or appropriate) machine/user collections and deploy/sync. 3. When KeeperPolicy **preprocesses** policies (e.g. after sync or GetPolicyData), it looks for **UpdateSettings** and calls the revert-all endpoint once. Plugin settings are then re-imported from the current in-memory configuration into storage. **Note:** UpdateSettings does **not** re-read the plugin JSON files from disk; it re-imports from whatever is already in the configuration provider. So for the **first** time you push a new RedirectEvaluator.json via SettingsUpdate, a **restart** is the most reliable way to load it. Use UpdateSettings for **subsequent** reloads when the config is already loaded (e.g. after a previous restart or when the file watcher successfully reloaded the file). {% endstep %} {% endstepper %} ### Calling KEPM Endpoints from Terminal or Scripts KEPM admin endpoints (including **POST /api/PluginSettings/revert-all** and **POST /api/PluginSettings/{pluginName}/revert**) use **process authentication**: the calling process must be signed with the same signature as KEPM and must pass validation (e.g. launched by or trusted like KeeperPrivilegeManager). Terminal, PowerShell, cmd, curl, and similar tools are **not** signed and will receive **403** when calling these endpoints. There is therefore **no** way to trigger a settings reload from a script or terminal—only **UpdateSettings** policy, **restart KEPM service**, or **restart the machine**. *** ### Limitations | Limitation | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Privilege Elevation only** | Redirect is evaluated only for **Privilege Elevation** events. File Access and other event types do **not** run the redirect logic. | | **Both patterns required** | **sourceExePattern** and **commandLinePattern** must both be **non-empty**. To match any command line, use `".*"`. | | **Policy must allow first** | The elevation request must be **allowed** by a Privilege Elevation policy. If the request is denied, LaunchPrivilegeElevation is not triggered and redirect is never evaluated. | | **Config file tampering protection** | If the product detects that `Plugins/RedirectEvaluator.json` was modified after initial load (tampering protection), it may **skip** loading that file on hot reload. In that case, the only way to apply the new rules is to **restart the KEPM service** (so the file is read at startup with no previous hash). Pushing settings via the management console into **Unified Storage** (e.g. PUT /api/PluginSettings/RedirectEvaluator/metadata) can provide new rules without relying on the on-disk file. | | **Target executable** | **targetExe** must be a path or a product-known name that resolves to a path under Jobs/bin or Plugins/bin. The substitute must exist and be launchable on the endpoint. | | **First matching rule** | Only the **first** rule that matches (by exe name, command line, event type, and optionally nonAdminOnly) is used. Order rules from most specific to least specific. | | **Revert vs. disk** | **POST revert-all** and **POST …/revert** re-import from the **current in-memory** plugin configuration into Unified Storage. They do **not** re-read the JSON files from disk. If the on-disk file was updated but not loaded (e.g. tampering), restart is required to use the new file. | | **UpdateSettings policy** | The **UpdateSettings** policy type triggers revert-all when preprocessing runs; it does not re-read plugin JSON from disk. Use it to reload already-loaded config without restart, not to load a never-before-loaded file. | | **No API from terminal/scripts** | Admin endpoints (revert-all, revert, job run, etc.) require the calling process to be signed like KEPM. Terminal, PowerShell, and curl cannot call them. | *** ### Related documentation * [Reference: Redirect](https://docs.keeper.io/en/keeperpam/endpoint-privilege-manager/reference/redirect-capability) — Redirect capability and rule fields. * [Example: Creating a Policy to set Settings](https://docs.keeper.io/en/keeperpam/endpoint-privilege-manager/examples/advanced-examples/policy-create-a-policy-to-set-settings) — SettingsUpdate policy and Process Configuration Policies job. * [Reference: Plugin & Task Settings](https://docs.keeper.io/en/keeperpam/endpoint-privilege-manager/reference/plugin-and-task-settings) — Plugin settings API, revert-all, and revert.