Skip to main content

Configuring the Default Parameters for Web Gateway

This article describes how to configure the default parameters for InterSystems IRIS® Web Gateway via the Web Gateway management pages. Other articles describe how to configure servers and applications.

The Default Parameters option on the Web Gateway management pages controls all the global (system-wide) configuration parameters for the Web Gateway. Note that you must be a system manager to use this option.

When you configure access to a particular InterSystems IRIS Server, any unspecified optional parameters and/or custom system forms are automatically inherited from the global configuration. For example, if you do not set a Server Response Timeout parameter for a specific server, that server inherits the global Server Response Timeout setting.

Web Gateway

This section contains parameters that are globally relevant to the whole Web Gateway installation.

Instance Host Name

This is the network host name for this particular instance of the Web Gateway. The Web Gateway generates a default value which is shown beneath the text box. The value of this parameter is transmitted to InterSystems IRIS with the request data as system variable CSPIHN. Your application can use the value to access management services provided by the Web Gateway over the network.

The format for this parameter is: server_name:port

Maximum Connections

Maximum number of connections to InterSystems IRIS that can be created from this Gateway instance. The default value is set to 6. Increasing this value allows better application responsiveness if an application uses more connections but may also result in heavier server resource utilization.

Changes to the Maximum Connections parameter only take effect after a restart of the Web Gateway (or the hosting web server).

Maximum Cache Size

Maximum amount of shared memory to be reserved for the purpose of caching CSP response data.

The cache size may be specified as a number with no suffix for bytes, a number followed by K for kilobytes, or a number followed by M for megabytes.

The default value for this parameter is 256K. This value can be raised or lowered as required.

Changes to the Maximum Cache Size parameter only take effect after a Gateway (or hosting web server) restart.

Web Server ID Cookie

Suppresses the Web Server ID Cookie (CSPWSERVERID). It can be set to:

  • Enabled (Default)

  • Disabled

The Web Server ID Cookie is used to enable load balancers to implement passive cookie affinity for web applications. However, there are situations where it is desirable to suppress the automatic generation of this cookie. For example, in proxy applications where the web request is transparently passed to other servers for processing.

The Web Server ID Cookie is not dispatched when returning resources that are deemed to be static (i.e. images and JS files). In this context, static files include all responses generated by InterSystems IRIS that are not accompanied by a Web Server ID Cookie. An exception to this rule is made for cases where the application is configured to Never use session cookies. In this case the Web Server ID Cookie is included with all responses (as before).

Security

If a username and password are defined here, then all system managers must provide this username and password to access the Web Gateway management pages.

If you forget the password, use the following procedure to set a new password:

  1. Edit the configuration file to specify a new value for the Username and Password; make the changes in the SYSTEM section of the file. You can specify the value of the password in plaintext.

  2. Restart the web server. The web server reloads the configuration and updates the file to hold the password hash instead of the plaintext password.

You can now log in to the web server with the updated username and password.

[SYSTEM]
Username=cm
Password=1Bx4tt88mttAWaf7isJg3Urqc2zE

You can configure the following CSP security parameters:

Access to these forms

Enable or disable access to the Web Gateway management pages option. The default is Enabled. When access is Disabled you cannot re-enable access using the Web Gateway management pages. To re-enable access, manually edit the configuration file. Set the SM_Forms parameter to Enabled in the SYSTEM section of this file.

[SYSTEM]
SM_Forms=Enabled

Username

Username required to access the Web Gateway management pages.

Password

Password required to access the Web Gateway management pages.

Password (Confirm)

When the password is modified, confirm the new value here.

Session Timeout

The amount of idle time (in seconds) that an active Systems Management session remains logged on. After this time has expired, the management session expires and the manager is automatically logged out of the Web Gateway management pages.

System Manager Machine/s

Defines a list of client machines (by IP address) through which you can access these Systems Management options. Any client with System Manager access can add or delete access to any CSP system, change any setting in the configuration file, and close down any active sessions. The addresses are separated by either a comma or a plus sign. In this example, two clients have System Manager access:

127.0.0.1, 45.123.231.12

If this field is undefined, only a client operating on the same machine as the Web Gateway (that is, the web server host) can configure CSP.

