Configuring REN Servers

To configure REN servers, use the REN Server (REN_SERVER_CMP) component.

This section provides an overview of REN server configuration options.

Depending on your requirements, choose one of two REN server creation and configuration options:

  • To create a single REN server in a particular database using default configuration parameters, create an application server domain using PSADMIN.

    Event Notification may be enabled in the quick-configure menu. An associated REN server cluster is automatically created when Event Notification is enabled.

  • To create additional REN servers in a particular database, configure each REN server as required on the REN Server Definition and REN Server Cluster pages.

    Then create the associated application server domains. Event Notification must also be enabled in the quick-configure menu.

When a REN server starts, it looks for configuration information in the database, using the application server domain name and host name as keys. If the associated configuration information exists in the database, the REN server uses it. If no such configuration information exists, the REN server is configured by defaults, which also configure a REN server cluster for each REN server. You can change the default REN server configuration by using the REN Server Configuration pages, but such changes do not take effect until the REN server starts up again.

Note: You can create only one REN server per application server domain.

This section discusses some possible REN server configurations that depend on domain server topology.

Simple Configuration: Mycompany.com

In this configuration, the REN server is on the host machine MachA, the REN server uses the default port number 7180, the domain name server (DNS) addresses the host machine as MachA.mycompany.com, and no SSL or reverse proxy server is involved:

Parameter

Value

PeopleSoft Pure Internet Architecture Authentication Token Domain

mycompany.com

Authentication Domain in REN Server Cluster Configuration

mycompany.com

REN Server Cluster Root Path

/psren

REN Server Cluster URL

http://MachA:7180

REN Server Browser URL

http://MachA.mycompany.com:7180

Simple Configuration with SSL-Enabled REN Server: Mycompany.com

In this configuration, the REN server is on the host machine MachA, the REN server uses the default port number 7143, and DNS addresses the host machine as MachA.mycompany.com. The REN server is SSL-enabled.

Parameter

Value

PeopleSoft Pure Internet Architecture Authentication Token Domain

mycompany.com

Authentication Domain in REN Server Cluster Configuration

mycompany.com

REN Server Cluster Root Path

/psren

REN Server Cluster URL

https://MachA:7143

REN Server Browser URL

https://MachA.mycompany.com:7143

Reverse Proxy Server with Non-SSL Configuration

This configuration includes a single REN server and a reverse proxy server. The reverse proxy server could be either a dedicated reverse proxy server or a web server with a proxy plug-in configured to redirect both PeopleSoft Pure Internet Architecture and REN server requests. The application server host machine is MachA, and the REN server uses its default port 7180. The reverse proxy server is on MachRPS using port 8080 for HTTP. The DNS server must recognize MachRPS.mycompany.com.

Parameter

Value

PeopleSoft Pure Internet Architecture Authentication Token Domain

mycompany.com

Authentication Domain in REN Server Cluster Configuration

mycompany.com

REN Server Cluster Root Path

/psren

REN Server Cluster URL

http://MachA:7180

REN Server Cluster Browser URL

http://MachRPS.mycompany.com:8080

Reverse Proxy Server with SSL Configuration and Secure HTTP

For SSL, install certificates on the reverse proxy server, set the server to encrypt all communications, and use HTTPS URLs from the browser. In this example, the reverse proxy server uses port 8443 for SSL:

Parameter

Value

PeopleSoft Pure Internet Architecture Authentication Token Domain

mycompany.com

Authentication Domain in REN Server Cluster Configuration

mycompany.com

REN Server Cluster Root Path

/psren

REN Server Cluster URL

http://MachA:7180

Note: The cluster URL should not be a secure HTTP address if SSL is handled through a reverse proxy server.

REN Server Browser URL

https://MachRPS.mycompany.com:8443

Note: This is a secure HTTP address (HTTPS).

Note: If you use SSL between the browser and REN server, you must use a reverse proxy server or SSL accelerator.

Specify REN server configuration parameters based on your network topology and server arrangement.

Define the parameters for REN server configuration in three locations:

  • Authentication token domain, set during PeopleSoft Pure Internet Architecture installation or in web profile configuration.

  • REN server configuration parameters, specified in an application server domain using PSADMIN.

  • REN server parameters, including cluster and browser URLs, set in the PeopleTools REN Server and REN Cluster components.

    Configuration parameters that are set in the REN Server and REN Cluster components override any defaults in PSADMIN.

Authentication Domain

The authentication domain tells PeopleSoft Pure Internet Architecture the internet domain name that browser clients use when accessing PeopleSoft applications across the internet. The token is required to comply with the same-origin security policy that is enforced by most browsers. The domain name that is specified in the REN Server Configuration page must be identical to the domain name that is specified as the authentication token domain during PeopleSoft Pure Internet Architecture installation.

