Running remote actions as a service on server devices (Windows only)

If a remote action needs specific Windows credentials to interact with a service, Nexthink provides a dedicated feature that allows it to run within the context of a specially configured service.

Nexthink Library includes remote actions that leverage this ability, including:

Adding/removing a user to/from an Active Directory group.
Adding/removing a device to/from an Active Directory group.

These remote actions are then used in workflows for various use cases.

Remote actions that run as a service are designed for use on Windows Server devices that serve as bastion devices to interact with on-prem servers securely. It is necessary to perform additional setup tasks on Windows Service devices before configuring and operating service remote actions.

Additionally, due to the sensitive nature of remote actions, Nexthink recommends leveraging Nexthink features to limit their use:

Selectively share the remote action only with users allowed to run it, if any.
Set up a dedicated entity for the bastion server, and limit the roles able to run remote actions on this device.

Setting up the target Windows Server

Requirements

Nexthink recommends using Windows Server 2019.

Deploy and configure Nexthink Collector (version 24.5 or later) on the device using the standard process.

Create a user account, typically a service account, that will be used to execute scripts within the service:

Ensure the account has the necessary permissions to successfully execute the planned remote actions. Make sure to apply security best practices by giving that service account the least privileges possible. Examples of best practices include:
Ensure that the relevant PowerShell modules are installed, if applicable. For example, for the Nexthink Library remote action to interact with ActiveDirectory, you must install the ActiveDirectory module using this command line in PowerShell: Install-WindowsFeature RSAT-AD-PowerShell
Ensure the account has write permissions to the following folder, where its logs are stored: c:\ProgramData\Nexthink\Logs\User\ c:\ProgramData\Nexthink\RemoteActions\Scripts\Service
Ensure the account has the permission to run PowerShell scripts from the following folder: c:\ProgramData\Nexthink\RemoteActions\Scripts\Service
Ensure the account can log on as a service on the machine, based on the local security policy. For local users, perform the following steps in the Local Computer Policy manager: Navigate to Computer Configuration > Windows Settings > Security Settings > Local Policies > User Rights Assignment, and verify that the user or groups the user belongs to are included in the Log on as a service policy.

To further secure the server and precisely control which scripts can run on the device, Nexthink recommends following best practices:

Set the collector execution policy for remote actions to trusted.
Use a dedicated code signing certificate that you will use for those remote actions that should be executed on the Windows server device and deploy the code signing certificates that you plan to use in the Local Computer > Trusted Publishers certificate store. Refer to the Writing scripts for remote actions on Windows documentation for more information.

Install, create and run the service

Follow these steps to configure the service used to execute the remote action:

Register the service: As a local administrator, run the following commands: sc create "nxtcod_service" binpath= "\"C:\Program Files\Nexthink\Collector\Coordinator\nxtcod.exe\" --service-name \"nxtcod_service\" --queue-size 512 --max-concurrent-script-executions 4" DisplayName= "Nexthink RA Execution as a Service" start= auto sc description "nxtcod_service" "Run Nexthink remote actions in a dedicated service account context"
Notes:
1. The parameter --service-name is mandatory and its value nxtcod_service must be used when configuring the remote action. Nexthink recommends using the same value as the service itself. The value must consist of letters, digits, and _ only, with a maximum length of 50 characters. Not providing this argument, or providing an invalid value prevents the service from starting.
2. The service supports additional parameters, --queue-size and --max-concurrent-script-executions, to control the accepted load. Refer to the section below for more information.
Finalize the service configuration: Use the management console:
1. Open the Services management console services.msc.
2. Locate and double-click on the service created in Step 1 Nexthink RA Execution as a Service to edit its properties.
3. In the Log On tab, configure the account to be used for the service by entering the account name and its password. This account must have the required permissions to perform the desired operations for the remote action scripts you plan to use.
4. In the Recovery tab, configure the recovery option to ensure that the service restarts in case of failure. Nexthink recommends restarting the service upon any failure using the following parameters:
Start the service: Click on Start in the General tab of the service, or as a local administrator, run the following command: sc start "nxtcod_service"

Running additional service instances to use different users

Create additional instances of the service to support running remote actions with different credentials on the same device.

To configure additional services, follow the same steps as above, with the following adjustment:

