Configuring Platform Agents

Platform Agents are configured by their installer. However, knowledge of the parameter configuration files can be useful if you need to make advanced configuration changes.

Note: On Windows systems, the Scheduler Service Manager lets you configure some Platform Agent options with a graphical user interface. For more information, see Configuring Platform Agents on Microsoft Windows.

Configuration files are stored in the ${InstallDir}/net/ hierarchy. The net directory can contain subdirectories, so multiple Platform Agents can be managed from a single tree. RunMyJobs traverses these directories in the following order.

1. net/instance/<instance>/<file>.
2. net/hostname/<hostname>/<file>.
3. net/global/<file>.

Placeholders above are as follows.

• <instance> is the name of the instance, which by default is set to default.
• <hostname> is the hostname of the server, as returned by the command hostname.
• <file> is the name of the file being sought. Files that are supposed to be protected should be located under the private directory.

In other words, instance-specific settings are honored before hostname-specific settings, and hostname-specific settings are honored before global settings.

The files that RunMyJobs looks for on all systems are listed here in alphabetical order.

Note: If you set or change server_root, you must restart the Platform Agent service/daemon and the Process Server in the central RunMyJobs server for the change to take effect.

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.

In files that can contain more than one word, you can separate keywords by putting them on separate lines or by separating them with a comma or space. A hash (#) character functions as a comment until the end of the line. The etc directory contains global configuration files.

address_acl

If set, the address_acl file will limit which IP addresses can connect to the server. The file can contain a list of IP addresses, hostnames, and/or IP ranges.

Example:

#
            ## Example address_acl file
            #
            192.168.10.0/24
            10.31.0.0/255.255.0.0
            bpa1.prod.sap.de
            bpa1.prod.sap.de
         

The address_acl is not set by any of the installers. Configuring it is up to an administrator.

agent_initiated_url

For AgentInitiated environments only.

Do not set this parameter if the Platform Agent should run a TCP server and wait for incoming TCP requests from RunMyJobs. This is the default configuration.

If the Platform Agent should create TCP clients and actively connect to the RunMyJobs instance (AgentInitiated mode), this parameter should be set to the full path of the servlet that it needs to connect to. The pattern allowed in this file is https://${Server}:${Port}/${Context}/ipi-platformagentservice/BusinessKey/${Partition}.${ProcessServerName}. For example, the following will connect to an app server named server running at the default port, context and Partition and Process Server name unix1.

https://pr1.example.com:50300/redwood/ipi-platformagentservice/BusinessKey/GLOBAL.unix1

For more information, see Cloud Platform Agents.

Note: AgentInitiated Platform Agents must be configured for auto-update. For more information, see Cloud Platform Agents.

cipherlist

Specifies the ciphers to use for TLS encryption.

The configuration file accepts a comma-separated list (no spaces) of OpenSSL cipher suite names (not IANA/RFC cipher suite names) or the ALL keyword, which means all cipher suites except the eNULL ciphers, ordered in a sensible manner.

Example

ECDHE-RSA-CHACHA20-POLY1305,ECDHE-ECDSA-CHACHA20-POLY1305

client_port_range

If set, the client_port_range file will limit the port numbers used for client connections. This parameter accepts <low>-<high> syntax (for example, 1024-1048). This can be used, for example, to identify traffic in a firewall.

etc/ca-bundle.crt

A list of PEM-encoded certificates. Append PEM-encoded certificates to this file when you want to (for example) trust self-signed certificates.

etc/session.rdp

The Remote Desktop Protocol (RDP) file used to connect to the local Windows Server. Windows Server 2012 and later are supported. Windows client operating systems (Windows 8, 8.1, or 10) are not supported.

failover_url

The read-only HTTP(S) URL of the fail-over RunMyJobs instance. The context URL can be set in the /configuration/FailoverContextURL [configuration entry|ConfigurationEntries].

gateway_acl

For AgentInitiated environments only.

Use this file to specify a newline-separated or comma-separated list of networks or hosts the RunMyJobs instance is allowed to access. For example, if your internal network is 10.x.x.x and you only want the RunMyJobs instance cloud servers to access the 10.0.0.x and 10.10.x.x subnets, you can set this to the following on each Platform Agent that will act as Secure Gateway.

10.0.0.0/24
            10.10.0.0/16
         

The file accepts networks (see example), DNS names, and IP addresses.

gateway_port_range

For AgentInitiated environments only.

The port ranges to use for the gateway. By default, this is set to 40000-49999.

hmac

Normally the Platform Agent will use the SHA256 algorithm to compute hashes that guarantee message correctness. This can be switched to the older MD5 algorithm if desired.

listen

Use the listen file to specify which IP address of the Platform Agent's computer is used to accept new connections. By default, this is set to 0.0.0.0 and accepts any connection from any Ethernet card and address. You can limit this to a particular IP address or a hostname that resolves to a local IP address. This in turn means that the Platform Agent will only listen for connections that come from that particular device.

If an IP address that you want the Platform Agent to listen on is not a permanent address (its availability is not 100%), keep the default address of 0.0.0.0 and set up an address_acl parameter to limit who can connect to the Platform Agent, because binding to disappearing network devices will result in failure of the Platform Agent each time the device stops.

max_requests

The HTTP server in the Platform Agent will normally process unlimited requests per HTTP connection. This can be lowered to a particular number by setting this number in the max_requests file. This is a debugging/support feature that should only be used in cooperation with technical support.

monitor_process

Use the monitor_process file to specify the command to use for monitoring an OS process.

monitor_socket

Use the monitor_socket file to specify the command to use for monitoring a socket.

port

The port the Platform Agent will use at startup is saved in a file named port. If no such file is found, the default of 1555 is used. The only contents of the port file should be the port number. For example, to set the port number for instance production to 1566, you can proceed as follows:

On UNIX:

echo 1566 > /opt/redwood/net/instance/production/port

Note that /opt/redwood is the installation directory in the above example.

On Windows:

echo 1566 > G:\redwood\net\instance\production\port

Note that G:\\redwood is the installation directory in the above example. The port parameter file is set by the standard installers.

no_live_view

The existence of this file disables live viewing of output and log files in the Processes Monitor and Definition Studio.

private/proxy_url_password, proxy_url, and no_proxy

For AgentInitiated environments only.

If set, proxy_url must contain the URL of the proxy server, and private/proxy_url_password must contain the encrypted password. Use jsecret -p to generate a proxy_url_password file.

You can specify multiple proxy servers and passwords as follows.

1. Create or edit the proxy_url file for the instance. For example, the proxy_url for instance default is stored in /opt/redwood/agent/net/instance/default/proxy_url.
2. Enter http://<user>@<proxy_server1>, http://<user>@<proxy_server2> into the file. For example: http://jdoe@proxy1.example.com:9090,http://jdoe@proxy2.example.com:9090
3. Make sure jtool is in your PATH.
4. Create two separate password files, merge them into one, and apply appropriate privileges:
   1. Issue jtool secret -p /tmp/proxy1_url_password. Note that you must enter the password for the first proxy server (in this case, http://jdoe@proxy1.example.com:9090).
   2. Issue jtool secret -p /tmp/proxy2_url_password. Note that you must enter the password for the second proxy server (in this case, http://jdoe@proxy2.example.com:9090).
   3. Issue paste -d',' <file_1> <file2> > <path>/proxy_url_password. For example: paste -d',' /tmp/proxy1_url_password /tmp/proxy1_url_password > /opt/redwood/agent/net/instance/default/private/proxy_url_password
   4. Issue chmod 640 path>/proxy_url_password. For example: chmod 640 /opt/redwood/agent/net/instance/default/proxy_url_password
5. Restart the Platform Agent: /opt/redwood/agent/latest/etc/scheduler restart

no_proxy

When you have a Secure Gateway configured, you can restrict the network traffic that is considered to be local traffic and is allowed to be forwarded to the cloud. For example:

<acl-entry>[,<acl-entry>...]
            acl-entry :=   <host>[/<mask>][:<port-range>] | <ipv6-addr>[/<mask>]
            port-range:=   [<port-low>][-][<port-high>]
            port-low  :=   integer 0-65535, default 0
            port-high :=   integer 0-65535, default 65535
            host      :=   <hostname> | <ipv4-address> | '['<ipv6-addr>']'
            hostname  :=   dns name
            ipv4-addr :=   <d>.<d>.<d>.<d>
            d         :=   integer 0-255
            ipv6-addr :=   [<x>]:[<x>][:[<x>]...]
            x         :=   hexadecimal integer 0-ffff
            mask      :=   <bits>
            bits      :=   integer 0-32 (or 0-255 for ipv6)
         

In the above example:

• acl-entry is the host, subnet, network, or domain for which no proxy is required.
• host is the hostname, domain name, IP address, or subnet for which no proxy is required. Examples: *.internal.example.com (domain), 10.1.0.15 (IP address).
  • hostname: The name of the server(s). Accepts wildcards. For example: myserver.example.com or *.example.com.
  • ipv4-addr: The IP version 4 address. For example: 10.15.0.15 or 10.15.0.0/32.
  • ipv6-addr: The IP version 6 address. For example: 1234:5678:ABCD:0018::2004 or 1234:5678:ABCD:0018::0/64.
  • mask: The subnet mask for subnet specifications (IP version 4 and 6). For example, 32 in the IP version 4 subnet specification 10.1.0.0/32.
    • bits: The bits of the subnet mask.
• port-range: The range of allowed ports.
  • port-low: The lowest allowable port of the range.
  • port-high: The highest allowable port of the range.

private/secret

If this file is present, it should contain a secret that the RunMyJobs instance also has configured for this Process Server. The secret is used to create a hash function over the content of the message being passed. If both sides do not possess the same secret, the Platform Agent log file will contain messages like the following.

error <date> [***-http-request #** tid=***] http.http - Content digest *** does not match computed value ***
            error <date> [***-http-request #** tid=***] http.http - Request with content has incorrect HMAC checksum
         

To avoid this situation, make sure both sides have the same shared secret. The shared secret is generated when you install a Platform Agent using the installer. If you register a Platform Agent during the installation, the shared secret is passed to the RunMyJobs instance. If not, you have to paste the value into the SharedSecret Process Server parameter and restart the Process Server. You can generate the shared secret with the jsecret executable. On Windows you can also use the Scheduler Service Manager to set the secret. For more information, see Configuring Platform Agents on Windows.

proxy_incoming

If this file contains the value true, the Platform Agent is accessible via a reverse proxy such as HAproxy or nginx. Refer to the following for more information on the protocol.

rwscert.pem and private/rwskey.pem

The rwscert.pem and private/rwskey.pem configuration files contain the public certificate and the private key for TLS. These must be PEM-formatted (the certificate must start with -----BEGIN CERTIFICATE-----, and the key must start with -----BEGIN PRIVATE KEY-----). You can convert them using openssl, or you can ask your certificate authority to provide you with the appropriate format.

Converting from DER to PEM using OpenSSL

$ openssl x509 -inform DER -outform PEM -text -in mykey.crt -out rwscert.pem
            $ openssl rsa -inform DER -outform PEM -in mykey.crt -out private/rwskey.pem
         

secure_connection

The secure_connection file, if it exists and contains the keyword true, will force the Platform Agent to use TLS for incoming HTTP requests. TLS mandates the following.

• PEM-formatted certificate and private key in rwscert.pem and private/rwskey.pem, respectively.
• OpenSSL cipher suites, or the ALL keyword in cipherlist.
• One or more directories to serve listed in server_root. Only files residing in directories or subdirectories of server_root will be served to clients.

For more information, see Securing Communications for Platform Agents and System Tools.

server_acl

If the server_acl file exists, it limits the Platform Agent to only connecting with RunMyJobs instances that have a system ID that the file contains. To find out what a system's system ID is, log in to the system and observe the browser heading. The part before the [ character is the system ID.

You can also issue the REL expression String.getSystemId() in a Process Definition parameter. This will return the current system ID.

Any characters in the system ID that are not alphanumerical must be converted to underscores (_). For example, a system ID of My Instance:1234 will be transmitted as My_Instance_1234.

The file can contain either system IDs or system IDs followed by /<Process Server name>. For example, the following server_acl file will limit the Platform Agent to function for these three nodes in a cluster, but it will be configurable as any Process Server.

## Limit this agent to respond only to nodes in the BPA cluster
            SAP_BPA_00
            SAP_BPA_01
            SAP_BPA_02
         

If you want this Platform Agent to respond only to the nodes in the cluster and for only a particular Process Server name, use something like the following.

## Limit this agent to respond only to nodes in the BPA cluster and the MSLN_UNIXS1 Process Server
            SAP_BPA_00/MSLN_UNIXS1
            SAP_BPA_01/MSLN_UNIXS1
            SAP_BPA_02/MSLN_UNIXS1
         

If the server_acl file exists, any messages or requests from systems and/or Process Servers that it is not configured to respond to will result in an error message stating "Refusing connection from server with SystemId ... and ProcessServer ..." This message is not translated into the user interface language because it is generated as a HTML response.

If the server_acl file does not exist, the Platform Agent will dynamically tie itself to the system ID and Process Server that it is first configured as, and will respond with an error message stating "Strict checking is enabled. Agent will only respond to X-RW-SystemID requests from ..." This message is not translated into the user interface language because it is generated as a HTML response. The server_acl file is set by the installer when a Platform Agent installer successfully registers with the RunMyJobs instance.

server_root

Platform Agents contain an HTTP server that can be used to serve process output and Platform Agent log files. It only does so to the Java server, because the caller must have the secret. It also limits the reading of files to those directories where it has put process output and log files. In some configurations, it may be necessary for a Platform Agent to serve files that it did not generate itself, however, in which case the HTTP server must be told which directories it is allowed to serve files from to the Java server.

The server_root file can contain a list of paths to the top-level directories that it should also serve. For example:

#
            ## Directories that contain extra output files to be served up
            #
            c:\tmp\
            d:\oapps\data\
         

The server_root parameter is not set by any of the installers. Configuring it is up to an administrator.

version_compatibility

The version_compatibility file contains the version(s) of RunMyJobs instances the Platform Agent is allowed to connect with. This file accepts the * wildcard.

For example:

2023.2.0.*,9.2.11.*,9.2.9.*

If instructed by Redwood support staff, you can use this setting to use a new version of the Platform Agent with an older version of the RunMyJobs instance. If you do so, make sure that the VersionCompatibility Process Server parameter is not set, because that means the Platform Agent no longer knows what messages the server supports.

http_response_mode and http_server_timeout

When communicating with servers older than 9.0.10, such as version 8 (M33), Redwood support may ask you to set http_response_mode to the value keep and http_server_timeout to a low value such as 30.

private/whitelist and private/blacklist

On UNIX, it is common practice to prevent certain users from being able to log in interactively. You can also avoid running jobs as specific users on UNIX, OpenVMS, and Windows. To do this, you must provide RunMyJobs with a list of authorized or banned users. These settings are saved in the ${InstallDir}/net hierarchy, in the private subdirectory. For security reasons, they should only be readable by users redwood and root on UNIX and System on Windows.

If you provide a whitelist, the blacklist is not used. The default value is a blacklist containing root,daemon,bin,sys,adm,uucp,nuucp,lp,listen,sysadm,smtp,ftp,tftp,news,sysdiag,sundiag on UNIX, or no defaults on Windows and OpenVMS.

This file should contain a comma-separated list of usernames, and no Windows domains.

UNIX network-processor

The UNIX-specific parameters for the network-processor executable are kept in the ${InstallDir}/net hierarchy, just like the system-independent settings. Some items reside in a further private/ subdirectory. For security reasons, these should be readable only by the user that the network-processor runs as.

chown

If you choose sudo as your user-switching mode, the RunMyJobs installer on UNIX creates a sudo configuration for the RunMyJobs user. This could be used to gain access to files owned by root. To avoid this, RunMyJobs lets you to specify your own chown command. RunMyJobs ships with an example chown.sh file, which checks various parameters for validity.

The chown file in the net directory is a symbolic link to the chown binary as detected by the installation routine. You can create a symbolic link to the chown.sh script in the Redwood Server bin directory to improve security. Edit the chown.sh script to suit your security needs.

Password Checking

The UNIX Platform Agent uses usermode to switch accounts. When the user switch mode is setuid or sudo, the users that jobs can be run as are determined by the private/whitelist, private/blacklist, and possibly the sudoers configuration. Who is allowed to use which account is fully under the Central Scheduler Server's administrator control by means of grants on Process Definitions and credentials. However, the actual password for the account stored in the Central Scheduler Server is not verified against the current password on the UNIX system. In this sense, the UNIX Platform Agent functions like a trusted subsystem.

If you want RunMyJobs to prove it has the current password, and/or you need to perform extra authentication or access checks, the job-processor can call PAM to further authenticate the user. To do so, set a PAM service name in the password_check file. For example:

login

If the password_check file has contents, a series of pam(3) Pluggable Authentication Module calls will be made. An exception is AIX, for which equivalent usersec calls are made. If the defined PAM service refuses access, the OS process will go into an error state. You can use the network-processor to test your configuration by using the -o flag.

In this example, we are checking the password for a specific instance, the password is correct, and PAM checking is enabled.

./network-processor -i prod -o
            [...]
            INFO  2023-07-27 06:07:45,408 GMT [131172-network-processor] common.config - Jobs will only be run for users not on blacklist root,bin,sys,adm
            INFO  2023-07-27 06:07:45,408 GMT [131172-network-processor] common.config - Password checking is enabled with value login
            INFO  2023-07-27 06:07:45,408 GMT [131172-network-processor] opsys.update - Verified user switch mode is setuid
            Enter password for example:
            INFO  2023-07-27 06:07:45,508 GMT [131172-network-processor] network.main - Password is correct
            INFO  2023-07-27 06:07:45,508 GMT [131172-network-processor] main.main - network-processor exit 0
         

In this example, we are checking the password for a specific instance, the password is incorrect, and PAM checking is enabled.

./network-processor -i prod -o
            [...]
            INFO  2023-07-27 06:07:45,608 GMT [131175-network-processor] common.config - Jobs will only be run for users not on blacklist root,bin,sys,adm
            INFO  2023-07-27 06:07:45,608 GMT [131175-network-processor] common.config - Password checking is enabled with value login
            INFO  2023-07-27 06:07:45,608 GMT [131175-network-processor] opsys.update - Verified user switch mode is setuid
            Enter password for example:
            ERROR 2023-07-27 06:07:45,708 GMT [131175-network-processor] opsys.user - Could not authenticate user 'example' via PAM: Authentication failure
            INFO  2023-07-27 06:07:45,708 GMT [131175-network-processor] main.main - network-processor exit 2
         

In this example, we are checking the password for a specific instance, the password is correct, and PAM checking is disabled (password_check is not set).

./network-processor -i default -o
            [...]
            INFO  2023-07-27 06:07:45,808 GMT [131195-network-processor] common.config - Jobs will only be run for users not on blacklist root,bin,sys,adm
            INFO  2023-07-27 06:07:45,808 GMT [131195-network-processor] common.config - User authorization delegated to sudo configuration and blacklist
            INFO  2023-07-27 06:07:45,808 GMT [131195-network-processor] opsys.update - Delaying verification of sudo user switch mode to point when configured by server
            Enter password for example:
            ERROR 2023-07-27 06:07:45,908 GMT [131195-network-processor] opsys.user - Password checking has not been enabled. Set 'password_check' net configuration file to desired PAM module, usually 'login'
            INFO  2023-07-27 06:07:45,908 GMT [131195-network-processor] main.main - network-processor exit 2
         

Troubleshooting dependencies:

$ network-processor -i prod -o
            INFO  2023-07-27 06:07:45,169 GMT [12787-network-processor] common.logging - Logging to stderr at level info
            INFO  2023-07-27 06:07:45,169 GMT [12787-network-processor] common.logging - Flavor linux-x86 build 9_2_11_20230727_10
            INFO  2023-07-27 06:07:45,170 GMT [12787-network-processor] opsys.conv - Network  character set is utf8
            INFO  2023-07-27 06:07:45,170 GMT [12787-network-processor] opsys.conv - Internal character set is utf8
            INFO  2023-07-27 06:07:45,170 GMT [12787-network-processor] opsys.conv - Filedata character set is UTF-8
            INFO  2023-07-27 06:07:45,170 GMT [12787-network-processor] opsys.conv - Filesys  character set is UTF-8
            INFO  2023-07-27 06:07:45,170 GMT [12787-network-processor] opsys.conv - Argument character set is UTF-8
            INFO  2023-07-27 06:07:45,171 GMT [12787-network-processor] opsys.env - Operating system Linux=v3.2 id=x86_64
            user=32-bit ram=7833MB processors=12
            INFO  2023-07-27 06:07:45,173 GMT [12787-network-processor] opsys.socket - IPv4/IPv6 support compiled in.
            INFO  2023-07-27 06:07:45,174 GMT [12787-network-processor] opsys.init - Host pr1 FQDN pr1.example.com
            INFO  2023-07-27 06:07:45,174 GMT [12787-network-processor] common.config - Jobs will only be run for users not on default
            blacklist root,bin,sys,adm,uucp,nuucp,lp,listen,sysadm,smtp,ftp,tftp,news,sysdiag,sundiag
            INFO  2023-07-27 06:07:45,174 GMT [12787-network-processor] common.config - Password checking is enabled with value login
            INFO  2023-07-27 06:07:45,178 GMT [12787-network-processor] opsys.update - Verified user switch mode is setuid
            Enter password for example:
            ERROR 2023-07-27 06:07:45,204 GMT [12787-network-processor] opsys.user - Could not authenticate user example via PAM:
            Module is unknown
            INFO  2023-07-27 06:07:45,204 GMT [12787-network-processor] main.main - exit 2
         

The above occurs when you run 32-bit GNU/Linux Platform Agents on 64-bit operating systems without the necessary PAM libraries.

$ sudo yum install pam.i686
            [...]
            $ network-processor -i prod -o
            INFO  2023-07-27 06:07:45,256 GMT [13163-network-processor] common.logging - Logging to stderr at level info
            INFO  2023-07-27 06:07:45,256 GMT [13163-network-processor] common.logging - Flavor linux-x86 build 9_2_11_20230727_10
            INFO  2023-07-27 06:07:45,256 GMT [13163-network-processor] opsys.conv - Network  character set is utf8
            INFO  2023-07-27 06:07:45,256 GMT [13163-network-processor] opsys.conv - Internal character set is utf8
            INFO  2023-07-27 06:07:45,256 GMT [13163-network-processor] opsys.conv - Filedata character set is UTF-8
            INFO  2023-07-27 06:07:45,256 GMT [13163-network-processor] opsys.conv - Filesys  character set is UTF-8
            INFO  2023-07-27 06:07:45,256 GMT [13163-network-processor] opsys.conv - Argument character set is UTF-8
            INFO  2023-07-27 06:07:45,257 GMT [13163-network-processor] opsys.env - Operating system Linux=v3.2 id=x86_64
            user=32-bit ram=7833MB processors=12
            INFO  2023-07-27 06:07:45,260 GMT [13163-network-processor] opsys.socket - IPv4/IPv6 support compiled in.
            INFO  2023-07-27 06:07:45,260 GMT [13163-network-processor] opsys.init - Host pr1 FQDN pr1.example.com
            INFO  2023-07-27 06:07:45,260 GMT [13163-network-processor] common.config - Jobs will only be run for users not on default
            blacklist root,bin,sys,adm,uucp,nuucp,lp,listen,sysadm,smtp,ftp,tftp,news,sysdiag,sundiag
            INFO  2023-07-27 06:07:45,261 GMT [13163-network-processor] common.config - Password checking is enabled with value login
            INFO  2023-07-27 06:07:45,265 GMT [13163-network-processor] opsys.update - Verified user switch mode is setuid
            Enter password for example:
            INFO  2023-07-27 06:07:45,307 GMT [13163-network-processor] network.main - Password is correct
            INFO  2023-07-27 06:07:45,307 GMT [13163-network-processor] main.main - exit 0
         

Following the installation of the 32-bit PAM libraries, the password check succeeds.

Note: On Debian-based systems, the package in question is named libpam-modules.

Note: A 64-bit version of the GNU/Linux Platform Agent is available.

usermode

The user-switching mode that the network-processor uses to run jobs under the correct account is stored in ${InstallDir}/net/.../usermode. It contains one of the following: plain, root, sudo, or setuid. This parameter is usually set by the UNIX Platform Agent installer.

See Also

• Support Note 115542 - Character set issues related to processes, jtool and jmail