Distributed Engine Configuration and Sizing

The distributed engine sizing guide is in development and will be available here when completed.

Requirements

Supported Windows Server OS Versions

As of Secret Server version 11.9.x:

  • Windows Server 2019 or newer is required for both the Web Server and Database Server in the minimum configuration.

  • Windows Server versions 2016-2022 are supported, with 2025 pending further QA validation.

Secret Server DEs require that one of the following two server features be installed when the Secret Server website is running on a Windows Server. This depends on which protocol is selected in the engine's callback settings. If HTTPS is selected, the HTTP activation is required. If TCP is selected, then TCP activation is required.

This is accomplished by going to one of the following in the Windows Server:

  • .NET Framework 4.5 Features > WCF Services > HTTP Activation
  • .NET Framework 4.5 Features > WCF Services > TCP Activation

If the feature is not installed, there will be an error message in the DE logs: (405) Method Not Allowed. ---> System.Net.WebException: The remote server returned an error: (405) Method Not Allowed.

Distributed Engine Installation

All interaction between the Secret Server Cloud tenant and your on-premises network uses our distributed engine service to communicate. The work tasks that distributed engine completes includes Active Directory authentication, password changing, and performing heartbeats. The machine where the engine is installed must be able to communicate outbound on port 443.

For more information, see the Distributed Engine Overview.

To install the Distributed Engine:

  1. Access Secret Server.

  2. Search for Distributed Engine. The Distributed Engine page loads.

  3. Click the Add Engine button. The Download Engine popup appears.

  4. Select the related Processor Architecture for either 64-bit or 32-bit from the dropdown list.

  5. Select the related Preconfigured Site from the dropdown list.

  6. Click Download now.

    You can install a distributed engine on your workstation or laptop for testing purposes, but for production installations, the distributed engine server should be installed on a server. Secret Server uses the distributed engine to communicate with your domain, so if your machine is turned off, users cannot log in with their domain accounts. This will also cause heartbeat and remote password changing to fail.

  7. Access your downloaded .zip file and perform an extraction to an appropriate location.

  8. Run setup.exe as an administrator to install the engine service and verify the folder location of the installation on your local machine.

  9. Go back to the Distributed Engine page. The Sites and Engines tab loads automatically.

  10. Expand the Pending Engines section. The engine you installed should appear here.

  11. Select the engine by clicking on it. Its details will automatically expand.

  12. Hover over the details of the engine and the 3-dot vertical menu appears.

  13. Select the Activate option. The Activate popup asking for confirmation will appear.

  14. Select New Site to add a new site. The Add site popup appears:

  15. Add a Site Name, select the Active checkbox and leave the Engine Callback Interval at the default 300 value.

  16. For the Site Connector, leave the Default Azure Service Bus - 11 Sites option unless otherwise directed.

  17. Click Add Site to save your changes.

  18. Access the newly created site by clicking on its name (it's a link). The Site tab loads by default.

  19. In the Site section, click Validate Connectivity. The Validate Connectivity popup appears.

  20. Set the Timeout in seconds (which represents how long, in seconds, to wait for a successful round trip from site to bus to engine and then back to site).
  21. Click Validate.

It may take several minutes for the engine to register. If it does not immediately validate, wait a few minutes and try again. If an error occurs it appears in the popup window, for example:

Configuring Engines for PowerShell Use

Secret Server can be configured to use PowerShell for several key task types:

  • Discovery

  • Heartbeat

  • Password Change

  • Script Tests

Customers using PowerShell extensively for these tasks may, however, experience high CPU usage, as PowerShell is more resource-intensive compared to cmd or bash. To address this, you can limit the number of "shells" (tasks) a user can run on a machine. These "shells" represent the tasks the engine is executing under the user account associated with the Engine Service.

This limit is controlled by the MaxShellsPerUser setting for WinRM, which PowerShell uses. You can configure this setting through Group Policy, the registry, or directly with PowerShell. If MaxShellsPerUser is set, the engine will only execute the allowed number of PowerShell tasks and queue any additional tasks in the Service Bus for later execution. If it’s not set, the engine will run tasks as normal without restriction.

In cases where PowerShell scripts are unreliable or prone to timeouts—especially under heavy loads from Secret Server—the engine may encounter issues. Since the Distributed Engine allows scripts to run for up to 15 minutes, extended timeouts can cause problems. To mitigate this, you can use the Prefetch feature, which controls how many tasks the engine can consume at one time. For instance, you could limit the number of concurrent Heartbeats by setting a specific prefetch value.

Additionally, a configuration setting allows you to match the prefetch count for all consumers that use PowerShell to the MaxShellsPerUser value. This setting can be found in the app-prefetch.config file located in the application directory.