Using Jolt Internet Relay

This section provides an overview of the Jolt Internet Relay architecture and how to use it.

Note: Jolt Internet Relay was used in previous releases at some sites for specific security requirements. Currently, it is not a widely used feature and should only be implemented in specific circumstances or by suggestion of Oracle support staff.

Image: Jolt Internet Relay Architecture showing the Jolt Relay sending messages through a firewall to the Jolt Relay Adapter

Jolt Internet Relay provides an environment in which the PeopleSoft web server and application server can be further decoupled. This provides greater security at sites where security is of utmost importance. Jolt Internet Relay routes messages from a Jolt client to a Jolt Server Listener (JSL) or Jolt Server Handler (JSH), and eliminates the need for the JSL, JSH, and Tuxedo application to run on the same machine as the web server. Communication takes place between the JRLY and JRAD elements rather than between the Jolt client and JSL/JSH processes. Traditionally an application server domain opens between 2 and 6 ports for such communications. The use of Jolt relay restricts this to one port per domain on the application server machine. This enables an administrator to open just one port on the application server machine. The following diagram illustrates this feature:

Jolt Internet Relay Architecture showing the Jolt Relay sending messages through a firewall to the Jolt Relay Adapter

Jolt Internet Relay consists of two elements: Jolt Relay (JRLY) and Jolt Relay Adapter (JRAD). It's important to understand the difference between these two elements.

JRLY consists of a standalone program and configuration file; the program runs on the same machine as the web server. JRLY receives Jolt messages from a PeopleSoft web application and routes those messages to JRAD on the application server. It receives the Jolt message through one port, the LISTEN port, and connects to the JRAD by using another port, the CONNECT port. JRLY is sometimes referred to as a front-end relay.

JRAD runs on the same machine as the application server. It's configured on the application server domain as part of the PeopleSoft PSADMIN domain configuration procedure. JRAD listens for JRLY messages on its LISTEN port and transfers the message to the JSL or JSH. JRAD is sometimes referred to as a back-end relay.

Note: Implementing Jolt Relay can impede performance. Always perform testing with typical production system load to ensure it will meet your service level requirements.

Keep the following points in mind as you configure the Jolt Internet Relay components:

  • The jrly binary and its corresponding jrly.config file must exist in the same directory. To start multiple Jolt Relays on a machine, copy the jrly binary and jrly.config into each subdirectory, modify the parameters in the jrly.config file, and start Jolt Relay. On Windows, you can define multiple Jolt Relay services on a machine.

  • You can start the JRLY process before or after you start JRAD. The JRLY attempts to connect to JRAD on the client request. If the JRLY is unable to connect to the JRAD, the client is denied access and disconnected. The connection will be retried upon the first use of PeopleTools..

  • If you're installing Jolt Internet Relay on UNIX and anticipate a large number of concurrent connected clients, increase the file descriptors limit before running the JRLY executable.

  • At runtime, if you get the following message:

    [FRi JUNl 6 20:25:11 1997] JRLY:accept():accept failed, err no: 23, strerror: File table overflow

    PeopleSoft recommends that you increase the MaxUSERS kernel parameter and regenerate the kernel.

  • If you're unable to connect, make sure that you check the following items:

    • Port numbers do not match.

      Print out the jrly.cfg file and the psappsrv.cfg file and compare the port numbers that you specified.

    • Make sure that the application server is running.

    • Make sure that JRLY is running.

  • Jolt Internet Relay can be installed on an intermediate machine rather than the web server machine if necessary. This extra level of indirection can cause performance degradation.

  • Make sure that JRAD is running on the application server and that you configure JRAD using PSADMIN.

Configuring JRLY is identical on UNIX and Windows.

To configure JRLY, navigate to TUXDIR\udataobj\jolt\relay and open jrly.config in a text editor.

Important! On UNIX, you can edit this configuration file by using VI or an equivalent editor. However, on Windows, you must edit the file using an editor that preserves the file's UNIX line feeds. WordPad is valid for this purpose, but Notepad is not.

Modify the parameters in the configuration file to reflect the site specifications, as follows:

Parameter

Description

LOGDIR

LOGDIR specifies the directory where JRLY creates access and error log files. This directory must exist; the JRLY program does not start if it can't find this directory. The path that you specify for LOGDIR should be an absolute path (starting from / on UNIX systems, starting from a drive letter on Windows systems). The JRLY accepts relative path names, but LOGDIR is relative to the directory from which the JRLY program is started, unless you specify it as an absolute.

ACCESS_LOG

ACCESS_LOG specifies the name of the file where JRLY records access information. This log file is created in LOGDIR. If the log file already exists, the most recent information is appended to it.

This parameter can be any valid file name. Everything after the equals sign (=) to the end of the line is considered as part of the file name, but leading and trailing blanks are ignored.

Note: If the JRLY program can't create this file or open it for appending, the program exits.

ERROR_LOG

ERROR_LOG specifies the name of the file where JRLY records error information. This file follows all the rules that apply to the ACCESS_LOG parameter. JRLY_error_log is created in /tmp.

LISTEN

