← Uninstalling Redwood Server Platform Agents from UNIXFile Events on Microsoft Windows Process Servers →

Creating a Microsoft Windows Process Server

note

Microsoft 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.

Microsoft Windows processes are executed by a platform agent that is installed on the Microsoft Windows server where you want the process executed. It executes the code in the process definition in a specific environment as a specific user. The platform agent may run on the same machine as the Redwood Server, or on any other machine on the network.

The installer unpacks the software, sets up a service on the local system and registers it with a Redwood Server. Once the installer is finished, you will have a running platform agent service on the target machine and a process server in the Redwood Server, if you registered it. You can choose not to register the platform agent with the central Redwood Server. However, you will have to manually setup a process server in Redwood 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. More details can be found in the Configuring Platform Agents on Microsoft Cluster Nodes section.

note

You must install the Redwood Server platform agent on a local file system; SAN file systems might be considered local, when they are mounted as iSCSI, for example.

Structure

On Microsoft Windows the 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 is monitoring that the network-processor.exe does not die undetected is performed by the Microsoft Service Controller.

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

Signed Binaries

The platform agent installer package (the self-extracting archive) is not signed, the binaries therein are signed. If you are prevented from executing unsigned binaries, you can extract the binaries into <installation_path> using other tools, such as signed versions of Winzip, Winrar or 7zip, and install the jtool utilities by running jtool install. You use servicemanager.exe to create the platform agent instance, it will use the provided properties file to create the necessary platform agent.

  1. Copy the ZIP archive to the destination server.
  2. Extract the contents to the desired installation directory.
  3. Start servicemanager.exe, choose Install, it will use the provided properties file to create the process server.

Example Extracting the ZIP Archive using GNU zip

$ zip -FJ platform-agent-windows-x86-2023.2.0-20231002_11-Agent.exe --out agent.zip

See the following topics for more information:

Installer Usage

The Windows platform agent installer accepts the following arguments, if you specify -u, you have to specify all the others as well for unattended installation. 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>
ArgumentDescriptionExample
-ac, -enable-server-acl <Y/N>Lock the platform agent to the current central Redwood Server.-ac Y
-ai, -agent-initiatedAgent initiated mode, the platform agent initiates the connection to the central Redwood server.-ai
-b, -enable-autoboot <Y/N>Enable automatic startup of the platform agent service.-b Y
-bin <path>(obsolete)

-d, -destination <destination_directory>Destination (installation path).-d D:/redwood/agent
-f <log_file>Full path to log file.-f D:/redwood/installer.log
-forceOverwrite any files without prompting.--force
-i, -instance <instance_name>[:<port>]Instance name and port; the port in the instance name will be used by the platform agent (except for agent-initiated agents).-i prd-a1234:8080
-l <level>Verbosity level, defaults to info (supports none, fatal, error, warn, info, debug, net, or trace; in order of verbosity).-l debug
-pr, -proxy <user:password@host:port>Proxy server information.-pr https://pxuser:horseStackMonkey@gatekeeper.local:80
-ps, -process-server [<partition>.]<process_server_name>Desired name of the process server in Redwood Server, used for platform agent registration.-ps MSLN_WINS1
-pw, -password <password>Redwood Server users' password, used for platform agent registration.-pw horseStackPompey
-ql, -queue-list <queue_list>Comma-separated list of queues for the process server, used for platform agent registration.-ql "WIN,SQL Server"
-rs, -registration-server <url>URL of the central Redwood Server, used for platform agent registration.https://pr1.example.com:50300/redwood
-s, -silentNo output on screen unless a proxy server is required and insufficient proxy server information was provided-s
-simplifiedDo a simplified installation with the values provided-simplified
-u, -unattendedUnattended mode can be used in in shell scripts. This is non-silent.-u
-un, -username <username>Redwood Server username, needs to have the scheduler-administrator role, used for platform agent registration.-un Administrator
-?, -helpShow usage information-?

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

The long command line arguments, such as -enable-server-acl, can also be specified with two leading dashes --enable-server-acl; just like on UNIX.

Installer Prompts

The installer may prompt when 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.

FieldDescription
Instance nameInstance name for the agent; the name is limited to characters supported as a folder name.
PortAn unused local port.

The Registration prompt will appear when the process server needs to be registered.

FieldDescription
Server URLThis is the value of the ContextURL registry entry by default or the value passed with the -rs
UsernameUser with administration privileges to create the process server
PasswordPassword for the admin user
Process server nameName of the process server to register
Queue listcomma-separated list of queues the process server will be serving
Lock agent to server systemPrevent other Redwood Servers from connecting to this platform agent

