Creating a Windows Process Server

Note: Windows Process Servers that schedule native workload and/or use file events are only available when your license includes a non-zero value for the key ProcessServerService.OS.limit. The value of this key determines how many Platform Agents (across all platforms) you can run. Monitoring-only Windows and UNIX Platform Agents are free of charge and do not count towards this license key.

Windows processes are executed by a Platform Agent installed on the Windows computer where the processes execute. The Platform Agent executes the code in a Process Definition in a specific environment as a specific user.

The Platform Agent installer unpacks the software, then sets up a service on the local system and registers it with the RunMyJobs server. Once the installer is done, you will have a running Platform Agent service on the target machine and a Process Server in the RunMyJobs server (if you registered the Platform Agent). You can choose not to register the Platform Agent with RunMyJobs, but that would mean you must manually set up a Process Server and configure it to connect to the Platform Agent.

Platform-independent configuration instructions can be found in the Configuring Platform Agents section.

The Platform Agent is compatible with Microsoft Cluster Service, and can be configured on cluster nodes to be highly available.

Note: You must install Platform Agents on a local file system. SAN file systems may be considered local (if they are mounted as iSCSI, for example). NFS and Windows shares are not supported because they may not be available at all times.

Structure

On Windows, a Platform Agent is automatically started by the Windows Service Controller. It starts a service with display name Scheduler Platform Agent ${instance} ${version} and service name jcs_${instance}. The service executable, which you will find in tools such as the Task Manager, is network-processor.exe. There is no intermediary program called platform-agent as on UNIX. The role of the platform-agent script (which makes sure the network-processor process does not die undetected) is performed by the Microsoft Service Controller.

For each process, a job-processor.exe instance is started. It will run under the account set via the Run As User credentials.

Circumventing Digital Signature Verification (Windows only)

If you cannot run the Windows Platform Agent installer (for example, because it is not digitally signed), you can use any ZIP utility (for example, WinZip, 7-Zip, or WinRAR) to extract the archive from the self-extracting executable. Use the following procedure.

1. Copy the ZIP archive to the destination server.

2. Extract the contents to the desired installation directory. The decompressed archive will contain a folder with the name of the installer and a file named register.properties. This file contains the configuration information you entered when you created the Platform Agent installer in the Process Server wizard.

3. Start servicemanager.exe and choose Install. The installer will use the provided properties file to create the Platform Agent.

Installer Usage

The Windows Platform Agent installer accepts the following arguments. Arguments have a short spelling that require one hyphen, like -u, and a long one, like --unattended, which requires two hyphens.

platform-agent-windows-x86-<version>.exe <arguments>

Note: If you specify -u for unattended installation, you must specify all the others as well.

TLS Environment Variables

Note: The Platform Agent must be installed by a user who has the right to create services. Redwood recommends using a user who has local administrator privileges.

Note: Long command line arguments, such as -enable-server-acl, can also be specified with two leading dashes (e.g., --enable-server-acl), just as on UNIX.

Installer Prompts

The installer may prompt if you do not specify -u or -s switches.

The instance prompt will appear in server-initiated setups when an instance with the same name exists or the port is in use.

The Registration prompt will appear when the Process Server needs to be registered.

The proxy server prompt will display if RunMyJobs cannot be reached over the network. This can also be the sign of a network outage during installation.

Long Path Names

You can switch long path support off for RunMyJobs on Windows 2008, 2012, 2012 R2, 10, 2016, and 2019 by setting the JCS_LONG_PATH environment variable system-wide to false. This environment variable is specific to RunMyJobs and does not alter the behavior of other programs.

Windows Service Log On Account

The service can run as either NT Authority\System (Local System) or as a user with local Administrator privileges.

The service must run as Local System, unless:

• You do not need automatic update of the Platform Agent. (Note that manually updating Platform Agents is error-prone and time-consuming).
• You do not need to run processes under accounts other than what the service runs as.
• You do not need to run processes that automate user actions that require a desktop. For example, you cannot execute Excel Macros from within processes.

Note that this applies to the Platform Agent, not the processes it runs. There are mechanisms that allow precise control over which accounts are used to run jobs, including account name blacklists and whitelists.

RDP and Console Sessions

You can specify a console or RDP session using the {console} and {session} keywords, respectively, in the Run As User field of a Process Definition. Note that if no active session exists for the specified user, the process will fail . To create and destroy a console or RDP session, specify the {logon} and {logoff} keywords, respectively.

