UNIX Platform Agents

A UNIX Process Server works by communicating with a UNIX Platform Agent. You can use a UNIX Platform Agent on any supported OS platform where the native API is UNIX (including Linux and macOS).

Structure of a UNIX Platform Agent

On UNIX the Platform Agent is started by the scheduler script located in ${InstallDir}/${version}/etc. This script starts all Platform Agent instances found in the various installation trees. The scheduler script is started when the system boots by a link from UNIX system dependent files, usually /etc/init.d/ scripts. The scheduler script invokes the platform-agent script. (Do not run the Platform Agent script manually, because that's what the scheduler script is for.)

The scheduler script needs the system character set in its environment. The character set must be convertible to UTF-8 using the UNIX I18N tools. Set the LANG, LC_CTYPE, or LC_ALL environment variable to a UTF-8 compatible locale. For example, you unset LC_ALL and set LANG to en_US.UTF-8 or ISO-8859-15. Note that LC_ALL takes precedence over LANG and LC_CTYPE.

Each Platform Agent instance is represented by two or three continuously running processes, shown here in ps form.

Copy 
\_ /opt/redwood/agent/9_2_11_20230727_10/bin/network-processor -p /opt/redwood/agent/etc/pid/default/default.pid -i default
 \_ /opt/redwood/agent/9_2_11_20230727_10/bin/network-processor -p /opt/redwood/agent/etc/pid/default/default.pid -i default

The platform-agent and top level network-processor processes are present from the start. The second network processor instance is created as soon as the Platform Agent is configured by the Process Server. If the network-processor process dies unexpectedly, the Platform Agent will restart it. The Platform Agent also plays a role in Automatic Updating.

A second instance of the network processor process verifies that the network processor can create a child process and makes sure the OS returns proper data for child processes.

For each other process, the Platform Agent starts a job-processor process.

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.

UNIX processes are executed by a Platform Agent. It executes the code in the Process Definition in a specific environment as a specific user. Note that on UNIX systems, when setting resource limits for a process, it is important to know that the limits that apply are those that are in effect for the parent process and not the limits for the user under which the process runs. This means that the resource limits of the user that starts the Platform Agent are in effect, regardless of which user the process actually runs as.

The Platform Agent may run on the same machine as the server, or on any other machine on the network. UNIX processes contain shell scripts in languages such as KSH, BASH, CSH and Perl.

Installing a UNIX Platform Agent

Note: When installing a Platform Agent on an SAP application server, Redwood recommends naming the Process Server <SID>_<APP_SVR>_PlatformAgent, where <APP_SVR> is the hostname of the application server.

Each installer is named individually for its operating system / platform combination, as follows.

Copy 
platform-agent-<OS>-<platform>-<version>.bin

Note: If you transfer a bin file via FTP, you must use binary mode.

You can control installation options with installer switches, and environment variables. Installer switches (if specified) override environment variables.

Installer Switches

The UNIX installer accepts the following switches.

Switch Description Example
-ac, --enable-server-acl <Y/N> If set to Y, this switch locks the Platform Agent to the RunMyJobs server. -ac Y
-ai, --agent-initiated If set, all communication will be initiated by the Platform Agent. -ai
-b, --enable-autoboot <Y/N> If set, automatically starts the Platform Agent when the OS boots. -b Y
--confirm If set, enforces confirmation of predefined values. --confirm
-d, --destination <path> The installation location (local path). -d /opt/redwood/agent
-f Lets you specify the location of the installer log file. -f /opt/redwood/installer.log
--force If set, overwrites any existing files. --force
-h, --help Shows this help. -h
-i, --instance <name>[:<port] Instance name and port. The port will be used by the Platform Agent (except for AgentInitiated agents). -i prd-kubernetes:1556
-l Lets you set the verbosity mode. Defaults to info. -l debug
--language Lets you select the language for the installer. Valid values: en (English), de (German), nl (Dutch), and fr (French). --language de
-m, --user-switch-mode Lets you set the mechanism for switching users. Valid values are root, plain, setuid, and sudo. -m sudo
-pr, --proxy <user:password@host:port> Lets you specify a proxy server. -pr https://pxuser:horseStackMonkey@gatekeeper.local:80
-ps, --process-server <process-server> Lets you set the name of the Process Server. -ps MSLN_UNIXS1
-pw, --password <password> Lets you set a user's password. -pw horseStackPompey
-ql, --queue-list <queue-list> A comma-separated list of the Queues that the Process Server serves. -ql "UNIXGeneric,Kubernetes"
-rp, --register-properties <path> The path of the register.properties file. -rp /opt/redwood/prd-kubernetes.properties
-rs, --registration-server http[s]://<server>:<port> The URL of the RunMyJobs server. -rs https://pr1.example.com:50300/redwood
-u, --unattended If set, turns on unattended installation. -u
-un, --username <name> The username of a RunMyJobs user with the privileges necessary to create a Process Server (such as scheduler-administrator or redwood-administrator). -un Administrator
-w, --run-as <username> The default user to run processes as. -w redwood

Use the switches as follows:

Copy 
platform-agent-<OS>-<platform>-<version>.bin <switch> <value> <switch> <value>...

For example:

Copy 
sudo ./platform-agent-linux-x86_64-9_2_11_20230727_10.bin -d /opt/redwood/prod -i Example -m sudo -b Y -ac Y

Note: Parameters that are set on the command line will not be verified by the installer, unless you specify the --confirm switch.

TLS Environment Variables

Note: If you run the installer as an unprivileged user, a file named root.sh located in the installation directory is created. This file must be executed as superuser (root) to complete the installation.

Environment Variables

Environment variables let you set installation-specific and registration-specific settings. The installer accepts the environment variables listed in this section.

You can specify multiple environment variables as follows:

Copy 
INSTLANG=DE INSTALLDIR=/opt/redwood/prod INSTANCE=Example USERSWITCHMODE=sudo STARTUP=Y SERVERACL=Y platform-agent-<OS>-<platform>-<version>.bin

INSTLANG

This is the language the installer uses is derived from your locale. To override this, set the INSTLANG environment variable to a two-letter language code. Languages supported are EN (English), FR (French), DE (German), and NL (Dutch). If you specify an unknown value, the installer uses English.

Copy 
INSTLANG=FR platform-agent-<OS>-<platform>-<version>.bin

INSTALLDIR

This is the installation directory for the Platform Agent. The user executing the installer must have write permissions to this directory.

Copy 
INSTDIR=/opt/redwood/agent platform-agent-<OS>-<platform>-<version>.bin

INSTANCE

This is the name of the instance for this Platform Agent.

Copy 
INSTANCE=prd-postgre platform-agent-<OS>-<platform>-<version>.bin

USERSWITCHMODE

This is the user switch mode to use. The default is setuid.

Copy 
USERSWITCHMODE=sudo platform-agent-<OS>-<platform>-<version>.bin

RUNAS

This is the user the Platform Agent runs as. If the USERSWITCHMODE is plain, then all processes will be run as this user.

Copy 
RUNAS=redwood platform-agent-<OS>-<platform>-<version>.bin

AGENTPORT

This is the numeric port used by the Platform Agent. Note that port names are not supported.

Copy 
AGENTPORT=1551 platform-agent-<OS>-<platform>-<version>.bin

STARTUP

This lets you control whether the Platform Agent starts when the OS starts.

Copy 
STARTUP=Y platform-agent-<OS>-<platform>-<version>.bin

ALLOWUPDATE

This lets you control whether the Platform Agent is updated when the central RunMyJobs server is updated.

Copy 
ALLOWUPDATE=Y platform-agent-<OS>-<platform>-<version>.bin

Registration Environment Variables

In addition to the other environment variables listed in this topic, you can use these.

  • REGISTER: Set this to Y to register the Platform Agent with the RunMyJobs server. This must be set to Y for the environment variables below to apply.
  • SERVERNAME: The hostname of the RunMyJobs server.
  • SERVERPORT: The port on which the RunMyJobs server is listening.
  • SERVERUSERNAME: The user account to login with.
  • SERVERPASSWORD: The password for this user.
  • PSERVER: The name of the Process Server to register.
  • SERVERACL: Set this to Y to lock the Platfrom Agent to the RunMyJobs server.

Example

This example demonstrates using the GNU/Linux installer for x86 platforms. It uses switches to perform an unattended installation in German, with processes run as user example using security option suid.

Copy 
$ platform-agent-linux-x86-9_2_11_20230727_10.bin -u -l DE -w example -m suid

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

See Also