Installing Platform Agents

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.

A Platform Agent is a small piece of software that is installed at the operating system level on a server inside your network. A Platform Agent can manage communication with sever-based parts of RunMyJobs, issue instructions to the local operating system, submit and monitor jobs, handle file events, and monitor local information such as CPU load and paging rate. There are different Platform Agents available for different operating systems.

Note: Before installing a Platform Agent, read the Prerequisites section below. Failure to comply with the prerequisites may mean that a Platform Agent will not install properly and your configuration may not be supported.

There are two ways to obtain Platform Agent installers.

• Create a Process Server that uses a Platform Agent. This process will create a customized installer that only works for one computer.

• Download a generic Platform Agent installer. You can use such installers to install multiple Platform Agents, but you must customize them when you install them.

Prerequisites

To install correctly and be able to auto-update as part of the Redwood upgrade service, Platform Agents must comply with the following prerequisites.

• To install a Platform Agent, you have sufficient privileges to install new components.
• Windows Platform Agents must be installed using a Windows system administrator account. UNIX and Linux Platform Agent installers can be run as a regular user, but you must run the root.sh file using the root account.
• Auto-update will be enabled when the Platform Agent is installed. This is necessary to ensure that Platform Agents remain synchronized with upgrades to the RunMyJobs server. Do not disable auto-update for an installed Platform Agent. Also, do not tamper with the Platform Agent installation directory, especially the bin and etc subdirectories. On Windows, do not change the settings of the scheduler service that is installed.
• The proxy or firewall must not block auto-update downloads.
• Platform Agents require an HTTPS connection to the Redwood cloud. This is necessary to confirm Platform Agent configuration and communicate job status information to the server. Connection is made to:
  • Host: <region>.###.cloud
    • ###- Verify your URL after connecting to an environment.
  • tcp port: 443

  Product URL (Region-Specific): Whitelist productname.cloud
  https://dublin.runmyjobs.cloud/
  https://oregon.runmyjobs.cloud/
  https://frankfurt.runmyjobs.cloud/

  Notes:

  • The Platform Agents connect to region.runmyjobs.cloud:443. The response uses another port, so the firewall rule must be "response on outbound request is accepted."
  • End-users use region.runmyjobs.cloudin their browser session, which is redirected to region.runmyjobs.cloud:443.
  • HTTPS traffic to region.runmyjobs.cloud using port 443 and proxy must be unrestricted (no TLS inspection, SSL offloading, session hijacking, or SSL encryption).
  • Firewall rules must be based on DNS names (no IP addresses).
  • To test connectivity, run the following cURL command: curl -i https://dublin.runmyfinance.cloud/probe. If this command returns a 202, the connection is OK.
• Platform Agents support HTTP proxy software. During the installation process, the installer will detect whether a direct connection is possible to the RunMyJobs instance. If not, it will allow you to enter proxy details. If you do not have a proxy, it means your sever has no connection to the internet.

Note: An explicit or transparent proxy must pass on the HTTPS traffic unmodified in any sense. In other words, the use of inspection software that decrypts the HTTPS stream is not supported.

The following sections provide an overview of the installation process for a sample of Platform Agent types. In all cases, once a Platform Agent has been successfully installed, at system startup it will launch automatically and attempt to connect to the RunMyJobs server. Successful installation of a Platform Agent will also create its required Process Server and Queue in RunMyJobs and associate the Platform Agent with them. The names of both the Process Server and the Queue will be the same as the hostname of the system on which the Platform Agent has been installed.

Installing a Platform Agent on Windows

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.

A Windows Platform Agent must be installed using a Windows system administrator account. This topic discusses the basic steps to complete the installation. For more information, see Creating a Windows Agent.

The default name of the installer is platform-agent-windows-x86-x_x_x_x.exe, where x_x_x_x is the release number. To install the Platform Agent, run this installer. The installation location will be C:\Program Files (x86)\Redwood\agent.

Note: If you wish to use a different location, start the installation via the command line using the command: platform-agent-x86-x_x_x_x.exe -d c:/MyNew/Folder

If your server communicates with the Internet via a proxy server, the installer will detect this and prompt you for the proxy server name and credentials.

When installation is complete, a confirmation window will display and the Platform Agent will start.

To check the status of the Platform Agent, select Platform Agent Service Manager from the Windows Start Menu. This will launch a desktop widget that lets you view Platform Agent status. You can also use this widget to stop, start, and uninstall Platform Agents on the computer.