Two system Process Definitions are available to create and destroy RDP sessions.

• System_Windows_Session_Close: Closes a specific session opened by System_Windows_Session_Create.
• System_Windows_Session_Create: Creates a terminal services session per specified user.

Example

To create an RDP session as user jdoe and log off at the end of execution, specify the following in the Run As User field.

{logon}{session}{logoff}jdoe

The session is created if there is none for the specified user. The configuration file used to create the RDP session is stored in <install_dir>\<version>\etc\session.rdp. An RDP file is created for each user and stored at the same location with the name <domain>-<user>.rdp. You can tailor the session file to suit your needs, but always retain a backup of the original session.rdp file.

Manual Service Creation

Assume that you want to create a new Windows service manually from the command line using the SC command. The Windows Platform Agent service takes a number of arguments that need to be specified in the binPath argument to sc, as follows (command to be issued on one line):

C:\Windows\system32>sc create <technical_name> binPath= """"<install_dir>\<version>\bin\network-processor.exe""" -i <instance>
-f """<install_dir>\var\SAP_<SID>\<process_server_name>\trc\<process_server_name>-${ProcessName}-${TimeStamp}-${ProcessId}.log"""" DisplayName= <some_userfriendly_name>
[-l <log-level>]

• <technical_name>: Scheduler Service Manager uses jcs_<instance_name> and defaults to jcs_default. The technical name must be unique. Redwood recommends sticking to this naming convention.
• <install_dir>: The installation directory. For example c:\\redwood\\agent. The default on MS Windows Vista and later is c:\\Program Files (x86)\\Redwood\\agent. Use -d or --destination on the command line to specify an installation directory, ideally on a data drive (not C:\\).
• <version>: The version number, with _ instead of .. For example: 9_1_2_3.
• <instance>: The instance name, as defined during installation of the Platform Agent. This will be used to retrieve the Platform Agent's settings.
• <SID>: The SAP SID. For example: PR1_30.
• <process_server_name>: The name of the Process Server in RunMyJobs.
• <some_userfriendly_name>: A user-friendly name. This name is displayed in services.msc, for example. It is also used as the description of the service. Spaces must be quoted.
• <log_level>: The log verbosity level. For syntax, see Platform Agent logging levels.

Note: The space after the equals sign (=) is mandatory for sc.

Example

Assume you need to replicate a Platform Agent installation directory to a new server and create a service for the default instance on that server. You have already performed the replication, and the directory structure is located in the same local hierarchy as the source server. You inspect the service on the source server with services.msc and notice the service calls "C:\\redwood\\agent\\2023_2_0_20230727_18\\bin\\network-processor.exe" -i default -f "C:\\redwood\\agent\\var\\SAP_PR1_30\\MSLN_WINS3\\trc\\MSLN_WINS3-${ProcessName}-${TimeStamp}-${ProcessId}.log". On Windows, you must surround quotes that should be escaped with quotes, so, " becomes """, and "" becomes """". Note that the binPath argument takes one value and in this case needs to be quoted.

The following call to sc creates a Windows service for a Platform Agent.

C:\Windows\system32>sc create jcs_default binPath= """"C:\redwood\agent\2023_2_0_20230727_18\bin\network-processor.exe""" -i default
-f """C:\redwood\agent\var\SAP_PR1_30\MSLN_WINS3\trc\MSLN_WINS3-${ProcessName}-${TimeStamp}-${ProcessId}.log"""" DisplayName= "Redwood Server Platform Agent Service"

The following call to Sc creates a Windows service for a Platform Agent with logging, with all categories of the job-processor at level debug.

C:\Windows\system32>sc create jcs_default binPath= """"C:\redwood\agent\2023_2_0_20230727_18\bin\network-processor.exe""" -i default
-f """C:\redwood\agent\var\SAP_PR1_30\MSLN_WINS3\trc\MSLN_WINS3-${ProcessName}-${TimeStamp}-${ProcessId}.log""" -l job-processor.*=debug" DisplayName= "Redwood Server Platform Agent Service"

Note that CMD.EXE must be run as Administrator with escalated privileges to create the service.

Renaming a Service

To rename a service:

1. Stop the old service.
2. Copy ${InstallDir}/net/instance/${Old} to ${InstallDir}/net/instance/${New}.
3. Create a service for instance ${New} using the Manual Service Creation instructions above.
4. Start the new service.
5. If the new service works, disable the old service. It can be removed if required.

Prerequisites

• Windows 2008, 2012, 2012 R2, 10, 2016, or 2019 with the latest Service Pack.
• Physical or remote access to the system.
• Local administrative privileges on the Windows computer to create a service.
• Administrative privileges in RunMyJobs, so you can register a Platform Agent and create a Process Server.
• The Platform Agent must run locally as either NT Authority\System (Local System) or as a user with local Administrator privileges.
• Platform Process Servers that schedule workload or use file events require at least one of the following license keys:
  • ProcessServerService.External.limit: The total number of external Process Servers (Platform Agents, distinct web service endpoints, and SAP connectors).
  • ProcessServerService.OS.limit: The total number of Platform Agent Process Servers.

Note: Both license keys must be honored if present. Their presence depends on your contract. The most restrictive applies.

Procedure

Installing a Platform Agent

1. Navigate to Configuration > Software.
2. Download the windows-x86 executable and copy it to the appropriate machine (if necessary).
3. Run the executable on the Windows. The installer uses C:\\Program Files (x86)\\Redwood\\agent by default. To override this, specify -d <installation_dir on the command line. For example: platform-agent-windows-x86-2023_2_0_20230727_14.exe -d "G:\\redwood\\agent"".
4. Select the language to use for installation.
5. Enter a Preferred instance name (referred to as ${instance}) and a Port. Indicate whether to enable auto-update, and optionally enter an Account. Redwood recommends enabling auto-update and always running the Platform Agent using the system account.
6. Click OK.
7. You can optionally register the Platform Agent by creating a new Process Server. Redwood recommends this unless you are in a cluster environment. Enter the FQDN and port of the RunMyJobs instance in the Server field. You can also enter a name for the Process Server, which will then be used throughout RunMyJobs. The default name is the instance name. You can also specify a list of Queues that this Process Server will be serving (comma-separated, without spaces).
8. Click OK.
9. You will now be asked to log into RunMyJobs so the installer can create and configure your Process Server. This step must be skipped if you are installing on a cluster. You must use an account which has the scheduler-administrator role or equivalent privileges in RunMyJobs.

For more configuration instructions, see Configuring Remote Agents.

Configuring a Firewall

If you use a firewall, add a rule to allow incoming connections on the port that you defined during the installation for program ${InstallDir}/bin/network-processor.exe. Because the network-processor process runs as a service, your firewall program may not show a pop-up that lets add this rule interactively. If you are running a firewall and no such notice pops-up during installation (when the service was started), you can add the rule manually, as follows.

1. Navigate to Start > Control Panel > Network Connections.
2. Choose Properties from the context menu of the desired adapter.
3. Click the Advanced tab.
4. Click Settings.
5. Click the Exceptions tab.
6. Add either a program ${InstallDir}\\bin\\network-processor.exe or port 1555.
7. Click OK twice.

Creating the Process Server

This step is required if you install on a cluster. Do not this if you registered the Process Server during installation.

• Navigate to Environment > Process Servers.
• Click .
• See Configuration of a Microsoft Windows Process Server for configuration data.

Automatic Updating

The Microsoft Windows Platform Agent supports Automatic Updating. If the service runs as the Local System (NT Authority\\System) account, the Platform Agent is capable of being updated automatically. If you need to change the setting at a later date you can do this as follows:

• To disable auto-update, remove the ${InstallDir}\\etc\\startup\\${instance}\\autoupdate directory.
• To enable auto-update, create the ${InstallDir}\\etc\\startup\\${instance}\\autoupdate directory and change the service so it runs as Local System by starting the Microsoft Windows Service Manager (services.msc) and modifying the Log On dialog of the Scheduler Platform Agent service.

Removing the Service and Software

Prior to removing the Platform Agent service and software, delete all Process Definitions and Chain Definitions that ran on the Process Server, and then delete the Process Server itself.

There is no automated process for removing the service and software. However, the following will remove the service and software.

1. Locate the installation directory of the Platform Agent. This is ${InstallDir} (defaults to C:\\Program Files (x86)\\Redwood\\agent).
2. Use the Redwood Service Manager at ${InstallDir}\\bin\\servicemanager.exe to stop and remove all running services.
3. Remove the installation directory ${InstallDir}.