LISTEN specifies the host and port on the current machine (that is, the machine where you're installing Jolt Relay). JRLY listens for client connections. The following formats are acceptable:

LISTEN=192.0.2.100:9000
LISTEN=//192.0.2.100:9000
LISTEN=server_name:9000
LISTEN=//server_name:9000

Specify the port number in decimal; it must match the port number that is specified by the psserver parameter in the configuration.properties file for the PIA web application.

Note: If a machine has multiple network interfaces, you should use the IP address notation, because specifying the host name could be ambiguous (the result is OS dependent). If the JRLY program can't establish a network listening end-point at the host and port specified, it prints an error and exits.

The host name that's specified for this parameter must be the name of the host on which the program is running.

Note: You can create multiple configuration files to run multiple instances of JRLY. Each configuration file must specify a different port number for this parameter.

CONNECT

CONNECT specifies the location of the JRAD machine and process port on the application server machine to which the JRLY program connects. A JRLY program communicates only with a single JRAD. The address you specify for this parameter must match the JRAD listener address that's on the application server machine (check the PSAPPSRV.CFG file in PS_CFG_HOME/appserv/domain). The JRAD doesn't have to be running when you start the JRLY program. JRLY attempts to connect to the JRAD when it first starts, and if the JRAD is not available, JRLY tries again whenever a new client connects to it. You can use any of the following formats for this parameter:

CONNECT=192.0.2.100:9100
CONNECT=//192.0.2.100:9105
CONNECT=server_name:9105
CONNECT=//server_name:9105

Note: PeopleSoft has found that machine address formats are operating system and environment dependent. If one fails to connect to the application server, try another format.

SOCKETTIMEOUT

SOCKETTIMEOUT specifies the duration (in seconds) for which the Jolt Internet Relay Windows service blocks the establishment of new socket connections to allow network activity (new connections, data to be read, closed connections) to complete. It's valid only on Windows machines.

SOCKETTIMEOUT also affects the Service Control Manager (SCM). When the SCM requests that the service stop, the SCM needs to wait at least the number of seconds specified by this parameter.

The JRLY connect port connects to the JRAD listener port that is specified on the application server machine. JRAD then routes the message to Jolt, either using the JSL for initial connection from a web client, or using the JSH for all subsequent connections from a web client. The return message follows the same path in reverse.

To configure JRAD:

  1. Launch the PSADMIN utility.

  2. Navigate to the PeopleSoft Domain Administration menu and select Configure this domain.

  3. In the Quick Configure menu, select the number for the Jolt Relay option, to enable Jolt Internet Relay.

  4. Select the JRAD Port option, and enter the appropriate port number for the JRAD Port.

    Note: The JRAD (listener) port number must match the JRLY connect port that you previously configured.

This section discusses how to:

  • Use the JRLY administration program.

  • Run Jolt Relay on Windows.

  • Run Jolt Relay on UNIX.

Using the JRLY Administration Program

You use the jrly command located in TUXDIR\udataobj\jolt\relay to administer Jolt Relay on all platforms. You can use the following jrly command options at any time:

  • jrly -version

    Display the current version of the JRLY binary.

  • jrly -help

    Display a summary of command-line options with brief descriptions.

Running Jolt Relay on Windows

On Windows, you set up Jolt Relay to run as a service. On other platforms you must run Jolt Relay directly.

If you want to install multiple Jolt Relay services, you must specify a string to be used as a display suffix that uniquely identifies each additional service you install. You subsequently use the suffix to identify each service it commands. An additional service with the suffix MyJoltRelay, for example, is called Oracle Jolt Relay_MyJoltRelay, but you refer to it using only the suffix. You can omit the suffix when installing only one of these services, which becomes the default Jolt Relay service, called Oracle Jolt Relay.

Note: All administrative commands in the following table except -start and -stop require that you have write access to the Windows registry. The -start and -stop commands require that you have Windows service control access. These requirements are based on Windows user restrictions.

Command

Description

jrly -install [display_suffix]

Install JRLY as a Windows service.

jrly -remove [display_suffix | -all]

Remove one instance, all instances, or the default JRLY Windows service.

jrly -set [-d display_suffix] -f config_file

Update the registry with the full path of a new configuration file for the specified JRLY service.

Note: You can run multiple Jolt Relay services by specifying a different display suffix along with the name of a different configuration file for each installed service. Each configuration file must contain a unique value for the LISTEN parameter that specifies a different port. This is essential to avoid port clashes when running the services concurrently. You must run this command before the service starts.

jrly -manual [display_suffix]

Set the start/stop to manual. This command sets the specified JRLY service to be manually controlled, using either the command-line options or the Service Control Manager (SCM).

jrly -auto [display_suffix]

Set the start/stop to automatic. This command sets all the operations for a specified JRLY service to be automatically started when the OS boots and stopped when the OS shuts down.

jrly -start [display_suffix]

Start the specified JRLY service.

jrly -stop [display_suffix]

Stop the specified JRLY service.

Running Jolt Relay on UNIX

This section discusses how to start and stop Jolt Relay directly from a command line on UNIX.

To start Jolt Relay on UNIX:

  1. Change directories to the Jolt Relay directory within your Tuxedo installation:

    cd $TUXDIR/udataobj/jolt/relay

  2. Run the following command:

    jrly -f jrly_config &

    Where jrly_config is the name of a Jolt Relay configuration file.

    You can run multiple instances of Jolt Relay by using a different port for each instance. You run JRLY once for each instance, and specify a different configuration file each time. Each configuration file must contain a value for the LISTEN parameter that specifies a different port.

    The ampersand character (&) causes JRLY to run in the background.

To shut down Jolt Relay on UNIX, use the UNIX kill -9 command.