Skip to main content

Define a Server Access Profile for Your InterSystems IRIS Instance

This page describes how to configure server access profiles for the InterSystems Web Gateway. Server access profiles enable the InterSystems Web Gateway to establish and maintain a connection with the InterSystems IRIS® application server which hosts your web application.

Each InterSystems IRIS instance accessed by the Web Gateway must be defined in a server access profile. Any unspecified optional parameters or custom system forms are automatically inherited from the Web Gateway default settings. After you have defined server access profiles for your InterSystems IRIS application servers, you can define application access profiles to associate application paths with their corresponding application servers.

For these and other configuration tasks, use the Web Gateway management pages or Web Gateway Registry methods. The Web Gateway maintains this configuration information in the CSP.ini file.

Important:

Except in containerized deployments where it may be necessary to edit the CSP.ini file directly, InterSystems recommends restricting access to the CSP.ini file and performing all Web Gateway configuration using the Web Gateway management pages.

Add a Server Access Profile

To allow the Web Gateway to connect to an InterSystems IRIS application server, define a server access profile to identify the InterSystems IRIS server within the Web Gateway configuration. To do so:

  1. From the Web Gateway management pages main menu, select Server Access.

  2. Select Add Server. The second configuration screen appears. Note that many parameter fields have default settings.

  3. In the Server Name text box, enter a unique, descriptive name for the server. This logical name is used to identify the server configuration in the CSP configuration file.

  4. Enter the system parameters (described below) for this server access profile.

  5. Select Save Configuration.

Server Access Parameters

The set of base server configuration parameters are as follows:

Server Configuration Parameter Function
Server Name Logical name to identify this server access profile in the CSP configuration file.
Service Status Allows you to enable and disable this server within your Web Gateway configuration(default is Enabled).
IP Address The DNS host name or IP address (physical or virtual) of the InterSystems IRIS server to connect to.
Superserver TCP Port The TCP port number on which the InterSystems IRIS server is listening for incoming connections. This is the TCP port number of the InterSystems IRIS superserver which is 1972 by default, but may be different if multiple instances are deployed on the same system.
Configuration is Mirror Aware

Configures a mirror primary as a server to access mirrored databases. In a failover or disaster recovery, the connection is redirected. By default, not selected.

Note: If you have configured a mirror VIP, do not configure a mirror aware Web Gateway, which causes the Web Gateway to ignore the VIP. Instead, simply configure the Web Gateway to connect to the VIP like any other client. In general, use of a mirror aware Web Gateway is the appropriate choice only in unusual circumstances.

To configure, enter the IP address of one of the failover members. From this failover member, the Web Gateway obtains a list of the failover and disaster recovery (DR) async members in the mirror and connects to the current primary based on this list (and not the VIP even if one is configured). The CSP connection fails until a primary is found.

Once the connection is established, if the mirror fails over, the Web Gateway changes the connection to the new primary. If no primary can be found among the failover members, the Web Gateway attempts to find one among the DR asyncs in the list, which enables it to reestablish the connection when a DR async is promoted to primary in a disaster recovery situation.

For details, see Redirecting Application Connections Following Failover or Disaster Recovery in Mirroring in the High Availability Guide.

Stateless Parameters

The set of parameters relevant to stateless connections are as follows:

Stateless Parameter Function
Minimum Server Connections The Web Gateway implements process affinity. This means that it always attempts to reconnect sessions to the same InterSystems IRIS process that serviced its previous request if possible. This parameter specifies the minimum number of connections that the Web Gateway should make to the InterSystems IRIS server before starting to share the connections among many clients. The higher this number, the more effective process affinity is. The default value is 3.
Maximum Server Connections This is the absolute maximum number of connections that the Web Gateway is allowed to make to the InterSystems IRIS server. If concurrent usage exceeds this number, the Web Gateway starts to queue requests. Requests remain in the queue until an InterSystems IRIS connection becomes available to service the request or the Queued Request Timeout is exceeded. This is unspecified by default, indicating that the only hard maximum is the number of maximum connections for the Web Gateway, which is 1024 by default.
Maximum Connections per Session This represents the maximum number of connections to InterSystems IRIS that can be concurrently used by an individual session. The default value is 3.

Connection Security Parameters

Connection Security settings are required by the Web Gateway to access the InterSystems IRIS application server. These parameters are discussed in Protecting Web Gateway Connections to InterSystems IRIS. The set of parameters relevant to connection security are as follows:

Connection Security Parameter Function
Connection Security Level Level of security required for connecting to the InterSystems IRIS server. Select one of the options:
  • Password

  • Kerberos

  • Kerberos with Packet Integrity

  • Kerberos with Encryption

  • SSL/TLS

Username Username required by the Web Gateway for connecting to the InterSystems IRIS server.
Password Password required by the Web Gateway for connecting to the InterSystems IRIS server.