The proxy server prompt will appear when the central Redwood Server cannot be reached over the network, this can also be the sign of a network outage during installation.

FieldDescription
ServerProxy server to use
PortPort number the proxy server is using (defaults to 3128)
UsernameUser for proxy server (check the checkbox to fill this field)
PasswordPassword for proxy server

Long Path Names

You can switch long path support off for Redwood Server 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 Redwood Server-specific and does not alter the behavior on Windows for other programs.

Windows Service Log On Account

The service must 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 agent.
    • Manually updating the agent 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.
    • You will not be able to execute any Excel Macros from within processes, for example.

Note that this applies to the agent, not the processes. There are mechanisms that allow precise control over which accounts are used to run jobs, including black or white lists of account names.

RDP and Console Sessions

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

Two new system process definitions are available to create/destroy RDP sessions:

Example

To create an RDP session as user jdoe and log off again at the end of execution, you 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, however, always retain a backup of the original session.rdp file.

Manual Service Creation

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, has to be unique! It is highly recommended you stick to this naming convention.
  • <install_dir> - 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> - version number with _ instead of., for example: 9_1_2_3.
  • <instance> - instance name as defined during installation of the platform agent; this will be used to retrieve the settings of the agent.
  • <SID> - SAP SID, example: PR1_30.
  • <process_server_name> - the name of the process server in Redwood Server.
  • <some_userfriendly_name> - a user-friendly name, will be displayed in services.msc, for example. Used as the description of the service; spaces must be quoted.
  • <log_level> - verbosity-level to use, see agent logging levels for syntax.
note

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

Example

You are tasked to replicate a platform agent installation directory to a new server and create a service for the default instance on a server. You have already performed the replication, 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_20231002_18\\bin\\network-processor.exe" -i default -f "C:\\redwood\\agent\\var\\SAP_PR1_30\\MSLN_WINS3\\trc\\MSLN_WINS3-${ProcessName}-${TimeStamp}-${ProcessId}.log". Windows quoting rules are quite simple, you surround quotes that are to 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 an agent:

C:\Windows\system32>sc create jcs_default binPath= """"C:\redwood\agent\2023_2_0_20231002_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 an agent with logging (all categories of the job-processor at level debug):

C:\Windows\system32>sc create jcs_default binPath= """"C:\redwood\agent\2023_2_0_20231002_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

  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, if the new services 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 (Terminal Services, vnc, pcAnywhere) access to the system.
  • Local administrative privileges on the Microsoft Windows server to create a service.
  • Administrative privileges in Redwood Server to register the platform agent or create the process server.
  • The 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 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

Install the Platform Agent

  1. Navigate to "Configuration > Software".
  2. Download the windows-x86 executable and copy it to the appropriate machine (if necessary).
  3. Run that executable on the Microsoft Windows system. The installer uses C:\\Program Files (x86)\\Redwood\\agent by default; to override this you specify -d <installation_dir on the command line.
    1. For example: platform-agent-windows-x86-2023_2_0_20231002_14.exe -d "G:\\redwood\\agent"".
  4. Select the language to use for installation.
  5. Enter a Preferred instance name (referred to as ${instance}), a Port, whether to enable auto-update and optionally an Account. Enabling auto-update and always running the platform agent using the system account is recommended. Choose OK.
  6. Optionally (but strongly recommended, except for cluster environments) you can register the platform agent by creating a new process server. Enter the FQDN (Fully Qualified Domain Name) of the central Redwood Server in the Server field and its port. You can enter a name for the process server which will be used throughout Redwood Server. 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). Choose OK.
  7. You will now be asked to log into the central Redwood Server so the installer can create and configure your process server inside Redwood Server, this step must be skipped when you are installing on a cluster. You must use an account which has the scheduler-administrator role or equivalent privileges in Redwood Server.

Further configuration instructions can be found in the Configuring Remote Agents section.

Configuring a Firewall

If you run 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. As the network-processor runs as a service, your firewall program may not show a pop-up that allows you to add this rule interactively. If you are running a firewall and no such notice popped-up during installation (when the service was started), add the rule manually.

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

Creating the Process Server

This step is required when you install on a cluster. You should not do this if you registered the process server during installation.

Automatic Updating

The Microsoft Windows platform agent supports Automatic Updating.

If the service runs as the Local System (NT Authority\\System) account the agent is capable of being updated automatically. If the administrator needs 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, ensure you have deleted all processes and chains that ran on the process server, and 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. Find the install 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}.

See Also

← Uninstalling Redwood Server Platform Agents from UNIXFile Events on Microsoft Windows Process Servers →