This field is supplemented with a check box (Override Username and Password) which, if checked, allows listed client machines to be exempt from entering a username and password to gain access to the Management Forms.

Custom Login Form

Defines a custom login form that controls access to the Web Gateway management pages. This parameter can be either the full path to a physical file or a link which enables the hosting web server to serve the form.

Examples:

 C:\Inetpub\wwwroot\login.html
 /login.html    

If a physical file name is specified then the Web Gateway retrieves and dispatches the form to the client. Otherwise, it sends an 'HTTP Redirect' response header to enable the client to request the form directly from the hosting web server. The custom form must implement an HTTP POST request to login Gateway Administrators.

The essential form fields are shown below:

<FORM METHOD=POST ACTION="/csp/bin/Systems/Module.cxw">
<INPUT TYPE=HIDDEN NAME="CSPSYS" VALUE="17">
<INPUT TYPE=HIDDEN NAME="CSPSYSsmSection" VALUE="SYSTEM">
<INPUT TYPE=TEXT NAME="CSPUNM" SIZE='20' VALUE="">  
<INPUT TYPE=PASSWORD NAME="CSPPWD" SIZE='20' VALUE=""> 
<INPUT TYPE=SUBMIT NAME="CSPSYSbOK" VALUE="Login"> 

Where CSPUNM is the username and CSPPWD the password. The text assigned to the Login (submit) button (shown as 'Login' above) can be changed.

A simple but complete example is shown below:

<html>
<head>
<title>Web Gateway Management</title>
</head>
<h2>Web Gateway Management</h2>
<FORM METHOD=POST ACTION="/csp/bin/Systems/Module.cxw">
<INPUT TYPE=HIDDEN NAME="CSPSYS" VALUE="17">
<INPUT TYPE=HIDDEN NAME="CSPSYSsmSection" VALUE="SYSTEM">
<BR>
Username: 
<INPUT TYPE=TEXT NAME="CSPUNM" SIZE='20' VALUE="">
<BR>
Password:
<INPUT TYPE=PASSWORD NAME="CSPPWD" SIZE='20' VALUE="">
<BR>
<INPUT TYPE=SUBMIT NAME="CSPSYSbOK" VALUE="Login">
</form>
</html>

Connections to InterSystems IRIS

This section contains parameters related to maintaining connections to InterSystems IRIS.

Server Response Timeout

The maximum number of seconds allowed for the target InterSystems IRIS server to respond to a request from the web server. The timeout refers to a period of no activity, so, for example, sending a line of HTML data every second for 10 hours does not cause a timeout. The minimum allowable value for this field is 5 seconds.

The value set here is the default for the system. If an Inherited Value is specified, the value came from the Default Parameters page. You may, however, set a different value on individual server-specific configurations or within the application itself.

Note that if you have an Apache server, you can also set this value using Timeout in the Apache httpd.conf file. The lower of these two values is triggered first.

Queued Request Timeout

This is the maximum number of seconds that a request can remain in a queue waiting for an available connection to the appropriate InterSystems IRIS system. The minimum allowable value is 5 seconds. If an Inherited Value is specified, the value came from the Default Parameters page.

No Activity Timeout

This parameter is relevant to stateless connections only. The parameter indicates the maximum amount of time (in seconds) that a stateless connection remains open in an idle state before closing. If this timeout is exceeded, the session automatically closes. This facility prevents stateless sessions accumulating on your InterSystems IRIS server, particularly after periods of high activity where a large number of connections were opened to cope with the increased workload. If a value is not specified, stateless connections remain open until they are manually closed. If an Inherited Value is specified, the value came from the Default Parameters page.

Apply timeout to all Connections

Applies the No Activity Timeout option to all connections (including those making up the minimal connection pool). If this option is not checked, the Web Gateway does not apply the No Activity Timeout to the minimal connection pool (as defined by the Minimum Server Connections parameter). If this option is checked the Web Gateway applies the timeout to all connections in the pool. This option is used by installations that have a very low level of CSP usage and, as a result, have a preference for all CSP processes to time out. If an Inherited Value is specified, the value came from the Default Parameters page.

Event Log Level

