Installing a Platform Agent on OpenVMS

Note: OpenVMS Process Servers are available only if your license includes a non-zero value for the key ProcessServerService.VMS.limit. Process Servers that include the DCL Definition Type are not counted towards the ProcessServerService.OS.limit and ProcessServerService.External.limit license keys.

Prerequisites

  • A RunMyJobs instance.
  • An OpenVMS 8.2 or higher ia64 server with appropriate access to the RunMyJobs server (including the root password).
  • The VMS Internationalization Kit.
  • A zip utility.
  • An OpenVMS account with the following VMS system privileges:
    • TMPMBX, to create temporary mailboxes for communication between processes.
    • NETMBX, to create a network socket for the server to communicate with the Platform Agent.
    • Optional: IMPERSONATE, to run processes as other VMS users.
    • Optional: CMKRNL, to monitor the system load (page rate, CPU usage).
    • Optional: SYSPRV privilege, to add a new nametable to LNM$SYSTEM_DIRECTORY
    • Optional: BYPASS privilege, to manipulate files created by processes running as other users and to create a new nametable in LNM$SYSTEM_DIRECTORY.
  • on-site-related topic Connectivity from the RunMyJobs server to the OpenVMS host on the Platform Agent's port.

Installing the OpenVMS Internationalization Data Kit

A Platform Agent communicates with RunMyJobs using the UTF-8 character set. To convert this to/from the usual DEC International Character Set (of which ISO-8859-1 is a superset), you need the OpenVMS Internationalization Data Kit.

To verify that the VMSI18N kit has already been installed, execute the following command.

Copy 
$ product show prod *i18*
----------------------------------- ----------- ------------
PRODUCT                             KIT TYPE    STATE
----------------------------------- ----------- ------------
DEC AXPVMS VMSI18N V8.2             Full LP     Installed
----------------------------------- ----------- ------------

1 item found

You can also try running one of the RunMyJobs command-line system tools. All of these try to access the necessary APIs for character set conversion when they start. If you run a command-line tool on a system that does not have the kit installed, you will see an error message such as this when you try to run it.

Copy 
$ run jsleep.exe
error 2023-07-27 00:00:00,000 GMT [154-Main tid=2075815240] opsys.conv - Unable to determine proper UTF-8 character set
error 2023-07-27 00:00:00,000 GMT [154-Main tid=2075815240] opsys.conv - Make sure the VMSI18N kit from the OpenVMS media set is installed

To install the OpenVMS Internationalization Data Kit, follow the instructions in the OpenVMS Upgrade and Installation manual.

If you have not yet installed the OpenVMS Internationalization Data Kit, you can still run a Platform Agent, but you will have to set the character set to UTF-8. This will mangle content that uses code points that are not at the same location as in UTF-8, but these seldom occur in OpenVMS DCL files. You can set the character set of the software to UTF-8 by setting a logical LANG to UTF-8, or add the following command line arguments: --filesys UTF-8 --filedata UTF-8. Although this should work, it is not recommended by Redwood.

Creating an Account

Redwood recommends that you create a new account for an OpenVMS Platform Agent that satisfies your local naming requirements.

For example, assume you are using the account REDWOOD with UIC [377,200]. To add this account, follow this procedure.

  1. Log in as SYSTEM.
  2. Change to the system directory and start the authorization image: $ MC AUTHORIZE
  3. Create the account: ADD REDWOOD /UIC=[377,200]
  4. Set password and login flags: MODI REDWOOD /PASSWORD=XXXX /FLAGS=NODISUSER
  5. Set the account privileges: MODI REDWOOD /PRIV=(NETMBX,TMPMBX,IMPERSONATE,CMKRNL,SYSPRV,BYPASS)
  6. Set the account default privileges: MODI REDWOOD /DEFPRIV=(NETMBX,TMPMBX,IMPERSONATE,CMKRNL,SYSPRV,BYPASS)
  7. Set the home directory: MODI REDWOOD /DEVICE=SYS$USER /DIR=[REDWOOD]
  8. Set the proper quotas for the new account: MODI REDWOOD/JTQUOTA=0/MAXDETACH=0/MAXJOBS=0/BYTLM=0
  9. Set the quota to at least these values:
    • MODI REDWOOD/BIOLM=150/DIOLM=150/ENQLM=2000
    • MODI REDWOOD/WSDEF=4096/WSQUO=32768/WSEXTENT=65536/PGFLQUOTA=100000
  10. Exit authorize: EXIT
  11. Create the home directory: $ CREATE/DIR SYS$USER:[REDWOOD] /OWNER=REDWOOD