Installing a Second Platform Agent on Windows

In some scenarios, you may want to install more Platform Agents on the same sever. To do so, relaunch the installer, and the installer will automatically select a new instance name and unique port number. If it is an existing Platform Agent setup, an extra alert will display to confirm (or update) the settings required to connect to the correct server. By default, these fields are populated with the server info from the environment where the download took place. Make sure the instance and Process Server name are unique.

If you want to split the installation locations, you can run the executable with the -d command to point to (for example) a DEV folder. The following is an example command for using the same server but splitting folders for DEV and TST.

platform-agent-windows-x86-9_2_11-20200224_15.exe -d C:\Redwood\TST

Installing a Platform Agent on UNIX

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.

This topic discusses the basic steps to install a UNIX Platform Agent. See Creating a UNIX Agent for more information.

Pre-Installation Tasks

Redwood recommends that you create a new account and group for the Platform Agent that satisfies your local naming requirements. For example, you can use the following procedure to create a new account and group with the account redwood and group redwood:.

1. Create the group: groupadd redwood

2. Create the account: useradd -g redwood -s /bin/bash redwood

3. Create the home directory of the user: mkdir /home/redwood

4. Change ownership of the directories: chown redwood:redwood /home/redwood

5. Set the password for the account: passwd redwood

6. Login as redwood: su - redwood or login redwood

Installation

The Platform Agent installation process for Linux and the various flavors of UNIX is similar. The following example is for Linux.

The default name of the installer is platform-agent-linux-x86_64-x_x.bin, where x_x is a software release number (in the example below, this is 9_2_11).

Make this file executable by issuing the chmod command, as follows.

redwood@RWtest:/tmp/redwood$ ls -lt
total 14068
-rw-rw-r-- 1 redwood users 14403030 okt 7 10:28 platform-agent-linux-x86_64-9_2_11.bin
redwood@RWtest:/tmp/redwood$ chmod 755 platform-agent-linux-x86_64-9_2_11.bin
redwood@RWtest:/tmp/redwood$ ls -lt
total 14068
-rwxr-xr-x 1 redwood users 14403030 okt 7 10:28 platform-agent-linux-x86_64-9_2_11.bin

To start the installation, run the executable.

redwood@RWtest:/tmp/redwood$ ./platform-agent-linux-x86_64-9_2_11.bin

If your server communicates to the Internet via a proxy server, the installer will detect it. Answer the following question with a Y to proceed.

* We were unable to connect to https://dublin.<*CustomerURL*>.cloud/<*CustomerName*>/<*CustomerEnv*>,
do you need to configure a proxy server? Answering No will HALT the installation! ('Y') #?

You will be asked for the name of your proxy server, along with the username and password if needed. Please enter these as shown in the example below, bearing in mind the password will not be shown on the screen.

#? Y
* What is the hostname of your proxy server? ('no default')

#? MyProxyServer
* What is the portnumber of the proxy-server? ('3128')

#?
* What is the username for this proxy server (myproxyserver:3128)? ('no default')

#? MyProxyUsername
* What is the password for this user (myproxyusername)? ('no default')

#? MyProxyPassword

Once connection to the Internet is established, the installation is designed to be self-contained and will require minimal interaction. Messages like the following may be displayed during installation.

*** Redwood Platform Agent Installation - Version 9_2_11_20230727_17 ***

- The installation directory is '/opt/redwood/agent'
- Instance 'RWtest' is being configured

INFO 2023-07-27 10:39:13,080 CEST [4246-jinstall] jtool.main - jtool succesfully installed

* Under which user account should the job-processor run? ('redwood')

        #?
- The 'setuid' method has been configured
- This agent is configured in 'AgentInitiated' mode, all communications will be initiated by the agent.
- Registering Platform Agent 'RWTEST' at
  https://dublin.<*CustomerURL*>.cloud/<*CustomerName*>/<*CustomerEnv*>
  Writing 'RedwoodPlatform_redwood_cloud_10180' to
  '/opt/redwood/agent/net/instance/RWtest/server_acl'