Controls what information is written to the Web Gateway Event Log. See Event Logging Parameters for details.

Event Log File

Specifies a location and filename for the Web Gateway Event Log. If not specified, it is written to the directory hosting the Web Gateway installation. For example:

To specify an alternative location:

/opt/logfiles/cspgateway/

To specify an alternative location and file name:

/opt/logfiles/cspgateway/event_log_01012006.log

Retain All Log Files

If Event Log Rotation Size is blank (the default), the Web Gateway Event Log grows until the administrator manually clears it. If the capacity of the file is specified by Event Log Rotation Size, InterSystems IRIS copies the log file to a file named filename.old, where filename is the full original filename. Subsequent log rotations overwrite filename.old with the current contents of the log. To retain all log files, select Retain All Log Files. Each log is named with the date and time when the copy took place.

Event Log Rotation Size

This defines the size after which log rotation should take place. The default value is blank which means that the Web Gateway maintains one log file which grows until the administrator manually clears it.

If rotation is required, the size may be specified as a number with no suffix for bytes, a number followed by K for kilobytes, or a number followed by M for megabytes.

The minimum size that can be specified is 100K. This value is automatically set if the administrator attempts to set a lower value in the maintenance suite.

Rotated copies of the log file, if retained, are named according to the date and time of rotation as follows:

CSP_YYYYMMDD_hhmm.log

where YYYY is year, MM is month, DD is date, hh is hour, and mm is minutes past the hour, for example:

CSP_20090109_1830.log (Log rotated at 18:30 on 9th January 2009)

If more than one log file rotation takes place in the space of one minute, a serial number is appended to the file name to prevent duplicates, for example:

03/12/2015  17:02           106,660 CSP_20151203_1702.log
03/12/2015  17:02           124,752 CSP_20151203_1702.log.0001
03/12/2015  17:02           124,752 CSP_20151203_1702.log.0002

The rotated log file that is not to be retained is named: filename.old, where filename is the full original filename.

In order for this facility to work, the Web Gateway must have create/write access to the directory hosting the Web Gateway binaries (i.e. the location where the main log file is kept). If the Web Gateway is unable to perform a successful rotation it continues writing to the current log file.

This field is supplemented with a check box labeled Retain All Log Files. If selected, this option instructs the Web Gateway to keep all log files according to the naming scheme outlined above.

SSL/TLS Library Path

Specifies the path to the OpenSSL libraries. On UNIX®, these files are libssl.so and libcrypto.so, and on Windows, the files are libcrypto-1_1-x64.dll and libssl-1_1-x64.dll. The default is for the Web Gateway to source these libraries locally in its home directory. See Overriding the Library Path If You Use SSL/TLS in Kerberos Library for more information.

Preserve Mode Exclude File Types

Allows static files to be served asynchronously in state-aware applications. In stateless applications, statics (files other than csp, cls, csr, and zen) are processed asynchronously with respect to the main session. In other words, requests for these files bypass the session lock and can be processed concurrently outside the main processing stream for the application.

This parameter allows this scheme to be extended to state-aware applications. State-aware applications are not only subject to the conventional session lock but are also subject to the connection lock in the Web Gateway. The connection lock is responsible for ensuring that all requests for the user/session are routed to the same InterSystems IRIS process. For applications that rely on static components being served from InterSystems IRIS, this leads to excessive request queuing which, in turn, can lead to browser instability (such as hangs).

Use this parameter to define a list of (space separated) file types (by extension) to process asynchronously and therefore exempt from connection/session locking in the Web Gateway and InterSystems IRIS. If the list is prefixed with *- (asterisk hyphen) then all files are processed asynchronously EXCEPT those defined in the following list.

Examples

Preserve Mode Exclude File Types=gif jpg jpeg  

Process files of type GIF, JPG and JPEG asynchronously with respect to the state-aware session:

Preserve Mode Exclude File Types=*- csp cls csr zen  

Process all files asynchronously with respect to the state-aware session EXCEPT those of type CSP, CLS, CSR and ZEN. This, incidentally, is the rule applied in the CSP engine for stateless applications.