If authentication domain is not set during PeopleSoft Pure Internet Architecture installation, define the authentication domain in web profile configuration to match the REN server configuration.

Note: You must specify the authentication token domain if you access the REN server and the PeopleSoft Pure Internet Architecture web server using different DNS names from the browser client (for example, if they are on different machines).

Configuring a REN Server and SSL-Enabled REN Server with PSADMIN

If necessary, you can specify parameters in the PSRENSRV section of the PSADMIN application server domain configuration, as illustrated in the following example:

Image: Configuring PSRENSRV in PSADMIN

This example illustrates the parameters in the PSRENSRV section of the PSADMIN application server domain configuration.

Configuring PSRENSRV in PSADMIN

Specify parameters as described in the following table:

Parameter

Default

Description

log_severity_level

Warning

This is the logging level for the REN server.

Select from one of the following log severity levels, from less to more logged data: Error, Warning, Notice, Debug.

Note: Do not use Debug in a production environment.

io_buffer_size

8192

This is the TCP buffer size in bytes that is used for serving content. Do not exceed a value of 65536.

If the REN server is running on Microsoft Windows, change io_buffer_size to a minimum value of 56000.

default_http_port

7180

This is the REN server's HTTP port.

The default value is 7180.

The default_http_port parameter takes effect only when a REN server starts up for the first time and the database does not already contain configuration information for the REN server.

Note: After the HTTP port number that is assigned to the REN server has been established in the database, the only way to change it is on the REN Server Definition page. Editing the port number in the psappsrv.cfg file does not overwrite the value that is stored in the database.

default_https_port

7143

This is the REN server's HTTPS port for SSL-enabled REN server.

The default value is 7143.

Note: The https port is used only when the REN server is SSL-enabled.

The default_https_port parameter is configured in psappsrv.cfg and is used when a SSL-enabled REN server starts up for the first time.

Note: To change the default https port, use the REN Server Definition page. Changing the SSL Port requires the reboot of the REN server.

default_auth_token

example.com

This is the fully qualified domain name of the application server.

This value should match the value of the web server's authentication domain.

The default_auth_token parameter takes effect only when a REN server starts up for the first time and the database does not already contain configuration information for the REN server.

When configuring the REN server parameters through PSADMIN, do not place a period or dot (.) before the default_auth_token value. For example, the parameter should read default_auth_token=example.com

Access logging is no longer enabled by default. In order to enable access logging, remove the leading #(hash) from this line in the “Modules to load” section of the psrenconfig.txt file.#ns_param  nslog   ${bindir}/${prefix}rennslog${ext}

After specifying REN server configuration parameters, be sure to specify Y (Yes) when asked if you want event notification configured and MCF server configured. Boot this domain from the Domain Administration menu.

Note: Use PeopleSoft Pure Internet Architecture REN server definition and configuration pages to modify configuration parameters whenever possible. REN server configuration parameters that you make using PSADMIN are written to the psappsrv.cfg file in the application server directory. REN server configuration values that are found in the database override any values that are found in psappsrv.cfg.

Use static IP addresses for your web servers. If you use dynamic IP addresses (DHCP), ensure that the domain name server (DNS) can map fully qualified domain names to the dynamic IP addresses.

If you are using Microsoft Internet Explorer internet security zones, include both the web server and REN server addresses in the same security zone; alternatively, exclude both addresses from security zones.

Socket Binding

The REN server listens on the port that is defined in the REN Server Definition page, which is by default 7180. However, the host name to which the REN server binds is determined by information in the psrenconfig.txt file for each application server domain. If the host machine contains multiple network interface cards (NICs), then the REN server binds by default to only one NIC, which is given by uname() on Unix, or GetComputerName() on Microsoft Windows.

To bind a REN server to a specific NIC, manually edit psrenconfig.txt for the appropriate application server domain, changing both set address and set hostname to the IP address and locally-known host name of the NIC. For example:

set address			192.0.2.10
set hostname		myserver.example.com

Note: If you enter an invalid IP address in the psreconfig.txt file, the REN server may not start correctly. Check the REN server log for error messages that identify the issue.

Note: To configure a REN server with a virtual machine name, manually enable the #ns_param javascript_kn_server parameter in the psrenconfig.txt by removing # (hash) from the parameter.

Configuring TCP_NODELAY

The parameter, TCP_NODELAY in psrenconfig.txt controls whether to disable the TCP Nagle algorithm on the TCP packets sent by the REN server. Two instances of TCP_NODELAY are available in psrenconfig.txt. TCP_NODELAY in the nssock section is used by non-SSL REN servers, and the instance in the nsopenssl section is used by SSL-enabled REN servers. The TCP Nagle algorithm is generally enabled by default and inserts a short delay before sending small TCP packets. This helps prevent network overload.