If you are running with reduced privileges:

  1. If you have not granted the SYSPRV (or write access to LNM$SYSTEM_TABLE) and BYPASS privileges, create a name table: CREATE/NAME/ATTR=NO_ALIAS/PARENT_TABLE=LNM$SYSTEM_DIRECTORY/EXE/PROT=(O:RWD,S:RWD,G:RW,W:RW) LNM$SCHEDULER

Installing a Platform Agent

To install a Platform Agent on OpenVMS, follow this procedure.

  1. Log in using the designated account.
  2. Create a directory (preferably named AGENT).
  3. Unzip the Platform Agent installer to this directory.
Copy 
$ unzip openvms-<CPU>.zip

The directory where you installed the Platform Agent is referenced as InstallDir, and its bin directory is referenced as ExecutableDir.

Creating Symbols

Redwood recommends that you create symbols for the command-line system tools so that they can be executed from within processes (for example, in a procedure that is set up in SYLOGIN.COM). Redwood also recommends that you add the following.

Copy 
$ !
$ ! Example, replace SYS$USER with your own logical or path to redwood directory.
$ !
$ !
$ JTOOL=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE TOOL"
$ JLINK=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE LINK"
$ JSLEEP=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE SLEEP"
$ JREGISTER=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE REGISTER"
$ JEVENT=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE EVENT"
$ JMESSAGE=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE MESSAGE"
$ JDESCRIPTION=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE DESCRIPTION"
$ JSECRET=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]JTOOL.EXE SECRET"
$ !
$ ! In case you need to pass arguments, for example, non-default instance
$ !
$ NETWORKPROCESSOR=="$SYS$USER:[REDWOOD.AGENT.<version>.BIN]NETWORK-PROCESSOR.EXE"

For further platform-independent configuration instructions, see Configuring Platform Agents. In particular, if you want to guard the Platform Agent against intruders and use by different server instances, Redwood recommends that you create a SharedSecret using the instructions found there.

Starting a Platform Agent on OpenVMS

Redwood recommends you create a symbol to the SCHEDULER.COM in your LOGIN.COMfile. For example:

Copy 
$!
$! Find the latest agent, or at least something.
$!
$loop:
$ x = f$search("[.agent.9*.bin]jtool.exe;")
$ if x .eqs. "" then goto stop
$ bindir = f$parse(x,,,"DEVICE") + f$parse(x,,,"DIRECTORY")
$ write sys$output "- Found agent directory ''bindir' for JTOOL"
$ jtool=="$''bindir'jtool.exe"
$ goto loop
$stop:
$!
$loop2:
$ x = f$search("[.agent.9*.etc]SCHEDULER.COM;")
$ if x .eqs. "" then goto stop2
$ etcdir = f$parse(x,,,"DEVICE") + f$parse(x,,,"DIRECTORY")
$ write sys$output "- Found agent directory ''etcdir' for SCHEDULER"
$ scheduler=="@''etcdir'SCHEDULER.COM"
$ goto loop2
$stop2:

The symbol can be used to stop, start, and restart all instances in the installation tree (or individual instances) using the following syntax.

Copy 
SCHEDULER {START | STOP | RESTART | START-INSTANCE <instance> | STOP-INSTANCE <instance> | ADD-INSTANCE <instance> <port> }

On an initial installation, you can use SCHEDULER.COM to create a new instance, as follows.

Copy 
@SCHEDULER.COM add-instance <name> <port>

This creates a number of files, if they are not already present.

Copy 
[.etc.startup.'instance'.autoupdate] ! directory, if present: allow auto-update
[.etc.startup.'instance']version. ! current version to be used
[.etc.startup.'instance']user. ! user to run platform-agent as
[.etc.startup.'instance']loglevel. ! initial loglevel
[.net.instance.'instance'.private]secret. ! Shared secret
[.net.instance.'instance']port. ! Port number to listen on

The system keeps track of which instances are running by process name. By default, PA <instance>. This can be overridden by creating a file:

Copy 
[.etc]process_name_fao.txt

...for which the default value is:

Copy 
PA !AS

...where !AS is the F$FAO() substitution for the process name.

Working Directory

The default working directory is set to ${JobFilesDirectory}, but you can change this by setting the JobWorkingDirectory Process Server parameter. You can use the following variables:

  • ${JobFilesDirectory}
  • ${HomeDirectory} (translated to SYS$LOGIN)
  • ${JobID}
  • All logicals set up by the LOGIN.COM procedure.