This mechanism can be monitored using log level v4. When invoked for a request, a record similar to the one shown below is added to the log.

 >>> Time: Fri Oct 04 14:56:40 2017 ...GET /csp/samples/zenutils.js       
     State-Aware Session (preserve == 1)     
     Process this request concurrently in the pool of stateless connections (File Type=js)

ASP Redirect

Web Document Root

This is the full physical path to the document root directory of the web server. For example, for Microsoft IIS Web Servers, this path is usually c:\InetPub\wwwroot. This parameter is only required if you plan to use the facility within CSP to send the CSP output through the Microsoft ASP engine to render the final page.

Temp ASP Directory

This is the full physical path to a directory where the Web Gateway can temporarily store Microsoft ASP content. This parameter is only required if you plan to use the facility within CSP to send the CSP output through the Microsoft ASP engine to render the final page.

Internal HTTP Server

This section is only relevant to the NSD. This section contains the following parameters:

Service Status

The HTTP server can be Enabled or Disabled. Select either:

  • Enabled

  • Disabled

The default is Enabled.

In the interests of security, it is best to disable this facility, unless it is intended that the NSD should be able to respond to raw HTTP requests.

NSD Document Root

For cases where the NSD is intended to be used as a stand-alone web server in its own right, this parameter defines the full physical path to the web documents root. For example:

/opt/webgateway/home/

If the server is used to serve web applications, then the broker components should be installed under:

/opt/webgateway/home/broker/

The static files used to support the CSP samples:

/opt/webgateway/home/samples/

The static files used to support the Management Portal:

/opt/webgateway/home/sys/

Custom Error Pages

The Error Pages section of the global configuration screen allows you to customize Web Gateway error messages and system responses. These can be set on a global or per-InterSystems IRIS server basis. To customize the default CSP responses, perform the following:

  1. From the Web Gateway management pages main menu, select Default Parameters.

  2. In the Error Pages section, enter the name of the CSP page that you wish to replace the corresponding Gateway page with. Enter the full physical path to your CSP page, or enter a path relative to that of the Web Gateway.

  3. Select Save Configuration.

You can customize the following Web Gateway system responses:

Server Error

Page to display when the Web Gateway encounters an internal error. For example, an error occurs if there is a problem communicating with an InterSystems IRIS server. The specific error is always recorded in the Web Gateway Event Log.

Server Busy

Page to display when all available CSP connections are in use.

Server Unavailable

Page to display when the InterSystems IRIS server (or application) has been deliberately disabled from within the configuration.

Server Timeout

Page to display when the request has timed out.

Connection Closed

Page to display when you log out of a state-aware session.

Event Logging Parameters

The Event Log Level field specifies the information that Web Gateway writes to the Web Gateway Event Log. Logging options are defined as a string of characters, each character representing a logging command. The value set here for the log level is the default for the system (that is, all InterSystems IRIS servers). Except where noted, you can set a different value for individual InterSystems IRIS servers.

You can view or clear the log from the CSP Web Management page menu. The logging parameters, shown below, are used mainly for troubleshooting:

Logging Option (Not Case-Sensitive) Function
E Record all errors. This option allows you to monitor connection failures.
V Verbose: Record the basic connection dialog between the Web Gateway and an InterSystems IRIS system. Use this option to record the strategic points of communication between the Web Gateway and an InterSystems IRIS server. There are 7 levels to this command (1 to 7). Each successive level records more detailed information. The levels are accumulative. For example, level V3 includes all log information specified for V1 and V2.
EV Enter EV to turn on basic event logging. The higher log levels generate a large volume of data in the log file and should only be used for diagnosing problems. For production systems it is recommended that the log level should be set to no higher than EV.
V1 Same as V.
V2 In addition to the information specified for previous levels, this level records:
  • Information regarding basic connection management between the Web Gateway and InterSystems IRIS (Start and Close points for each connection).
  • Transmission interrupts received from the browser.
  • Cases where connections to InterSystems IRIS are forcefully closed (due to a lack of response from InterSystems IRIS or other errors where the connection cannot be recovered).
  • Access violations in state-aware (preserve mode 1) sessions (For example, Invalid Session ID).