If TCP_NODELAY is set to 0, the TCP algorithm acts normally. This is the recommended configuration for most applications. However, for certain CTI applications, this parameter must be set to 1 to improve performance. If TCP_NODELAY is set to 1, the TCP Nagle algorithm is disabled on operating system platforms that support disabling this feature.

Access the REN Server Configuration page using the following navigation path:

PeopleTools > REN Server Configuration > REN Server Definition

Image: REN Server Configuration page

This example illustrates the fields and controls on the REN Server Configuration page. You can find definitions for the fields and controls later on this page.

The REN Server Configuration page displaying the REN server ID and the Keystore Information.

Field or Control

Definition
Application Server Domain

Enter the application server domain that is serving this REN server.
Host Machine

Enter the name of the host machine on which the specified application server domain runs.

This entry requires the host machine name, not its DNS name. However, the host machine name may need to be fully qualified, for example, machineA.example.com. On a Unix machine, determine the host name by running uname -a. On a Microsoft Windows machine, determine the host name by running hostname at a command prompt.
Port Number

Enter the HTTP port number on which this REN server is addressed.

Change the HTTP port value if multiple REN servers are running on the same host machine to avoid port conflicts.
SSL Only

Select to enable SSL on REN server.

Note: If this option is selected, you must enter the SSL port.

If you want to enable SSL on the REN server, ensure that you create and configure a Renserver certificate before defining a REN server.

SSL Port Number

Enter the HTTPS port number on which this SSL-enabled REN server is addressed.
Client Authentication

Select an option to determine the level of client authentication.

Note: If the browser is configured for client authentication pop-up or the browser has more than one certificate configured, the SSL session ends if the user fails to provide the certificate within three heartbeats. To avoid such a session time-out, the user must either accept the client certificate within a heartbeat or increase the session time-out value in psrenconfig.txt.

The Client Authentication values are described in a subsequent table.
P12 Keystore File With Path

Enter the absolute path where the PKCS #12 keystore will be created or is located.
Keystore Password

Enter a password for the internal or the external PKCS #12 keystore. The password is internally encrypted.
PEM TrustStore File With Path

Enter the absolute path where the TrustStore will be created or is located.

Note: The trusted certificates are the root certificates, which are different from the certificate chain.
Create Keystore from Database

Select to use stored certificates from the Digital Certificates page.
Certificate Alias

Select a certificate alias to be used as a server certificate by the SSL-enabled REN server.

Note: The certificate alias is stored in the PSKEYDB, PSCERTDB, and PSREN records.
Read External Keystore

Select to use an external PKCS #12 keystore to read the Private Key, the Certificate Chain, and the Trusted Certificates. If you want to use an external Java keystore, you must configure the external Java keystore before you define the REN server on this page.

See Configuring External Keystore in REN Server

Note: By default, the Read External Keystore radio button is not selected, that is, the application server, at boot up, reads the Private Key, the Certificate Chain, and the Trusted Certificates from the database and creates a PKCS #12 keystore at the location entered in the P12 Keystore File With Path field.

Note: When you select the Read External Keystore radio button, the application server, at boot up, streams the path and password of the external PKCS #12 keystore to the REN server. The path of the external keystore is entered in the P12 Keystore File With Path field and the password is entered in the Keystore Password field. Subsequently, the REN server, at boot up, loads the external PKCS #12 keystore by using the password.

The following table shows the client authentication values:

Parameter

Flag Value

Description

No Client Authentication

0

Client authentication is disabled.

On each Request-Verify only if Supplied

1

Client authentication is enabled

The server sends a client certificate request to the client. Verification happens only if the certificate is provided. If the verification process fails, the TLS/SSL handshake is immediately terminated. If the client does not return any certificate, SSL communication still continues

On Each Request-Mandatory to Supply

3

Client authentication is enabled and mandates that the client provide the certificate.

If the client does not return a certificate, the TLS/SSL handshake is immediately terminated with a handshake failure alert. If the client returns a certificate, it is verified. The communication fails if the verification fails.

At Initial handshake Only-Verify only if Supplied

5

Client authentication is enabled and requests a client certificate on the initial TLS/SSL handshake only.

Verification happens only if the certificate is provided. If the client does not provide any certificate, SSL communication still continues. If verification fails, the TLS/SSL handshake is immediately terminated.

At Initial handshake Only-Mandatory to Supply

7

Client authentication is enabled and mandates that the client provide the certificate only in initial TLS/SSL handshake.