Create the additional service instance using command lines similar to those used for the first service, but use a different service name and display name. Adjust the command line parameters accordingly: sc create "nxtcod_service_bis" binpath= "\"C:\Program Files\Nexthink\Collector\Coordinator\nxtcod.exe\" --service-name \"nxtcod_service_bis\" --queue-size 512 --max-concurrent-script-executions 4" DisplayName= "Nexthink RA Execution as a Service (2)" start= auto sc description "nxtcod_service_bis" "Run Nexthink remote actions in a dedicated service account context (2)"
Configure and start the service using the previous steps.

Update and uninstallation of the service

When updating Collector, the service executable is also updated. Restart the service after updating Collector to ensure it's using the latest version.

Before uninstalling Collector, stop all instances of the service. Failure to do so results in errors during the uninstallation process.

Monitoring the expected load

In typical workflow scenarios, the same server processes a large number of remote actions to handle each required user or device. The server queues the requests and process them sequentially, with a specified number of threads working in parallel.

To align with your expected throughput of remote action executions on the bastion server, configure using command line parameters:

The queue length: Parameter --queue-size, default: 128; recommended: 1024; maximum: 100000.
The number of parallel remote actions executed within the service: Parameter --max-concurrent-script-executions, default: 2; recommended: 4; maximum recommended: number of cores of the server.

Leverage the data collected by Nexthink Collector to ensure that you do not exceed the limit.

Check the average CPU usage and memory usage of the server to verify that they are not exhausted:

device_performance.events past 24h
| where device.name == "<proxy-device-name>"
| summarize avg_cpu_usage = cpu_usage.avg() / number_of_logical_processors.avg(), avg_free_memory = free_memory.avg() by 1h
| where avg_cpu_usage >= 80 or avg_free_memory <= 1GB

Check that remote action executions are not failing or timing out by running the following NQL query:
```
remote_action.executions past 7d
| where remote_action.name in ["<service-remote-action-names>"]
| summarize total_executions = count(), in_progress = countif(status == in_progress), expired = countif(status == expired), success = countif(status == success), failure = countif(status == failure) by 1d, device.name
```
- If the In progress numbers are higher than the maximum queue size, consider increasing the value of the --queue-size parameter.
- If the Expired numbers are increasing, consider increasing the value of the --max-concurrent-script-executions parameter.

Troubleshooting errors

Symptom Troubleshooting

Symptom	Troubleshooting
Error when starting the service: The `<ServiceName>` service on Local Computer service started and then stopped.	Check the Windows Event log for the relevant error message: A common cause is missing the mandatory command line argument `--service-name`. Use the following steps to verify the issue and remediate it: Edit the service from the Services management console. Verify that the value in Path to executable is correctly included in the command line `--service-name "somevalue"` and that `somevalue` contains only letters, digits or `_` and has a length of at most 50 characters. To modify the executable and its parameters, run this command as a local administrator to modify the command line arguments: `sc config "nxtcod_service" binpath= "\"C:\Program Files\Nexthink\Collector\Coordinator\nxtcod.exe\" --service-name \"service_1\" --queue-size 512 --max-concurrent-script-executions 4"`.
Error when running the remote action: The service is not found.	Verify that the value for the service name configured in the remote action Script tab, e.g. `service_1`, matches the value configured for the `--service-name` argument set up for the service: Edit the service from the Services management console. Verify that the value in Path to executable has an argument `--service-name "service_1"` that matches the value used in the remote action configuration. Follow the same instructions as above to modify the command line.

Error when starting the service: The <ServiceName> service on Local Computer service started and then stopped.

Check the Windows Event log for the relevant error message:

A common cause is missing the mandatory command line argument --service-name. Use the following steps to verify the issue and remediate it:

Edit the service from the Services management console.
Verify that the value in Path to executable is correctly included in the command line --service-name "somevalue" and that somevalue contains only letters, digits or _ and has a length of at most 50 characters.
To modify the executable and its parameters, run this command as a local administrator to modify the command line arguments: sc config "nxtcod_service" binpath= "\"C:\Program Files\Nexthink\Collector\Coordinator\nxtcod.exe\" --service-name \"service_1\" --queue-size 512 --max-concurrent-script-executions 4".

Error when running the remote action: The service is not found.

Verify that the value for the service name configured in the remote action Script tab, e.g. service_1, matches the value configured for the --service-name argument set up for the service:

Edit the service from the Services management console.
Verify that the value in Path to executable has an argument --service-name "service_1" that matches the value used in the remote action configuration.
Follow the same instructions as above to modify the command line.

Last updated 10 days ago