V3 In addition to the information specified for previous levels, this level records: InterSystems IRIS headers and HTTP headers.
Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.
V4 In addition to the information specified for previous levels, this level records: Information regarding the serialization of state-aware sessions.
Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.
V5
In addition to the information specified for previous levels, this level records the contents of data buffers received from, and sent to, InterSystems IRIS via the WebSocket protocol. All data framing (where applicable) is also recorded. Finally, further information about the nature of the WebSocket created is also recorded at initial connection time. For example:
  • WebSocket Connection
  • WebSocket Connection Accepted by InterSystems IRIS: WSClassProtocolVersion=2; SharedConnection=0; NoDataFraming=2; BinaryData=1;
Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.
V6 In addition to the information specified for previous levels, this level records:
  • Headers to the data blocks sent to InterSystems IRIS.
  • Request Data from the web server (except multipart attachments).
  • Headers to the data blocks received from InterSystems IRIS.
Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.
V7 In addition to the information specified for previous levels, this level records: The full content returned from InterSystems IRIS.
Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.
V9 Record incoming HTTP request data. The HTTP headers and posted content (where applicable) are recorded. (Does not record information for levels 1–7.) This log directive can be further extended and refined.
  • v9r: In addition to logging all HTTP requests, record all HTTP responses.
  • v9a: Record all HTTP requests to http.log in the Web Gateway home directory.
  • v9b: Record all HTTP requests on a per-session basis. Log files of the form http[session_id].log is created in the Web Gateway home directory, where session_id is the 10-Byte session ID.
  • v9m: Log all multi-part posts in the Web Gateway home directory. The raw incoming HTTP request are recorded together with the individual components in both their encoded and decoded form.
Note: The forms V9, V9r, V9a, and V9b have no effect when specified for individual servers. These forms of logging can be enabled only at the default level.
s
Sessions: Record information about the management of session tokens:
  • The point at which new session IDs are allocated.
  • For existing sessions: an indication as to whether the session token was extracted from a cookie or the form/URL variable CSPCHD.
  • For all requests: the final session ID transmitted to InterSystems IRIS.
Note: This logging option has no effect when specified for individual servers. This option can be enabled only at the default level.
c
Connections: Record information about connections made using the Kerberos Library (IRISCONNECT).
Include a log level of lowercase c to instruct the Web Gateway to record a complete audit of all IRISCONNECT functions called, together with the input parameters supplied and the result returned. For the sake of brevity, the content of the input and output buffers to and from InterSystems IRIS are not recorded at this level. Set a log level of uppercase C to record, in addition to the IRISCONNECT function calls, the contents of the input and output buffers.
In addition to the logging facilities provided by the Web Gateway, it is possible to instruct the IRISCONNECT library to generate a detailed trace recording its internal processes. To additionally request that a IRISCONNECT trace be generated, add a digit to the c directive to indicate the type of trace required.
For example, a log level of c3, in addition to the standard Gateway log entries, generates a level 3 IRISCONNECT trace. Valid IRISCONNECT trace levels are 1 to 6 and are defined as follows:
  • 6 — errors
  • 5 — warnings
  • 4 — informational message
  • 3 — output data
  • 2 — input data
  • 1 — normal events
Unlike the Web Gateway log levels, the IRISCONNECT trace is less verbose at the higher log levels. Log level 1, therefore, provides the most detailed trace file. The Web Gateway instructs the IRISCONNECT library to maintain its trace in a file called irisconnect.log located in the Web Gateway home directory. The security considerations and permissions for this file are the same as those for the Web Gateway Event Log.
Note: An IRISCONNECT trace can only be activated on a per-process basis, so it cannot be truly isolated to a server. Once configured, trace log generation is not triggered until a new SSL connection is attempted.
t
Transmission: Record the raw data buffers received by and dispatched by the Web Gateway. The format for this option is: t[x][y].
The value of x instructs the Web Gateway to record data buffers transmitted between the Web Gateway and InterSystems IRIS and the value of y instructs the Web Gateway to record data buffers transmitted between the Web Gateway and the client, via the hosting web server.
x and y can take the following values:
  • 0: No transmission data to be recorded.
  • 1: Record request data only.
  • 2: Record response data only.
  • 3: Record request and response data.
