Configuring Agentless Process Servers

A normal configuration for running native OS jobs consists of two separate parts: a process server in the central Redwood Server system where OS jobs are represented by processes and a platform agent on the native system where you want to run the native OS job.

If you have a requirement to run native OS jobs on (many) servers where you do not want to install or are not able to install a Redwood Server platform agent you can do this by configuring an agentless process server.

Agentless is supported for UNIX and Microsoft Windows native OS jobs. It functions by using a proxy platform agent which will receive the OS job instructions and then forward these on to the actual (target) server that the OS job will be executed on. The proxy agent connects to the target server by means of SSH (UNIX) or WMI (Microsoft Windows).

This means that you must configure at least one normal UNIX process server and platform agent if you want to run agentless UNIX jobs and/or one normal Microsoft Windows process server and platform agent if you want to run agentless Microsoft Windows jobs.

Prerequisites

• UNIX Proxy Process Server system needs an ssh client, needs to be able to reach the target server on the default ssh port 22.
  • target system needs an ssh server running on the default ssh port 22.
• Windows proxy process server system needs to access target system on RPC and WMI ports. Note that WMI uses port ranges.
  • A temporary SMB network share will be created on the proxy platform agent and accessed by the target system; port 445.

Configuring the process server

Running OS jobs on a server still requires a process server per host, just as for running OS jobs with a platform agent. The process server must be configured with the following parameters:

Parameter	Value	Use
Agentless	true	Toggle that specifies that this is an agentless process server
RemoteHostName	...	The hostname of the server that the OS job will run on
ProxyProcessServers	null	Optional comma separated list of process servers that will function as a proxy

If ProxyProcessServers is null the list of valid proxy process servers is filled with all non-agentless process servers that provide the definition type of the process. If ProxyProcessServers is not null its value is used as the list. In either case the first process server from the list that is running will be used as the proxy.

Process Server Parameters supported for agentless process servers:

• RemoteHostName
• EndPoint
• LowVolume
• DefaultRunAsUser
• CygwinInstallPath (Microsoft Windows only)
• LocalInterpreter_XXX
• InterpreterWhitelist_XXX

All others do not apply or the values from the proxy process server are used.

Special considerations for UNIX Jobs

If you want to run UNIX OS jobs remotely please consider the following restrictions:

1. The proxy server (with the platform agent) must possess an ssh client.
2. The server that the OS job will run on must possess a working ssh server (daemon).
3. If the process definition does not have a full set of credentials (username + password) the SSH connection will be tried using the username, or if that is not set, the default user that OS jobs run as on the proxy host. In such a case the system will use the authorized_keys mechanism.

Special Considerations for Microsoft Windows Jobs

1. The proxy server and the target server must both have WMI active and configured. This is true of default Microsoft Windows Server installations, but your system administrator may have disabled WMI.
2. Both servers must belong to the same domain or there must be a trust relationship between the domains of the servers.
3. The process definition must have a full set of authorization including a password. This can be done by setting the Run As User field with a username or domain\username, with either a password in the Run As User field or in a credential object.
4. The user specified in the authorization must be an administrator account on the target server.
5. Enable incoming WMI and DCOM connections in the firewall on the target server. If using the built-in Windows Firewall, enable the following inbound rules on the target server:
   1. Windows Management Instrumentation (DCOM-In).
   2. Windows Management Instrumentation (WMI-In).
6. The proxy server must allow file sharing to the target server. As part of the OS job a temporary network file share is created on the target server to the output and log files on the proxy server.

If you get a WMI connection failure, especially if accompanied by error code 0x800706ba, ensure that you have created the firewall exceptions as indicated in item 5. See System Administration > Windows Management Instrumentation > Using WMI > Creating WMI Clients > Connecting to WMI on a Remote Computer > Connecting Through Windows Firewall in the Microsoft MSDN documentation for more information.

Implementation Details for Microsoft Windows

This section shows how the agentless functionality is implemented on Microsoft Windows. This also explains the various requirements as layed out in the special considerations section.

The proxy process server prepares a job specific directory. Since all job directories and the files in it are to be owned by the RunAs user this user account must be known on the proxy process server. Even if it were owned by a different user the actual OS runner account would have to be granted full access to these files, so there is no workaround for this restriction.

The proxy process server then accesses the target host via WMI. Microsoft Windows requires Administrator privileges to allow this. It also shares the proxy platform agent binary and data root directories via SMB. The latter requires no special privileges as it is performed by the local system account. You can see these network shares if you run 'net share' on the proxy process server. An example output is:

C:\> net share

Share name                      Resource                        Remark

---------------------------------------------------------------------------------------------------
C$                              C:\                             Default share
IPC$                                                            Remote IPC
ADMIN$                          C:\Windows                      Remote Admin
agent-SystemID_10180-bin        D:\agent\2023_2_0_20231002_18\bin
agent-SystemIDs_10180-dataroot  D:\agent\var\SystemID_10180\proxyhost

The command completed successfully.

All actions on the WMI channel for a single job are bundled in one WMI session running as the same user. From Microsoft Windows 2008 upwards these sessions are fully isolated, even from other agentless jobs.

During the Dispatched phase the proxy job-processor tries to access the target hosts' ADMIN$ share, in particular \\host\ADMIN$\Temp. This is the default system temp directory. It creates a temporary directory and stores a small executable there as well as a log file. If the creation of this temporary directory and the files succeeds it is able to call the copied executable in order to create a temporary network share to \\proxyhost\agent-SystemId_port-dataroot with a temporary drive letter.

If the access to the ADMIN$ share fails it runs NET USE directly. This has the disadvantage that it needs to pass the password in clear text, and cannot handle all possible punctuation characters in passwords. In particular, a password containing a single or double quote or a space may not function correctly on all Microsoft Windows versions. You can either change the password or enable access to the ADMIN$ share on the target host.

Once the temporary drive has been set up the job goes into the Running status. The job-processor on the proxy host asks WMI to start a second copy of the job-processor, but this time running on the target host. The job-processor on the target host switches to the correct WoW (Windows On Windows) environment if a 64 bit execution environment is requested, and runs the CMD script or CMD shim. Since CMD is used for all definition types as a buffer to set up the correct environment for the process it is required for all processes. Unfortunately CMD requires a current directory that starts with a drive letter. This explains why we need to set up a temporary share for every job.

Once the user code is finished the WMI session ends. This automatically cleans up the temporary network share access and drive letter on the target host. The job-processor on the proxy host then removes the temporary directory in ADMIN$\Temp and copies any log files to the JobFiles directory.

You can find these extra logfiles as extra files attached to the job.

• stdsetup.log contains the execution log of setting up the \\host\agent-SystemID_port-dataroot share.
• stdremote.log contains the execution log of the actual job processor running on the remote agent.

Debugging Agentless Connections

When you run an agentless process it will be executed by calling remote (SSH or WMI) software from a job-processor on the proxy server. Any stdlog.log file is created by this job-processor. If it is necessary to analyze the operation of the remote OS job creation you must change the loglevel setting of the proxy process server, and not the target process server.

Configuring WMI Port Ranges or Static Ports

By default, WMI initially makes a call from the client server to the target server via RPC on port 135, subsequent calls are then made on various ports in the range defined for WMI. The port ranges differ for the various supported Windows versions, see KB832017 for more information.

proxy process server agentless