Alternatively, on UNIX®/Linux/macOS systems, this field can specify an operating system command to retrieve the password programmatically, within braces ({}).

Password (Confirm) When you create a new password, confirm the new password by entering it again.
Product Product being connected to (InterSystems IRIS).
Service Principal Name Service principal name. A Generate button is provided for creating a default name with respect to the target InterSystems IRIS server.
Key Table Full path to the Key Table file.

SSL/TLS Parameters

The following parameters are relevant only to installations using SSL/TLS to secure connections between the Web Gateway and InterSystems IRIS.

SSL/TLS Parameter Function
Minimum SSL/TLS Protocol Version

Minimum version of the SSL/TLS protocol to use. The following options are provided:

  • TLSv1.0

  • TLSv1.1

  • TLSv1.2

  • TLSv1.3 (on platforms where it is supported)

On platforms where TLSv1.3 is supported, the default value is TLSv1.2. Otherwise, the default value is TLSv1.1.

Maximum SSL/TLS Protocol Version

Maximum version of the SSL/TLS protocol to use. The following options are provided:

  • TLSv1.0

  • TLSv1.1

  • TLSv1.2

  • TLSv1.3 (on platforms where it is supported)

On platforms where TLSv1.3 is supported, the default value is TLSv1.3. Otherwise, the default value is TLSv1.2.

SSL/TLS Key Type

The type of SSL/TLS key file (based on the algorithm used to generate it). The following options are provided:

  • DSA — Digital Signature Algorithm

  • RSA — Rivest, Shamir, and Adelman (inventors of the algorithm)

The default is RSA.

Require Peer Certificate Verification If checked, requires peer certificate verification for this installation.
SSL/TLS Cipher Suites (TLSv1.2 and below) Cipher suites for TLSv1.2 and below. The default is ALL:!aNULL:!eNULL:!EXP:!SSLv2.
SSL/TLS Cipher Suites (TLSv1.3) Cipher suites for TLSv1.3. The default is TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256. Available only on platforms where TLSv1.3 is supported.
SSL/TLS Certificate File

The full path to the SSL/TLS certificate file for the Web Gateway. Supported file formats for certificate files are the same as those supported for InterSystems IRIS TLS Configurations.Example: C:\InterSystems\certificates\clicert.pem

SSL/TLS Private Key File

The full path to the private key associated with the Web Gateway’s SSL/TLS certificate. Supported file formats for certificate files are the same as those supported for InterSystems IRIS TLS Configurations.Example: C:\InterSystems\certificates\clikey.pem

SSL/TLS CA Certificate File

The full path to the certificate for Certificate Authority (CA) for the Web Gateway’s certificate. Supported file formats for certificate files are the same as those supported for InterSystems IRIS TLS Configurations.Example: C:\InterSystems\certificates\cacert.pem

SSL/TLS Private Key Password The password to the SSL/TLS Private Key.

Alternatively, on UNIX®/Linux/macOS systems, this field can specify an operating system command to retrieve the password programmatically, within braces ({}).

Optional Parameters

The descriptions of the Optional Parameters are given in Configuring Default Parameters, If any of these parameters is blank, its value is inherited from the Web Gateway global configuration described in Connections to InterSystems IRIS.

Error Pages

The Error Pages parameters let you customize the Web Gateway responses. If not specified, the parameters are inherited from the global configuration. For a description of each parameter, see Custom Error Pages.

Copy a Server Access Profile

You can quickly configure a new server access profile by copying an existing server access profile. Having done this, both configuration entries are identical, except for the server name. You can then edit the second configuration and make changes to it (such as changing the IP address).

Tip:

This feature is also useful for fine-tuning a configuration. By creating a second (temporary) configuration for a server, you can test parameter changes without worrying about losing the original configuration.

To copy an existing server access profile:

  1. From the Web Gateway management pages main menu, select Server Access.

  2. At the Server Access screen, select an existing server name.

  3. Select the Copy Server option.

  4. Select Submit. The second configuration screen appears.

  5. In the Server Name text box, enter a unique, descriptive name for the new server.

  6. Select Save Configuration.

Disable Access to an InterSystems IRIS Server

Use this facility to prevent users from accessing a configured InterSystems IRIS server through this Gateway installation.

To disable access to a server:

  1. From the Web Gateway management pages main menu, select Server Access.

  2. At the Server Access screen, select an existing server name.

  3. Select the Edit Server option.

  4. Select Submit. The Server configuration screen appears.

  5. For the Server Status parameter, select Disabled.

  6. Select Save Configuration.

To re-enable access, repeat the procedure and select Enabled at Step 5.

Delete a Server Access Profile

To delete a server access profile:

  1. From the Web Gateway management pages main menu, select Server Access.

  2. At the Server Access screen, select a server name.

  3. Select the Delete Server option.

  4. Select Submit.

  5. Confirm by selecting YES : DELETE.

FeedbackOpens in a new tab