Using lowercase t results in the Web Gateway recording just the first 256 Bytes of transmitted data for each buffer. Using uppercase T results in the Web Gateway recording the full data buffer. All non-printable characters are recorded in their escaped form.
Note: When this logging level is specified for an individual server, y options record response buffers sent to the client, but not incoming request buffers from the client.
p[n]
Performance: Instructs Gateway to capture information to assess the performance of the CSP installation.
n is the number of seconds (total service time) below which data is not recorded for a request. For example, a directive of p records data for all requests, p2 records data for requests taking longer than 2 seconds to service.
The following information is recorded.
  • Total time to service request: The total time spent in servicing the request (from the time it reaches the Web Gateway to the time at which the last Byte of response data leaves the Web Gateway environment.
  • Obtain [NEW] connection to InterSystems IRIS: Time taken between the request reaching the Web Gateway and a connection to InterSystems IRIS being reserved for the purpose of servicing the request. The message recorded indicates if a new connection is created during this time (as opposed to an existing one being reused).
  • Send request to InterSystems IRIS: Time taken between the first and last Byte of request data being read from the web server and dispatched to InterSystems IRIS.
  • Processing request in InterSystems IRIS: Time taken between the last Byte of request data being dispatched to InterSystems IRIS and the first Byte of response data being received by the Web Gateway.
  • Receive response from InterSystems IRIS: Time taken between the first and last Byte of response data being received from InterSystems IRIS and dispatched to the web server.
p[n]([v])
Provides the capability to conditionally activate verbose logging based on the results of the performance monitor. Useful in situations where you want to record further information about requests that take more than a certain time to process.
n is the optional lower time-to-service threshold (in seconds) for which performance data is recorded and v is the verbose log level required.
This mechanism only applies to the verbose Event Log settings. A request to record error information, e is always applied to all requests regardless of whether or not they are recorded by the performance monitor.
For example:
ep5(v9)This option records any errors encountered while processing requests for all requests (e). In addition, it records the HTTP request message (v9) but only for requests that take longer than 5 seconds to process (p5).
Gateway event logging is designed to have a minimal impact on performance and to occupy a small footprint in terms of system resources consumed. Therefore, the following limitations apply:
  • Only one verbose log level can be specified per individual setting. In other words it is not possible to specify a v9 level for requests recorded by the performance monitor and a v2 level for all other requests. For example, if v2p5(v9) is specified then only the conditionally applied v9 level is honored.
  • The Web Gateway configuration allows you to specify an Event Log level both globally and on a per server basis. When verbose logging is in force, some records are written before the target InterSystems IRIS server has been identified so, for best results, it is best to specify conditional logging at the global level under Default Parameters.
pp[n]
Provides detailed timing information as follows:
  • Pre-processing of request: Time taken to identify the target InterSystems IRIS server; includes the initial handover from the web server and basic request processing to identify the server.
  • Obtain [NEW] connection to InterSystems IRIS: Time taken to allocate a connection to the appropriate InterSystems IRIS server. Indicates whether a new connection is created (instead of an existing one reused).
  • Format request: Time taken to parse and format the request message for transmission to InterSystems IRIS.
  • Send request to InterSystems IRIS: Time taken between the first and last byte of request data read from the web server and dispatched to InterSystems IRIS.
  • Processing request in InterSystems IRIS: Time taken between the last byte of request data dispatched to InterSystems IRIS and the first byte of response data received by the Web Gateway.
  • Post-processing of response(b): When a content-length header is required, this reports the time taken for the dispatch of the response data back to the client via the web server.
  • Post-processing of response(c): Time taken between the dispatch of the response and the Web Gateway being ready to read the response footer data from InterSystems IRIS. The footer data is part of the internal communication protocol between the Web Gateway and InterSystems IRIS and includes control information (For example: instructions to change the preserve setting for the session).
  • Receive footers from InterSystems IRIS: Time taken to receive the response footer data from InterSystems IRIS.
  • Post-processing of footers: Time taken to process footer data and respond to instructions received.
  • Release connection to InterSystems IRIS: Time taken to release the active connection to InterSystems IRIS.
  • Cleanup: Time taken to release resources used in servicing the request and return control back to the hosting web server.
Feedback