- Systemd unit 'scheduler.service' will be created.
- Systemd unit 'scheduler@.service' will be created.
Created symlink /etc/systemd/system/multi-user.target.wants/scheduler.service →
/etc/systemd/system/scheduler.service.
- Systemd instance 'scheduler@RWTEST.service' will be created.
Created symlink /etc/systemd/system/scheduler.service.wants/scheduler@RWTEST.service
→ /etc/systemd/system/scheduler@.service.
- Installation is complete
- To finish the installation you will need to run '/opt/redwood/agent/root.sh' under the root account
INFO 2023-07-27 10:39:35,528 CEST [4095-sfx] sfx.main - Installation succeeded

After a successful installation, the Platform Agent will be started automatically.

Installing a Second Platform Agent on Linux

In some scenarios, you may want to install more Platform Agents on the same sever. Relaunch the installer, and the installer will automatically select a new instance name and unique port number. If it is an existing Platform Agent setup, an extra alert will display to confirm (or update) the settings required to connect to the server. By default, these fields are populated with the server info from the environment where the download took place.

Make sure the instance and Process Server name are unique. If they are not, you can change the instance name with -i and change the Process Server name with -ps. Alternatively, you can download a new installer with this info from your environment.

In the following example, we picked the name linuxtstagent to be installed in a test folder. It allows us to have a second DEV instance in a separate folder to strictly split it. If you do not use the -d option, the different configurations (connections to RunMyJobs instances) will be managed from the same installation

./platform-agent-linux-x86_64-9_2_11-20200124_14.bin -i linuxtstagent -ps linuxtstagent -d /opt/redwood/test

Installing a Platform Agent on Mac OS

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.

The Mac OS X Platform Agent is installed via a package with the default name platform-agent-macos-x86-x_x_x_x.pkg, where x_x_x_x is a software release number.

To start the installation, run the executable: $ ./platform-agent-macos-x86_64-9_2_11-20211004_07.bin

If your server communicates with the Internet via a proxy server, the installer will detect this and prompt you for the proxy server name and credentials.

$ ./platform-agent-macos-x86_64-9_2_11-20211004_07.bin

*** Redwood Platform Agent Installation - Version 9_2_11_20230727_07 ***

* In which language do you want the installation to proceed?

1. Exit Installation

1. English
1. Deutsch
1. Nederlands
1. Francais

#? [1]
*** Redwood Platform Agent Installation - Version 9_2_11_20230727_07 ***

 - The installation directory is '/opt/redwood/agent'
 - Instance '<hostname>' is being configured
INFO  2023-07-27 11:36:57,048 CEST [25207-jinstall] jtool.main - jtool succesfully installed
 - The default account for running jobs will be '<YourUser>'
 - The 'setuid' method has been configured
 - This agent is configured in 'AgentInitiated' mode, all communications will be initiated by the agent.
 - Registering Platform Agent '<hostname>' at https://dublin.<CustomerURL>.cloud/<CustomerName>/<CustomerEnv>
Writing 'RedwoodPlatform_redwood_cloud_10180' to '/opt/redwood/agent/net/instance/<hostname>/server_acl'

 - To finish the installation you will need to run '/opt/redwood/agent/root.sh' under the root account
INFO  2023-07-27 11:36:59,351 CEST [25074-sfx] sfx.main - Installation succeeded

When installation is complete, a confirmation window will display and the Platform Agent will start.

Installing a JVM (Optional)

If you want to run RunMyJobs system processes on the Platform Agent, you must first install a supported Java 11 or 17 JDK on your Platform Agent. Supported and tested Java 11 or 17 JDKs include the following.

• Oracle JDK
• Eclipse Adoptium Temurin
• IBM Semeru

You can use a different Java 11 or 17 JDK, but it must be supported by a vendor. If you encounter JVM-related issues that are not reproducible with the supported and tested JDKs above, you will have to contact your vendor for support. You must ensure that the JDK is updated regularly with patches. On Linux, fontconfig is required.

Installing a JCo for SAPR3 Processes (Optional)

If you want to run SAPR3 processes on the Platform Agent, you must first install the SAP Java Connector (JCo) 3.1 on your Platform Agent's computer.

Navigate to SAP Java Connector and download the appropriate JCo 3.1 ZIP file for your platform. Unzip the file contents into a directory (for example, C:\\redwood\\sap\\jco).

On Windows, set environment variable NATIVEJAVA_CLASSPATH for user System to the directory where you extracted the JCo files (.jar file and .dll files).

On UNIX/Linux, create an environment file named <pa_install>/etc/environment and insert the following:

export NATIVEJAVA_CLASSPATH=/path/to/jco

If you extracted the jar and libraries to /opt/sap/jco, for example:

echo "export NATIVEJAVA_CLASSPATH=/opt/sap/jco" > "<pa_install>/etc/environment"

The fontconfig package is a requirement on UNIX.

To enable the Platform Agent to retrieve SAP spool files, set the /configuration/jcs/sap/output/RetrieveOutputViaAgent registry key to true.

Securing Connections with Secure Network Connections (SNC) (Optional)

Prerequisites

• SAPCAR for your platform (available from launchpad.support.sap.com).
• SAPCRYPTOLIB for your platform.

Workflow

Configuring SNC with jrfc to enable secure RFC connections greatly improves security. See SAP Note 1848999 for more information.

1. Unpack the SAR file using sapcar. For example: sapcar -xvf SAPCRYPTOLIBP_8540-20011697.SAR.
2. Copy the SAP Cryptographic library (sapcrypto.dll for Windows, or libsapcrypto.<ext> for UNIX) to ${InstallDir}/saplibs.
3. Set the SNC_LIB environment variable (SNC_LIB_64 on Windows with a 64-bit JVM) to the full path of the library file. For example: C:\Program Files (x86)\Redwood\agent\saplibs\sapcrypto.dll or /opt/redwood/agent/saplibs/sapcrypto.so.
4. Follow the below procedure for creating the PSE files. Use the values mentioned below.
   1. Copy the PSE files to the directory defined in SECUDIR(for example, ${InstallDir}/sapsec).
   2. Set the SECUDIR environment variable to the directory where you stored the PSE files (for example, C:\Program Files (x86)\Redwood\agent\sapsec or /opt/redwood/agent/sapsec).
   3. In ${InstallDir}/etc/startup/${Instance}/environment, specify the full path to the SAP Cryptographics library in the SNC_LIB environment variable (SNC_LIB_64 on Windows with a 64-bit JVM). Specify the full path of the directory containing the PSE files in the environment variable SECUDIR. Make sure the user under which the Platform Agent runs can read the files in question. You must restart the Platform Agent for the changes to take effect.

Note: For SNC on UNIX, the UUID daemon must be active. For more information, see SAP Note 1391070.

Note: The <INSTALL_PATH>/saplibs directory is prepended to the library search path.

Values

• _PASS=secret: The password of the PSE.
• _FIPS=-fips on: Leave this empty if no FIPS is to be used.
• _LPS=-lps: Leave this empty if no LPS is to be used.
• _ALG= -a RSA:2048:SHA256: Thje algorithm to use.
• _PSE=RunMyJobs.pse: The name of the PSE to create.
• _CRT=RunMyJobs.crt: The certificate that needs to be installed in the target SAP system(s).
• _DN="CN=RunMyJobs, OU=Example, O=Redwood, C=NL": The oganizational name to be used for RunMyJobs.
• <OS User>: The user that runs the Platform Agent

Execute the following commands after setting the environment variables (Windows cmd.exe examples):

: Create PSE
sapgenpse %_FIPS% gen_pse -v %_ALG% %_LPS% -x %_PASS% -p %_PSE% %_DN%
: For each Target SAP System
sapgenpse %_FIPS% maintain_pk -v -x %_PASS% -a <Target SAP certificate>.crt -p %_PSE%
: Export your own Certificate
sapgenpse %_FIPS% export_own_cert -v -x %_PASS% -p %_PSE% -o %_CRT%
: Create the logon to PSE for the user
sapgenpse %_FIPS% seclogin -v %_LPS% -x %_PASS% -p %_PSE% -O <OS User>

Note: On Windows, set the OS user to SYSTEM.

Further Reading

• SNC Terminology
• Configuring SNC: External Programs - ABAP Platform Using RFC
• Exporting the Server's Certificate Using SAPGENPSE
• Creating the Server's Credentials Using SAPGENPSE
• Maintaining the Server's Certificate List Using SAPGENPSE

Checking Platform Agents from the Redwood Server

RunMyJobs will automatically create, configure, and connect a Process Server and Queue in the cloud. These are required in order for the Platform Agent to be accessible. The Process Server and Queue associated with a specific Platform Agent are identified by the hostname of the connected server.

To check the status of your Process Servers, navigate to Environment > Process Servers. The Status of the Process Server after installation should display as Running.

See Also

• Creating a Microsoft Windows Process Server
• Creating UNIX Process Servers
• Configuring Platform Agent Hosts