docs.intersystems.com
Home / Web Gateway Configuration Guide / Web Gateway Operation and Configuration

Web Gateway Configuration Guide
Web Gateway Operation and Configuration
Previous section           Next section
InterSystems: The power behind what matters   
Search:  


This topic describes how to configure the InterSystems IRIS™ Web Gateway and exploit its functionality in web applications. It contains the following sections:
Web Gateway Management Pages
The Web Gateway Management pages allow you configure and manage the Web Gateway, including monitoring its operational status. The following table shows the options available on the Web Gateway Management Main Menu page.
Menu Item Action
About Web Gateway Shows the Web Gateway version, the hosting web server environment, including the path to the Web Gateway configuration.
System Status Displays the status of active server connections. Also allows you to clear the Web Gateway cache.
Test Server Connection Tests the connection to an InterSystems IRIS server by opening a stateless session. There is also an option to display the server-side Event Log.
View Event Log Allows you to view information in the Web Gateway Event Log, as well as clear its contents. The Event Log is maintained on the web server host.
View HTTP Trace Provides an interactive view of the HTTP requests and responses processed by the Web Gateway.
Default Parameters Allows you to configure the Web Gateway on a specific web server. Also, it allows you to customize CSP responses to errors and other conditions.
Server Access Configures Web Gateway access to a specific InterSystems IRIS server.
Application Access Configures the access to an application according to the application path. Path, in this context, refers to the path contained within the application URLs.
Back to Management Portal Returns to the Management Portal page.
The Web Gateway Documentation, which provides online help on configuring the Web Gateway, is available through the Help button on the Web Gateway Management pages. Navigate to System Administration > Configuration > Web Gateway Management. If the page asks you to log in, enter your username and password (see below). Then select Help.
By default, the navigation path in the previous paragraph takes you to pages for the private web server. To see the Web Gateway Management pages for your production web server, substitute localhost for localhost:52773 in the URL, as http://localhost/csp/bin/Systems/Module.cxw.
For more information on default InterSystems IRIS web service server port numbers, see the WebServerPort entry of the Advanced Configuration Settings Reference.
The first time you try to access the Web Gateway Management pages, you are asked for a username and password. Look for the username in the install-dir\CSP\bin\CSP.ini file. The password is the one that you entered during the InterSystems IRIS installation. If you forget the password, see the section Security.
Localization of the Web Gateway Management Pages
Localization of the Web Gateway Management pages is based on the contents of the file CSPres.xml, if it is installed. If no localization file is present then the Web Gateway Management pages default to using the embedded English text. The language settings of the browser have no influence on this mechanism.
You can support alternative languages by installing the appropriate text resource file as a file named CSPres.xml in the Web Gateway’s home directory. When the Web Gateway starts or restarts, it loads the text resources found in CSPres.xml and the Management forms then appear in the chosen language.
To create a CSPres.xml file, rename the appropriate CSPres_xx.xml file in the InterSystems IRIS bin directory to CSPres.xml.
For example, to convert to Spanish:
  1. Restart the web server. You must restart because the language text affects the CSP module for the given web server.
To convert back to English (Default):
  1. Rename CSPres.xml back to CSPres_es.xml
  2. Restart the web server.
Security Considerations with Web Gateway Management Pages
By default, only clients local to the Web Gateway’s hosting computer are allowed access to the Web Gateway Management pages. The browser through which the management forms are accessed must be running on the same machine as the web server and Web Gateway. For example:
http://localhost:<port_no>/csp/bin/Systems/Module.cxw
You can add additional clients to the list of authorized administrators by adding the client IP addresses to the System_Manager parameter in the SYSTEM section in CSP.ini (in install-dir\CSP\bin). The System_Manager parameter represents a comma- (or plus-, + ) separated list of clients (by IP address) who may access the Web Gateway Management pages. The directive shown below grants access to three remote clients in addition to the default local access.
[SYSTEM]
System_Manager=190.8.7.6, 190.8.7.5, 190.8.7.4
For new Gateway installations, for which there is no local browser available, manually create this configuration setting by editing CSP.ini.
The System_Manager parameter in CSP.ini is equivalent to the Systems Manager Machines setting, found under the Default Parameters section of the Web Gateway Management pages. You can specify wildcard and numeric ranges in the entries for the Systems Manager Machines parameter.
The following example indicates that the last part of the IP address can take the value of a number between 4 and 6 inclusive.
[SYSTEM]
System_Manager=190.8.7.4-6
The previous example is a more convenient way of writing:
[SYSTEM]
System_Manager=190.8.7.6, 190.8.7.5, 190.8.7.4
You can also use wildcards, such as, in this example:
[SYSTEM]
System_Manager=190.8.7.*
The following directive grants access to all clients:
[SYSTEM]
System_Manager=*.*.*.*
However, it is not recommended that such a directive be used on operational systems.
There are shortcomings in using this scheme as a way of protecting the Web Gateway Management pages. This scheme does not provide strong security. To check web clients, the IP address of a client is obtained from the CGI environment variable REMOTE_ADDR. Client IP addresses can be spoofed.
The use of a proxy between the client and the web server/Gateway installation effectively translates all client IP addresses to that of the proxy. In this scenario you would have to either specify the proxy’s IP address as a Gateway Systems Manager (which would effectively grant access to all web users coming in through the proxy) or, preferably, enable the designated systems managers to bypass the proxy layer altogether.
The IP-based scheme, while useful as a first line of defense, should not be relied upon as the sole means through which access to the Web Gateway Management pages is controlled – certainly not for CSP installations that are available over the Internet. For production systems it is recommended that you use the hosting web server configuration to control access to the Web Gateway systems management modules.
Checking System Status
The System Status option displays the status of all active CSP connections. You must be a system manager to use this feature. In each of the tables below, click a column head to sort by that column.
First Table: Connections to InterSystems IRIS
The first status table (Connections to InterSystems IRIS) displays information on connections to InterSystems IRIS.
Item Function
Connection Number Number that the Web Gateway assigns to the connection. Your InterSystems IRIS license determines the number of possible connections.
Gateway PID The Web Gateway (or hosting web server) process ID for the connection.
Server Name Name of the InterSystems IRIS system connected to. Mirror members show current configuration name with mirror member name appended.
InterSystems IRIS PID Process ID on the InterSystems IRIS server.
Status Indicates whether information is being sent to or from the InterSystems IRIS system, as follows: Free — no information is being sent and the connection is ready to process the next request. In Use — information is being transmitted through the connection. Private — the connection is state-aware (preserve mode 1) and not free for general use. Server — the connection is being used by the InterSystems IRIS server.
Idle time/Timeout Indicates the amount of time that the connection has been idle against the timeout applied to that connection. The timeout is the ‘No Activity Timeout’ for connections in the state-less pool and the ‘Application timeout’ for connections marked as ‘Private’ (state-aware).
Activity Number of transactions (hits) the connection has processed.
Interrupt For a connection with status ‘In Use’, an Interrupt button will attempt to interrupt the corresponding InterSystems IRIS process and return it to the state where it is ready to accept the next web request.
Close If available, allows you to forcefully close down the connection by selecting it.
Second Table: InterSystems IRIS Servers
The second status table (InterSystems IRIS Servers) displays information on InterSystems IRIS servers.
Item Function
Server Number The number that the Web Gateway assigns to the server.
Server Name Name of the InterSystems IRIS system connected to.
Mirror Member For mirror-aware configurations, the name of the mirror member.
Mirror Status For mirror-aware configurations, the name of the mirror configuration along with the mirror status of the server. The member type, Failover or Async, will be shown and the Primary will be labeled as 'Primary'.
Total Connections Number of connections to the InterSystems IRIS system.
Connections In-Use Number of connections that are currently in use (actively serving a Web request).
Private Connections Number of connections that are currently in use as state-aware sessions (preserve mode 1).
Total Activity Number of transactions (hits) the InterSystems IRIS system has processed.
Queued Requests Number of Web requests that are held in a queue waiting for a free connection to the InterSystems IRIS system. Queued requests are an indication that the InterSystems IRIS license should be increased in order to maintain good performance.
Close Close all connections on this InterSystems IRIS server.
Third Table: Application Paths
The third status table displays information for application paths.
Path Number The number that the Web Gateway assigns to the application path.
Path The application path.
Server Number The number that the Web Gateway assigns to the InterSystems IRIS server.
Server Name The name of the InterSystems IRIS system connected to.
Activity The number of requests processed by this server for this path since the last Gateway.
Status The status for this server, one of Disabled, Enabled or Offline. Also the current master (or primary) server in the set is indicated in this column.
Action If a server is marked as Offline, this column contains a button allowing Administrators to mark it Online/Enabled again.
Fourth Table: Web Gateway Cache
The fourth status table lists the forms held in the Web Gateway response cache.
Item Function
Cached Forms
Name (including path) of cached form.
Cached Data (Bytes)
Amount of cached form data held in the Gateway (in Bytes).
Cache Blocks In Use
Total number of cache memory blocks in use.
Cache File
Name of physical file if permanent storage (on the web server host) is used to cache the file.
Cache Form Activity
Total number of times this form has been requested from the cache.
Clear
Clear this form from the cache.
Clearing the Cache
Under certain circumstances, such as during the development process for Web applications, it may be necessary to clear the Web Gateway cache. To do this:
  1. On the System Status page, there are a number of tables. To clear the cache, in the Cached Forms table, select the button in the Clear column (the right-most column) and the Total row (the bottom row). If the System Status page does not display a Cached Forms table, then there is no currently cached content. This may be because the cache has been cleared recently and nothing has been cached since then.
This action clears all cached content for the Web Gateway and removes the Cached Forms table from the page until there is new cached content.
Closing Connections Manually
If your InterSystems IRIS system shuts down while a CSP connection is still active, CSP continues to try to connect to the system until one of the following occurs:
If your InterSystems IRIS system is scheduled for extensive downtime, you may want to close the connections. You can close sessions manually using the Close button on the System Status page.
Note that you can close the connections while the InterSystems IRIS system is down.
Testing Server Connections
The Test Server Connection option on the Web Gateway Management Main Menu is useful to test Web Gateway connectivity to your InterSystems IRIS systems. Note that you must be a system manager to use this feature.
To test CSP connectivity:
  1. From the Web Gateway Management Main Menu, select Test Server Connection.
  2. Select the desired InterSystems IRIS system from the displayed list.
  3. Select Connect.
Depending on your selection and the state of the server connection, you receive one of the following results:
Result Meaning
CSP Test Form The Web Gateway is working correctly and is able to connect to InterSystems IRIS. The form shows the basic parameters returned by the target InterSystems IRIS server (version and process ID).
Server Availability Error This error occurs any time that InterSystems IRIS is unreachable. If there are no additional error messages, check to ensure your InterSystems IRIS system is running.  Also, check the Event Log for specific connectivity error messages.
In all cases where an error condition is returned, check the Event Log for additional and more specific error information. Consider raising the Log Level to capture even more diagnostic information where necessary.
Viewing the Event Log
Use the View Event Log option from the Web Gateway Management Main Menu to read the contents of the Event Log.
When CSP.log reaches its capacity as specified by Event Log Rotation Size it is copied to CSP.log.old. If Event Log Rotation Size is blank (the default) CSP.log grows until manually cleared. To save all logs in files named with date and time, select Retain All Log Files on the Default Parameters page. Each log entry is marked with a header record which captures the date, time and additional information with respect to the context in which the log entry was made.
Example:
>>> Time: Wed Jul 26 15:40:57 2006; RT Build: 664.896 (win32/isapi);
Log-Level: 9; Thread-Id: 2236; Connection-No: 0; Server: LOCAL;
Server-PID: 3028; Page: GET /csp/samples/menu.csp 
Select Clear Log to clear all current entries from the Event Log.
The Log can be displayed in either ascending date/time order (the default) or descending date/time order. Select the hyperlink at the top right-hand corner of the form to reverse the display order. This hyperlink acts as a toggle between the two modes.
Finally, most browsers are unable to render more than about 1MB of log data in a single form. Therefore, as the volume of log data returned approaches 1MB the Web Gateway terminates the display and prompts for the next page of data See the More hyperlink at the bottom left-hand corner of the form. Additionally, a Top hyperlink is provided at the bottom right-hand corner of the form to allow you to quickly go back to the first form in the series.
Using the HTTP Trace Facility
The HTTP trace facility builds on the Event Log information already captured for log levels v9 (record raw HTTP request) and v9r (record both HTTP request and response). The trace is accessed via the View HTTP Trace option.
The trace window consists of two main frames. The left-hand frame contains a list of HTTP requests processed by the Web Gateway by time and a unique request ID (assigned by the Web Gateway). As each request is selected, the request and response data is shown in the right-hand frame. Hyperlinks allow easy navigation between the request and response message.
The request listing is automatically refreshed every few seconds (currently 7) so that the overall effect is of a real-time monitor operating in much the same way as a proxy such as TCPTrace.
Note:
Note that the HTTP request headers reported by the Web Gateway are reconstituted because the hosting web server always assumes responsibility for parsing the request headers. The Web Gateway reassembles the complete header from the CGI environment variables supplied by the web server. However, if a request is passed directly through the NSD component (that is, effectively bypassing the web server), then the request header recorded is byte-for-byte the same as it was when dispatched from the client.
Configuring Default Parameters
The Default Parameters option on the CSP Web Management page menu provides you with a mechanism for maintaining 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.
The Default Parameters are made up of up to six components:
Web Gateway
This section contains parameters that are globally relevant to the whole 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 follows:
In Bytes n
In Kilobytes nK
In Megabytes nM
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:
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, manually edit the Web Gateway configuration file CSP.ini and remove the Username and Password parameters from the SYSTEM section of this file. Then you can access the Web Gateway Management pages without a username and password and enter a new username and password if required.
[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 using this 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 CSP.ini. 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 Event Log. See the Event Logging Parameters section for details.
Event Log File
Specifies a location for the Event Log file (CSP.log). If not specified, it is written to the directory hosting the Web Gateway installation. For example:
To specify an alternative location for CSP.log:
/opt/logfiles/cspgateway/
To specify an alternative location and file name for the Event Log:
/opt/logfiles/cspgateway/event_log_01012006.log
Retain All Log Files
If Event Log Rotation Size is blank (the default) CSP.log grows until the administrator manually clears it. If the capacity of CSP.log is specified by Event Log Rotation Size, InterSystems IRIS copies the CSP.log file into a file named CSP.log.old. Subsequent log rotations overwrite CSP.log.old with the current contents of the Event 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.
In Bytes n
In Kilobytes nK
In Megabytes nM
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
YYYY year
MM month
DD day of the month
hh hour of the day
mm 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: CSP.log.old
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, CSP.log.
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: libssl.so and libcrypto.so. The default position 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 the section Kerberos Library in this book for more information. This parameter is available only on UNIX® systems.
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 Gateway Log Level 4 (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:
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 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.
The Web Gateway system responses that you can customize are as follows:
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 allows you to control what information the Web Gateway writes to the Event Log. Logging options are defined as a string of characters, each character representing a logging command. The value set here for the Event Log level is the default for the system (that is, all InterSystems IRIS servers); however, you may set a different value for individual InterSystems IRIS Servers.
The Web Gateway writes the Event Log to the serial file named CSP.log. This file is placed in the same directory as the Web Gateway runtime module. You can view or clear the Event Log from the CSP Web Management page menu. The logging parameters are used mainly for troubleshooting. The following table shows the logging options, which can be expressed in lower- or uppercase.
Logging Option 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 no response from InterSystems IRIS or other errors where the connection can't 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.
V4 In addition to the information specified for previous levels, this level records: Information regarding the serialization of state-aware sessions.
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;
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.
V7 In addition to the information specified for previous levels, this level records: The full content returned from InterSystems IRIS.
V9 Record incoming HTTP request data. The HTTP headers and posted content (where applicable) are recorded. (Does not record info 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.
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.
c
Connections: Record information about connections made using the Kerberos Library (IRISCONNECT).
Include a log level of lower-case 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 upper-case 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 (CSP.log).
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 lower-case t results in the Web Gateway recording just the first 256 Bytes of transmitted data for each buffer. Using upper-case T results in the Web Gateway recording the full data buffer. All non-printable characters are recorded in their escaped form.
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.
Configuring Server Access
The Server Access option allows you to:
Each InterSystems IRIS system accessed by the Web Gateway must be defined here. Any unspecified optional parameters or custom system forms are automatically inherited from the Web Gateway global configuration.
Adding a Server Configuration
To configure access to an InterSystems IRIS server:
  1. From the Web Gateway Management 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 configuration.
Server Access
The set of base server configuration parameters are as follows:
Server Configuration Parameter Function
Server Name Logical name to identify this server configuration in the CSP configuration file.
Service Status Allows you to enable and disable this configuration (default is Enabled).
IP Address The 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 usually 51773.
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.
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.
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.
Maximum Connections per Session This represents the maximum number of connections to InterSystems IRIS that can be concurrently used by an individual session.
Connection Security
Connection Security settings are required by the Web Gateway to access the InterSystems IRIS server. These parameters are discussed in greater depth in a later section. 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.
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
SSL/TLS Protocol
The version of the SSL/TLS protocol to use. The following options are provided:
  • SSLv2
  • SSLv3
  • TLSv1
  • TLSv1.1
  • TLSv1.2
The default TLS protocol is: TLSv1+TLSv1.1+TLSv1.2. The default for CipherList is: “ALL:!aNULL:!eNULL:!EXP:!SSLv2"
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 Certificate File
The full path to the SSL/TLS certificate file for the Web Gateway.
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.
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.
Example: C:\InterSystems\certificates\cacert.pem
SSL/TLS Private Key Password The password to the SSL/TLS Private Key.
Optional Parameters
The descriptions of the Optional Parameters are given in the Configuring Default Parameters section. If any of these parameters is blank, its value is inherited from the Web Gateway global configuration described in the section 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 the Custom Error Messages section.
Copying a Server Configuration
You can quickly configure a new server by copying the configuration entry of an existing server. 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).
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 configuration:
  1. At the Server Access screen, select an existing server name.
  2. Select the Copy Server option.
  3. Select Submit. The second configuration screen appears.
  4. In the Server Name text box, enter a unique, descriptive name for the new server.
Disabling Access to a Configured 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 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.
To re-enable access, repeat the procedure and select Enabled at Step 5.
Deleting a Server Configuration
To delete a configured server:
  1. From the Web Gateway Management Main Menu, select Server Access.
  2. At the Server Access screen, select a server name.
  3. Select the Delete Server option.
  4. Select Submit.
Configuring Application Access
The Configure Application Access option allows you to:
Each web application must have the path to its CSP files configured. The configuration for each path identifies the InterSystems IRIS server responsible for running the application. Optional directives for specifying failover and load-balancing are included in the application path's configuration. The default application path, root, (/) is automatically configured when the Web Gateway is started for the first time. Inheritance is applied to application paths. For example, if a CSP request asks for a file in /Accounts/Invoices and there is no configuration for /Accounts/Invoices, the Web Gateway uses the configuration defined for /Accounts. If this is not defined, the configuration for the default path of / is used.
Adding an Application Path
To configure the path to an application:
  1. Select Add Application. Note that many parameters have default settings.
  2. In the Application Path text box enter a unique path for the application. This path is the path which appears in the application URLs.
    Note:
    An InterSystems IRIS installation creates a new /csp configuration. If you have configured /csp as your application, your configuration is overwritten when you install a new build of InterSystems IRIS. To maintain your application configuration, enter a path other than /csp.
    Any directory under /csp works fine, such as /csp/myapplication, but the path cannot contain any dots (periods). These lead to ambiguity for the Web Gateway. In this example: /csp/samples/menu.csp/csp/aaa/bbb/ccc.cls, the Web Gateway could either interpret this as a request for /csp/samples/menu.csp/csp/aaa/bbb/ccc.cls or as a REST request for/csp/samples/menu.csp (where PATH_INFO is /csp/aaa/bbb/ccc.cls). The Web Gateway, working in the web server environment, has no way of resolving these ambiguities.
    CSP is case-sensitive. Specify your path names consistently when you are configuring CSP.
  3. Enter the other configuration path and server parameters (described in the tables below) for this application.
  4. When you have finished, select Save Configuration. Changes you make to the application configuration take effect as new user sessions are created for that application path. Existing users are unaffected.
Application Path Configuration Parameters
The set of base parameters are as follows:
Parameter Function
Service Status Enable and disable access to an application via the application path (default is Enabled).
Web Server Physical Path Path to the corresponding directory on the web server. This setting is particularly important for Microsoft IIS systems where each path configured must be set up as a virtual directory under the web server configuration. Each virtual directory defined within IIS must have a physical path associated with it. The purpose of this additional configuration procedure for IIS is to allow the paths used by CSP to be defined with execute permissions. The default is for execute (and hence access to CSP) to be denied.
Extra CGI Environment Variables Comma-separated list of additional CGI Environment Variables to be returned to the InterSystems IRIS environment with each and every request. The commonly-used CGI Environment Variables are automatically sent with each request. Enter the wildcard character (*) to instruct the Web Gateway to send all Environment Variables supplied by the web server to the InterSystems IRIS server with each request.
Process with this class Process files in this path with the specified class. This allows you to build your own request handlers in CSP.
GZIP Compression Enable or disable GZIP compression for all CSP pages returned in this path (default is Disabled).
GZIP Minimum File Size Minimum response size, in bytes, for which GZIP compression is invoked. Default is 500 bytes.
GZIP Exclude File Types
This is a list of file types to be excluded from GZIP compression. Files to be excluded can be listed by MIME type (such as image/jpeg) or by common extension (such as jpeg).
By default, these common (natively compressed) image files are excluded:
GZIP Exclude File Types: jpeg gif ico png gz zip mp3 mp4 tiff
Separate additional types or extensions with a space.
Response Size Notification
This parameter provides configurable control over the method used by the Web Gateway to notify clients of the amount of data contained in each response.
Web clients typically require some form of response size notification if HTTP KeepAlive connectivity is used. Under these circumstances, the Web Gateway defaults to using chunked transfer encoding, provided HTTP v1.1 is in use. If an earlier HTTP protocol is in force it buffers the response data received from InterSystems IRIS and generate a content length header instead. Also, in cases where the entire response fits into one output buffer a content length header is generated instead of using chunked transfer.
There are scenarios in which it is desirable to instruct the Web Gateway to specifically use one method or the other. For example, in cases where HTTP v1.1 is used but some intermediary (such as a proxy) is unable to properly support chunked transfer. Also, while not sending any form of size notification (such as, where the close connection event is used as the response terminator) should be supported by all web clients, it is nevertheless recommended as 'good practice' that all responses should be accompanied by some form of size notification. Indeed, some clients require this.
The following options are provided:
  • Chunked Transfer Encoding and Content Length (the default)
  • Chunked Transfer Encoding
  • Content Length
This parameter is supplemented with a check box to instruct the Web Gateway to always generate a size notification for all requests regardless of whether or not KeepAlive is used.
KeepAlive Enable or disable HTTP KeepAlive connectivity for this path. Default is No Action in which case the KeepAlive status is determined by the HTTP response headers for each request.
Non-Parsed Headers Enable or disable Non-Parsed Headers protocol for this path. Default is Enabled in which case HTTP response headers are streamed directly back to the client. If this property is disabled, the response headers are submitted back to the hosting web server. This gives the web server the opportunity to parse the headers and invoke any output filters that may be indicated (For example the Apache Group’s mod_deflate facility).
Server Parameters
You can define a list of InterSystems IRIS servers to use for an application and the purpose for which they are to be used. The default server is the first one specified in the list.
Parameter Function
Servers
The first server listed is the default InterSystems IRIS server. It is used first. If it fails the other listed servers can be used, depending on the option checked. There are three options:
Servers #: List of servers. The configuration screen shows only three server slots at any one time, but you can define any number of alternative servers. Each server can be checked as Enabled or Disabled. Default is always Enabled See more information in the Load-Balancing and Failover section in this book.
Copying an Application Path Configuration
You can quickly configure a new application path by copying the configuration entry of an existing path and editing it.
This feature is also useful for fine-tuning a configuration. By creating a second (temporary) configuration for an application path, you can test parameter changes without worrying about losing the original configuration.
To copy an existing application path configuration:
  1. From the Web Gateway Management Main Menu, select Application Access.
  2. On the Application Access screen, select an existing application path.
  3. Select Submit.
  4. In the Application Path text box, enter a new and unique application path.
  5. Select Save Configuration. The new application configuration takes effect as new user sessions are created for the new application path. Existing users are unaffected.
Disabling Access via an Application Path
Use this facility to prevent users accessing a configured application through this Gateway installation.
To disable access via an application path:
  1. From the Web Gateway Management Main Menu, select Application Access.
  2. At the Application Access screen, select an application path.
  3. Select Submit. The configuration screen for the application path appears.
  4. For the Application Status parameter, select Disabled.
To re-enable access, repeat the procedure and select Enabled at Step 5.
Deleting an Application Path Configuration
To delete a configured application path:
  1. From the Web Gateway Management Main Menu, select Application Access.
  2. At the Application Access screen, select an application path.
  3. Select the Delete Application option.
  4. Select Submit.
About Web Gateway Page
This page displays information about the Web Gateway, including the version of the InterSystems IRIS distribution, the Web Gateway build number, the version of the hosting web server, the active interface, the name and location of the Web Gateway configuration file (CSP.ini), and the location of the event log.
Example:
Version: 2018.1.1.803.0 
Gateway Build: 1602.1573d
Web Server Name: localhost 
Web Server Type: Apache Web Server: Apache/2.4.10 (win32) Cache_Server_Pages-Apache_Module/2018.1.1.803.0-1602.1573d 
Active Interface: Apache Module 
Configuration: C:InterSystems/HealthShare_2/CSP/bin/CSP.ini
Event Log: C:/InterSystems/HealthShare_2/CSP/bin/CSP.log
Web Gateway Build Numbers
The Web Gateway build number is made up of two numeric components. The first number indicates the version of InterSystems IRIS. The second number is the internal Web Gateway build number.
Web Gateway and Security
This section describes how the Web Gateway relates to InterSystems security features. For more details on CSP authentication, see the chapter Authentication in the Security Administration Guide.
Web Gateway connections to InterSystems IRIS can be protected according to the following levels of security:
  1. Minimal connection security (not recommended).
Remember that security applied here is solely for the purpose of authenticating the Web Gateway host to the InterSystems IRIS server. It protects against the unauthorized creation of connections to the CSP engine (%cspServer). It does not, however, identify an individual user of a web application. A user of a web application can only be positively identified by whatever user login facility is provided by the application itself. For example, a Systems Manager logging on to the Management Portal can only be identified by the username and password supplied to the Management Portal login form.
The stateless nature of the Web should also be borne in mind. There is no fixed relationship between a Web Gateway connection to InterSystems IRIS and an individual user of a web application. Many users share the same connection.
Authenticating the Web Gateway to InterSystems IRIS at connection time is important. If an attacker can impersonate a Web Gateway, it can redirect traffic through a system under his control (by technical means and/or social engineering) and read and/or modify data at will. This is distinct from authenticating individual users to a web application. The Web Gateway's InterSystems IRIS username and password, Windows network credentials, or UNIX Kerberos key table should never be used by ordinary users.
Web Gateway Security Parameters
Maintain the following security parameters using the Web Gateway Web Management application. Under the Configuration section, select Server Access and choose to edit, copy, or add a server. The Connection Security section has the following settings:
Minimal Connection Security
In Minimal Connection Security, the Connection Security Level is set to Password and the Username and Password fields are left empty.
In this mode, there is a minimal level of security applied to the connection between the Web Gateway and InterSystems IRIS.
If this mode of operation, ensure that the Web Gateway service (%Service_WebGateway) together with the username under which it operates (for example, CSPSystem) is not expecting any form of authentication.
Simple Username- and Password-based Authentication
In Username- and Password-based Authentication, the Connection Security Level is set to Password and the Username and Password fields are applied.
This is the simplest form of authentication that can be applied between the Web Gateway and InterSystems IRIS.
It should be remembered that InterSystems IRIS passwords are a weak form of authentication since they must be sent over the network as plain text for authentication in InterSystems IRIS. Network sniffing is easy to do and can be used to reveal these passwords. Passwords used in this configuration option must be held in the Web Gateway configuration file (CSP.ini) in accordance with the following guidelines.
In all cases, the default username and password used for the Web Gateway is as follows. The installation process creates the CSPSystem user for this purpose. This user (CSPSystem or any other) should have no expiration date; that is, its Expiration Date property should have a value of 0.
Username: CSPSystem
Password: SYS
Windows
Passwords are encrypted in the Web Gateway configuration file (CSP.ini) using functionality provided by Microsoft’s Data Protection API (DPAPI). The Web Gateway Management Default Parameters page handles the encryption of passwords.
Note:
A form of password encryption is used for Windows because ordinary Windows user accounts are occasionally granted membership in the Administrators Group, although this is not recommended practice for production systems. Encrypting the password offers a higher level of protection for all Windows installations.
Occasionally, you need to introduce a password outside the context of the Web Gateway Management pages, for example, if the Web Gateway configuration is set up by custom configuration scripts. In this case, the password should be filed as plain text and the Web Gateway encrypts it when it is started for the first time.
Because the web server hosting the Web Gateway operates within a protected environment where there is no available user profile on which to base the encryption, it must use the machine store rather than the user store. Consequently, it is not possible to decrypt a Web Gateway password that was encrypted on another computer. This creates a situation for clustered environments in which the CSP.ini file is on a shared drive and shared among multiple participating computers. Only the computer that actually performs the password encryption can decrypt it. It is not possible to move a CSP.ini file containing encrypted passwords to another computer; the password must be reentered and reencrypted on the new machine.
Here are some possible approaches to this problem:
Kerberos-based Authentication and Data Protection
In Kerberos-based Authentication and Data Protection, three levels of authentication (and data protection) are provided through the Connection Security Level parameter.
  1. Kerberos. This option provides initial authentication only for the connection.
  2. Kerberos with Packet Integrity. This option provides initial authentication and guarantees data packet integrity.
  3. Kerberos with Encryption. This is the highest level of security and provides initial authentication, guaranteed data packet integrity, and, finally, encryption for all transmitted messages.
Kerberos Library
To use any of the Kerberos-based modes, the Web Gateway must be able to load the InterSystems Kerberos client library:
Install the appropriate library in a location specified in the PATH environment variable for the Operating System or at one of the following locations relative to the Web Gateway installation.
The Web Gateway attempts to load the library at the time it is first required. If successful, the following status message is written to the Event Log: Web Gateway Initialization The IRISCONNECT library is loaded - Version: 5.3.0.175.0. (This library is used for the optional Kerberos-based security between the Web Gateway and InterSystems IRIS)
If the Web Gateway is unable to locate or link to the IRISCONNECT library, a suitable statement of failure and error message is written to the Event Log.
For Kerberized communications between the Web Gateway and InterSystems IRIS, the Web Gateway is the Kerberos client.
The procedure for configuring the Web Gateway to use Kerberos is in the Windows section.
Overriding the Library Path If You Use SSL/TLS
By default, the Web Gateway expects dependent security libraries (shared objects) to be installed in its home directory (that is, the directory with the Web Gateway binaries).
If you use SSL/TLS connectivity between the Web Gateway and InterSystems IRIS, these libraries include the IRISCONNECT library and SSL/TLS libraries (libssl.so and libcrypto.so). When the Web Gateway and IRISCONNECT libraries, loaded in the web server's process space, load a copy of the SSL/TLS libraries, there is a conflict between different versions of the same libraries that were previously loaded by the hosting web server. To ensure that only one copy of the SSL/TLS libraries are loaded in the web server process space, the Web Gateway must instruct the IRISCONNECT library to source the SSL/TLS libraries from the same location as those used by the hosting web server.
The Web Gateway Management Default Parameters page provides the parameter SSL/TLS Library Path to allow you to use an alternative set of OpenSSL libraries. For example:
SSL/TLS Library Path = /usr/bin/  
Important:
You must use the SSL/TLS and SSH libraries that ship with the version of InterSystems IRIS you are currently running. You cannot swap these libraries.
Windows
Kerberos key tables are not implemented for Windows. Therefore, authentication uses network credentials that are either obtained when the hosting service starts in a named account or from the Trusted Computing Base (TCB) when the hosting service runs in the System Logon Session (that is, as LOCAL SYSTEM).
Windows domain accounts use a permanent key derived from a password to acquire a Kerberos Ticket Granting Ticket (TGT) and service ticket for the local machine. The local machine must also have a permanent Kerberos key, shared with the Key Distribution Centre (KDC) component of the domain controller. That key can be used to acquire a TGT and service ticket to authenticate to another Kerberos principal such as InterSystems IRIS.
For practical purposes the Web Gateway, operating within the context of a Windows-based web server is operating through either the Network Service logon session or the System logon session. The account used must have Log on as a batch job rights assigned.
The built-in Network Service logon session has access to the machine's credentials and is designed for services that need network credentials to authenticate to other machines. However, the Network Service logon session is not always present. The System logon session can also be used for the purpose of authenticating the Web Gateway to InterSystems IRIS.
For IIS installations, and ISAPI extensions in particular, using the Network Service login session is the preferred means through which both databases (local and remote) and remote computers should be accessed.
Web Gateway Configuration
Set the Service Principal Name to that of the target InterSystems IRIS server that the Web Gateway is connecting to. Leave the Username, Password, and Key Table fields empty.
The client principal name (or client username) is that of the Web Gateway host. This is the Kerberos name representing the Web Gateway hosts' network service session:
<computer_name>$
Assign this principal the necessary privileges in the InterSystems IRIS server to allow the Web Gateway’s service to operate.
UNIX
These Operating Systems support Kerberos Key Tables. The Web Gateway configuration is conceptually more straightforward for these systems.
Web Gateway Configuration
Set the Service Principal Name to that of the target InterSystems IRIS server that the Web Gateway is connecting to.
Enter the name of the key table file (including the full path) in the Key Table field.
Set the Username field to the name of the appropriate key in the key table file.
Leave the Password field empty.
The client principal name (or client username) is that of the Web Gateway host. This is the name used to identify the key in the Kerberos Key Table. Assign this principal the necessary privileges in the InterSystems IRIS server to allow the Web Gateway’s service to operate.
SSL/TLS-Based Authentication and Data Protection
You can use the SSL/TLS protocol to secure communications between the Web Gateway and InterSystems IRIS.
In this mode, the SSL/TLS transport, as configured for this host, secures connections to InterSystems IRIS. The SSL/TLS Configuration Name field should be set to the appropriate value for the target server. The Service Principal Name and Key Table fields are not relevant and should be left empty.
For more information on creating SSL/TLS client configurations for InterSystems IRIS systems, see the chapter Configuring the Web Gateway to Connect to InterSystems IRIS Using SSL/TLS in the Security Administration Guide. See also the subsection, in this book, “Overriding the Library Path If You Use SSL/TLS” in the section Kerberos Library on setting a path for the SSL/TLS libraries.
CGI Environment Variables
CGI Environment Variables are derived both from the client’s HTTP request headers and from the environment in which the web server is operating. The Web Gateway transmits the common environment variables to InterSystems IRIS with each and every request. If extra environment variables are required by the application, they must be explicitly requested in the Web Gateway configuration (via the Extra CGI Environment Variables setting in the Application Access section of the configuration). Navigate to System Administration > Configuration > Web Gateway Management and select Application Access.
The list of environment variables transmitted is shown in the table below together with a brief description of each. Further documentation can be obtained from standard web text books.
Environment Variable Value
AUTH_PASSWORD Value entered in the client’s authentication dialog. This variable is available only if Basic authentication is used.
AUTH_TYPE Contains the authentication method that the server uses to validate users when they attempt to access a protected script.
CONTENT_TYPE For requests which have attached information, such as HTTP POST and PUT, this is the content type of the data.
GATEWAY_INTERFACE Revision of the CGI specification to which this server complies. Format: CGI/revision
HTTP_ACCEPT Value of the Accept request header that contains a list of accepted formats (MIME types). For example: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.ms-excel. The values of the fields for the HTTP_ACCEPT variable are concatenated, and separated by a comma (,).
HTTP_ACCEPT_CHARSET Comma-delimited list of the character encodings that the client accepts.
HTTP_ACCEPT_LANGUAGE Contains a string describing the language to use for displaying content (such as en-us).
HTTP_AUTHORIZATION Contains the Base-64 encoded username, password, scheme and realm sent by the client.
HTTP_COOKIE Holds the contents of the client’s cookie(s).
HTTP_REFERER Holds a string that contains the URL of the page that referred the request to the current page using an HTML <A> tag. Note that the URL is the one that the user typed into the browser address bar, which may not include the name of a default document. If the page is redirected, HTTP_REFERER is empty.
HTTP_SOAPACTION SOAPAction HTTP request header field can be used to indicate the intent of the SOAP HTTP request. The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or that it is resolvable. An HTTP client MUST use this header field when issuing a SOAP HTTP Request.
HTTP_USER_AGENT Browser the client is using to send the request. General format: software/version library/version.
HTTPS Set to either On or Off (using word, not numerical value). Set to on if the script is being called through a secure server (that is, using SSL/TLS).
PATH_TRANSLATED Translated version of PATH_INFO, in which any virtual-to-physical mapping is applied to the path.
REMOTE_ADDR IP address of the remote host making the request.
REMOTE_HOST Hostname making the request. If the server does not have this information, it should set REMOTE_ADDR and leave this parameter unset.
REMOTE_IDENT If the HTTP server supports RFC 931 identification, then this variable is set to the remote username retrieved from the server.
REMOTE_USER Name of the user as it is derived from the authorization header sent by the client
REQUEST_METHOD Method with which the request was made. For HTTP, this is GET, HEAD, POST, and so on.
SERVER_NAME The server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs.
SERVER_PORT Port number to which the request was sent. For example: 80
SERVER_PORT_SECURE Set to either 0 or 1. If the request is being handled on the web server’s secure port, then it is set to 1. Otherwise, it is set to 0.
SERVER_PROTOCOL Name and revision of the information protocol that the request came in with. Format: protocol/revision
SERVER_SOFTWARE Name and version of the web server software responding to the request. Format: name/version.
HTTP Response Headers
CSP and CSP-based applications usually assume the responsibility for formulating a full HTTP response header. For performance reasons the Web Gateway traditionally streams the response headers, together with the following content, directly to the client via the web server. This mode of operation is known as the non-parsed header (NPH) approach. The Web Gateway does not grant the hosting web server any control over the response headers by passing them back through the dedicated API functions provided by the server. It is assumed that it is the client that needs to read and interpret the response header directives rather than the web server.
However, this assumption breaks down in cases where it necessary for the web server to interpret the response headers in order to invoke further web server-based functionality implied in the header directives generated by CSP. For example, by invoking output filters to further process the response (compression and encryption utilities etc.). Such output filters are usually found not to work for CSP content returned according to the nonparsed header mode of operation.
A facility exists to instruct the Web Gateway to explicitly pass the response headers through the hosting web server instead of streaming them directly to the client.
To use this facility, set the following CSP Header Directive:
CSP-nph: false
This directive must be set in the OnPreHTTP method. For example:
<script language=objectscript method=OnPreHTTP arguments=""
returntype=%Boolean>
Do %response.SetHeader("CSP-nph", "false")
Quit 1 </script>
When set to false, (the default setting for the Web Gateway is true), the CSP-nph directive ensures that the hosting web server is properly notified as to the nature of the response through the response headers returned from the CSP engine. As a result, any further processing can be performed as necessary. This is parsed header mode.
When the Web Gateway is operating in parsed header mode, the hosting web server interprets the response headers and perhaps add header directives of its own. At the very least it adds a Server header to the response. For example:
Server: Apache/2.0.48 (Win32)
OR:
Server: Microsoft-IIS/5.1
Note that this facility only applies to the use of Web Gateway implementations that work directly to web server APIs. In other words: everything other than CGI.
If the Web Gateway CGI modules are used and this facility is required then you must configure the web server to use the non-NPH versions of the CSP CGI modules. For example, use CSPcgi instead of nph-CSPcgi. The nph- prefix used in the name of a CGI module is the standard way of informing the web server that it is not required to read and interpret the response headers returned by the module: in other words operate in non parsed header mode.
The essential difference between the parsed and non-parsed versions of these modules lies in the way the HTTP response status line is formulated. This is the first line in the header block.
For parsed headers, format the HTTP status line as follows:
Status: <status_code>
Example:
Status: 200 OK
For nonparsed headers, format the HTTP status line as follows:
HTTP/1.1<status_code>
Example:
HTTP/1.1 200 OK
The CGI modules supplied with the Web Gateway automatically handle these differences internally. The CSP engine always return a standard HTTP header block (2).
See also the Non-parsed Headers parameter in the Adding an Application Path section
Compressing the Response to Requests for CSP Forms (GZIP/ZLIB)
Compressing the response generated by the CSP engine before dispatching it to the client is advantageous because it can dramatically reduce the network bandwidth required to transport the response to the client. From the client’s perspective the performance of the application is improved. This is particularly true for clients accessing the application through mobile devices over slower telecommunications networks. There is, of course, a cost in terms of the web server host’s CPU time that’s required to actually compress the data but this is a small price to pay for the advantages.
The advantage of serving compressed response data is particularly marked for CSP pages for which large volumes of response data are generated.
There are two methods for implementing GZIP in a web server environment.
Most web servers offer add-on facilities for compressing data. Windows/IIS offers a gzip filter (implemented as an ISAPI filter). The Apache Group offer a compression filter implemented as an add-on module (mod_deflate.c – which, rather confusingly, implements gzip compression not deflate). There is also a third-party module for Apache called mod_gzip.c. There are a number of third-party GZIP products available as add-ons for most web servers.
The advantages of implementing a compression solution directly in the Web Gateway are as follows:
It has been discovered that if Chunked Transfer Encoding is enabled at the Web Gateway level and if the Apache mod_deflate output filter is enabled for the same resources, then Windows browsers are occasionally unable to display the response content.
The Web Gateway makes use of the freely available GZIP (or zlib) library for implementing data compression. The compression algorithm used is described in RFCs (Request for Comments) 1950 to 1952.
Installing the GZIP/ZLIB Library
The GZIP/ZLIB library was developed by Jean-loup Gailly and Mark Adler (Copyright (C) 1995-2009). A pre-built version of this library (version 1.2.11) is provided with InterSystems IRIS distributions. You can also download the library from the following site:
http://www.zlib.net/
The library is freely available for all platforms on which the Web Gateway is supported. It is implemented as a DLL for Windows (zlib.dll or zlib1.dll), and as a shared object (or shared library) for UNIX systems (libz[1].so or libz[1].sl).
The library libz[1].so (or libz[1].sl) is usually pre-installed on all Linux systems in /usr/lib/ or /usr/local/lib. For Windows, the ZLIB library is usually installed in the Windows System32 directory.
The version distributed with InterSystems IRIS is usually found in the directory hosting the Web Gateway binaries.
The Web Gateway uses the following rules to locate a usable ZLIB library.
First, the library is expected to be named as zlib or zlib1 with the appropriate OS-specific extension. Libraries otherwise named (e.g. zlib123) should be renamed or, for UNIX systems, a symbolic link set up.
Take care to ensure that the library is of the same ‘bitness’ as the Web Gateway binaries. For example, if the Web Gateway binaries are 64-bit then the 64-bit version of the ZLIB library must be deployed.
The Web Gateway searches the following locations (in order) to find a ZLIB library.
Windows:
  1. [web_gateway_path]/zlib[1].dll Where web_gateway_path is the path to the Web Gateway installation
  2. zlib[1].dll This locates a library held in the standard PATH.
UNIX:
  1. [web_gateway_path]/zlib[1].so/sl Where web_gateway_path is the path to the Web Gateway installation
  2. zlib[1].so/sl This locates a library held in the standard PATH.
When relying on the Web Gateway being able to find ZLIB somewhere in the standard PATH, bear in mind that the PATH environment variable may not be available to Web Gateway installations operating in the context of highly locked-down web server environments.
The Web Gateway dynamically links to the ZLIB library when response compression is requested for the first time. Thereafter the ZLIB library remains loaded until the Web Gateway is closed down.
For UNIX systems, the library (libz.so or libz.sl) is usually installed in one of the following locations:
If the Web Gateway is able to load the ZLIB library on demand and identify all the required functions, the following initialization message is written to the Event Log:
Web Gateway Initialization
The ZLIB library is loaded - Version 1.2.11.
       (This library is used for the optional GZIP compression facility)
If the Web Gateway cannot find or link to the ZLIB library, it operates as before and pages are returned without being compressed. A statement of failure is written to the Event Log.
Using the GZIP/ZLIB Library
The Web Gateway implements two modes of operation (1 and 2) for compressing the response data using the ZLIB library:
  1. In this mode, the Web Gateway streams all data received from InterSystems IRIS into the compressor. When all the data has been processed, the compressor streams the compressed data back to the Web Gateway at which point it is forwarded on to the client.
    This mode offers the best possible compression at the expense of slightly higher latency. Of course, the latency is more pronounced for larger forms.
  2. In this mode, the Web Gateway streams all data received from InterSystems IRIS into the compressor. On each and every call, the compressor makes as much compressed data as it can available to the Web Gateway at which point it is forwarded on to the client.
    This mode offers the lowest possible latency at the expense of slightly reduced level of compression. Of course, the reduction in the degree of compression achieved is more pronounced for larger forms. Generally speaking, mode 2 is more appropriate for web applications where it is usually not possible to know, in advance, how much data a response contains.
If (and only if) the Web Gateway is able to successfully compress the data stream returned from InterSystems IRIS, it modifies the HTTP response headers to include the appropriate Content-Encoding directive. For example:
HTTP/1.1 200 OK
Content-Type: text/html; charset=ISO-8859-1
Set-Cookie: CSPSESSIONID=000000000002119qMwh3003228403243; path=/csp/samples/;
Cache-Control: no-cache 
Connection: Close 
Date: <date and time>
Expires: <date and ttime>
Pragma: no-cache 
Content-Encoding: gzip
Before attempting to compress response data, the Web Gateway always checks the value of the Accept-Encoding HTTP request header (the HTTP_ACCEPT_ENCODING CGI environment variable). The Web Gateway only compresses a response if the client has indicated that it is capable of dealing with compressed content.
For example:
Accept-Encoding: gzip, deflate
There are several methods for specifying that a CSP response should be compressed. These are discussed in the following sections.
Specifying Compression for Individual Pages
The %response object contains a property called GzipOutput. If this property is set to true (or the mode required) the Web Gateway attempts to compress the response.
<script language=objectscript method=OnPreHTTP arguments=""
         returntype=%Boolean>
         Set %response.GzipOutput = 2
         Quit 1
</script> 
Compression can also be specified on a per-page basis by adding the CSP-gzip directive to the HTTP response headers. This must, of course, be done in the OnPreHTTP method. For example:
<script language=objectscript method=OnPreHTTP arguments="" 
        returntype=%Boolean> 
        Do %response.SetHeader("CSP-gzip", "2") 
        Quit 1 
</script>
The CSP-gzip header directive should be set to the compression mode required (1 or 2).
Specifying Compression for All Pages within an Application Path
Compression can be specified on a per-application path basis. This, incidentally, is the most common method for indicating that compression should be used when using a web server output filter (such as mod_deflate).
Use the following configuration parameters in the Web Gateway Application Access section:
Item Function
GZIP Compression If Enabled, all CSP output for that path is compressed. Default is Disabled (no compression).
GZIP Minimum File Size Controls the minimum response size in bytes for which compression is activated. If left empty, then all responses for which GZIP is enabled are compressed.
GZIP Exclude File Types
List of file types to be excluded from GZIP compression. Files can be listed by MIME type (such as image/jpeg) or by common extension (such as jpeg).
By default, these common (natively compressed) image files are excluded:
GZIP Exclude File Types: jpeg gif ico png gz zip mp3 mp4 tiff.
Separate additional types or extensions with a space.
Monitoring
An Event Log level of V3 instructs the Web Gateway to record the degree of compression achieved for all CSP responses that were successfully compressed. The size of the compressed data and the original uncompressed data stream is recorded.
For example:
GZIP Compression for /csp/samples/inspector.csp 
GZIP Mode=1; Uncompressed Content Size=19042; Compressed Content Size=2499 (13 percent) 
Implementing HTTP Authentication for Web Applications
The Apache modules (mod_csp*.so/dll and CSPa*[Sys].so/dll) to allow HTTP authentication to be controlled by InterSystems IRIS.
HTTP authentication of web requests is normally carried out between the web server and client (browser). Because of this it is not usually possible to implement HTTP authentication in custom request handlers hosted by the web server – such as CGI programs and web server API-based request handlers. Of course, such extensions can issue a 401 Authorization Required response header and, in response to this, the browser displays the HTTP login dialogue. However, in the subsequent request, the web server intercepts the user's login details and attempts to authenticate the user using its own built-in functionality. The username and password are not, at least in the first instance, passed along to the request handling extension until the web server has authenticated the user on its own terms.
This scheme presents a problem for users of third-party development technologies (such as CSP) who wish to perform HTTP authentication locally (and programmatically) within their technology of choice.
The feature described here overcomes these technical difficulties and allows users to perform HTTP authentication in the InterSystems IRIS environment for Apache-hosted web applications. Users of Apache can choose between the three approaches described in the following sections.
Standard HTTP authentication in Apache (mod_auth)
This method is the standard mechanism provided by Apache (through the mod_auth module) and does not involve the Web Gateway. It is mentioned here for the sake of completeness.
As an example, the basic parameters required for protecting the CSP samples using Apache-based authentication are shown in the following configuration block (httpd.conf):
<Location "/csp/samples/">
    AuthType Basic
    AuthName "CSP samples"
    AuthUserFile conf/csp.pwd
    require valid-user
</Location>
Where:
AuthType is the type of authorization required (usually Basic).
AuthName is the realm.
AuthUserFile is the file (relative to the web server root) holding usernames and their associated passwords (in encrypted form). This file is created and maintained by the Apache htpasswd utility.
The require parameter lists the users who may access the protected resource (the CSP samples in this case). The valid-user argument indicates that the user must be defined in the username/password file (as declared in AuthUserFile).
Apache provides for users to be grouped together in user 'groups' – see the AuthGroupFile directive for further details:
https://httpd.apache.org/docs/2.4/mod/mod_authz_groupfile.html#authgroupfile
Authenticating in CSP at the Same Time as the Request is Processed.
This is the preferred (and best performing) method for implementing HTTP authentication in web applications.
The basic parameters required for protecting the CSP samples using CSP-based authentication are shown in the following Apache configuration block (httpd.conf):
<Location "/csp/samples/"> 
    AuthType Basic 
    AuthName "CSP samples" 
    require valid-user 
    Auth CSPEnable On
    AuthBasicAuthoritative Off
</Location> 
The parameters AuthType, AuthName and require are the standard Apache parameters used for triggering authentication.
The additional AuthCSPEnable parameter instructs the CSP module to bypass the authentication checks that would otherwise be performed by Apache (in mod_auth) and pass the user's name and password, along with the original web request, to InterSystems IRIS for authentication. The web application must check the user using the following CGI environment variables:
If the user can be successfully authenticated based on the values held in these parameters then the application should continue and process the request (i.e. return the requested CSP resource). If not, it should return a HTTP 401 Authorization Required response which, at the very least, should be something like:
HTTP/1.1 401 Authorization Required 
WWW-Authenticate: Basic realm="CSP samples" 
Content-Type: text/html 
Connection: close 
<html> 
<head><title>401 Authorization Required</title>
</head><body> <h1>Authorization Required</h1> 
<p> The server could not verify that you are authorized 
to access the application. Check your username and password. 
</p> 
<hr> 
</body> 
</html> 
On receiving this message the browser redisplays the login dialogue unless the user has used-up all his/her login attempts (usually 3) in which case the message following the header is displayed instead.
Uers can implement this method of authentication by modifying the login page. If a request comes in and the user does not have the necessary privileges to run the application then the login page is called, the processing for which can extract the authentication information from the request (such as AUTH_TYPE, REMOTE_USER and AUTH_PASSWORD). If these parameters are correct, the login script can then redirect control to the application page that was originally requested. It should not be necessary to repeat the authentication procedure for all public pages provided the InterSystems security control layer is deployed.
Authenticating in CSP before the Request is Processed.
This is an alternative method for implementing HTTP authentication in InterSystems IRIS. It is intended primarily for cases where performing authentication at request-processing time in the web application would be awkward or time consuming.
In this method, the user is authenticated by calling a dedicated authentication class. The Web Gateway performs this check before dispatching the original request to InterSystems IRIS. When the user's details have been successfully checked by the authentication class, the web application need not perform any further any further checking.
Of course, this method bears the overhead of processing two requests (to InterSystems IRIS) per web request: one for authentication and one for actually dealing with the request for the CSP resource.
The basic parameters required for implementing this method of authentication are shown in the following Apache configuration block (httpd.conf):
<Location "/csp/samples/"> 
    AuthType Basic 
    AuthName "CSP samples" 
    require valid-user 
    AuthCSPEnable On 
    AuthCSPClass /csp/samples/%CSP.HTTPAuthentication.cls 
    AuthBasicAuthoritative Off
</Location> 
The parameters AuthType, AuthName, require and AuthCSPEnable are the same as for method (2).
The additional AuthCSPClass parameter defines a class that performs user authentication. The class must extend %CSP.Page and, using the appropriate CGI environment variables, should check the user's login details and return either a 200 OK response header if the operation is successful or a 401 Authorization Required response header if not.
A simple authentication class in which user login details are checked against records held in the %Users file is shown below:
Class %CSP.HTTPAuthentication Extends %CSP.Page 
{ 
        ClassMethod OnPreHTTP() As %Boolean 
        { 
                Set %response.ContentType = "text/html" 
                Set %session.Preserve = 0 
                Quit 1 
        } 
        ClassMethod OnPage() As %Status 
        { 
                Set crlf=$Char(13,10) 
                Set type=%request.GetCgiEnv("AUTH_TYPE", "") 
                Set user=%request.GetCgiEnv("REMOTE_USER", "") 
                Set pwd=%request.GetCgiEnv("AUTH_PASSWORD", "") 
                Set httpauth=%request.GetCgiEnv("HTTP_AUTHORIZATION", "")
                If httpauth'="" {
      Set type=$Piece(httpauth," ",1)
      Set user=$system.Encryption.Base64Decode($Piece(httpauth," ",2))
      Set pwd=$Piece(user,":",2)
      Set user=$Piece(user,":",1)
                }
                Set auth=0 
                If $ZConvert(type,"L")'="basic" Set auth=1 
                If auth=0,user'="",$Get(^%Users(user))=pwd Set auth=1 
                If auth=1 { 
                        Write "HTTP/1.1 200 OK"_crlf 
                        Write "Content-Type: text/html"_crlf 
                        Write "Content-Length: 0"_crlf 
                        Write "Connection: close"_crlf_crlf 
                } 
                Else { 
                        Write "HTTP/1.1 401 Authorization Required"_crlf 
                        Write "WWW-Authenticate: Basic realm=""CSP samples"""_crlf 
                        Write "Content-Type: text/html"_crlf 
                        Write "Content-Length: 0"_crlf 
                        Write "Connection: close"_crlf_crlf 
                } 
                Quit $$$OK 
        } 
        ClassMethod OnHTTPHeader(ByRef OutputBody As %Boolean) As %Status 
        { 
                Quit $$$OK 
        }
}
For methods (1) and (3) a custom error page can be specified for login failure by using the Apache ErrorDocument directive. For example:
ErrorDocument /error/my_authentication_error.html 
Of course, for method (2) the text of the error message is controlled by the web application.
Mirrored Configurations, Failover, and Load Balancing
This section describes:
Load Balancing and Failover Between Multiple Web Servers
In most environments, multiple web servers are used to balance load and provide high availability at the web server layer. A load balancer is typically required to direct user connections to participating web servers. For best performance and resilience, it is recommended that a hardware-based solution is used. A Load Balancing system such as Cisco ACE 4710 or the F5 BigIP LTM appliance is placed in front of a set of web servers. In this configuration, if there are also multiple InterSystems IRIS server instances, such as in a distributed cache cluster, each web server (and by implication, Web Gateway instance) should be configured to connect to a specific InterSystems IRIS server instance.
Software based load-balancing and failover systems, though not as robust as hardware based solutions, are much less costly to deploy. Examples of software based solutions include HAProxy and the Apache Group’s mod_proxy_balancer. For more information, see the HAProxy site www.haproxy.org
Note:
Important: Sticky sessions should always be enabled for web applications. It is essential that each user session ‘sticks’ to the same back-end InterSystems IRIS server for the lifetime of the session – unless, of course, a failover event occurs.
Although the above approach is the primary recommendation, the Web Gateway contains a basic (software-based) system for implementing load balancing and failover between multiple InterSystems IRIS servers. In this configuration a Web Gateway installation is configured to connect to a number of InterSystems IRIS servers. This facility is described in the remainder of this section.
Web Gateway load balancing and failover is configured in the Application Access section of the Web Gateway Management pages. Navigate to System Administration > Configuration > Web Gateway Management and select Application Access.
A list of InterSystems IRIS servers may be defined for an application (path). Use the options listed under the Use Alternative Servers For parameter to select the purpose for which they are to be used. The following options are available:
Load Balancing and Failover Between Multiple InterSystems IRIS Server Instances
In configurations with multiple (equivalent) InterSystems IRIS server instances, such as in a distributed cache cluster, the Web Gateway provides a basic (software-based) facility for implementing load balancing and failover between those InterSystems IRIS instances for web applications. An external solution like those described previously is the primary recommendation, however.
The failover mechanism provided by the Web Gateway is not necessary to implement failover between multiple InterSystems IRIS database servers in a typical High Availability configuration, such as failover clustering or InterSystems IRIS mirroring. Those technologies provide Virtual IP based failover and the Web Gateway can be configured to connect to that IP address.
The remainder of this section describes the load balancing and failover capabilities provided by the Web Gateway.
Web Gateway load balancing and failover is configured in the Application Access section of the Web Gateway Management pages.
A list of InterSystems IRIS servers may be defined for an application (path). Use the options listed under the Use Alternative Servers For parameter to select the purpose for which they are to be used. There are two options:
The default course of action, if only one server is listed, is to use the first InterSystems IRIS server defined in the list. Following this default server is the list of alternative InterSystems IRIS servers, each designated as server# where # is the server number.
The configuration screen shows only three empty server slots at any one time, but it is possible to define any number of alternative servers. Each server can be marked as Enabled or Disabled. The default setting is Enabled.
Load-Balancing is implemented in a round robin fashion. Each new user session is connected to the next available 'alternative' server. Once a user session is established on a server, the Web Gateway maintains the session on that server unless it becomes unavailable, in which case the session is failed-over to the next available server in the list. State-aware sessions (preserve mode = 1) cannot be failed-over under any circumstances and, consequently, the session is closed if the hosting server becomes unavailable.
Mirrored Configurations
With mirrored InterSystems IRIS configurations, a database is duplicated (or mirrored) between participating mirror members. An InterSystems IRIS mirror set configuration represents the set of participating mirror members for an installation. For a complete description of InterSystems IRIS mirroring, see the chapter Mirroring in the High Availability Guide.
If Mirror Virtual IP (or an equivalent technology) is used to provide network redirection to the primary member, then configure the Web Gateway to connect to that address. No further action is required. The Virtual IP address is always mapped to the mirror primary.
For configurations where the Mirror Virtual IP cannot be used (or does not operate in certain disaster scenarios), it is possible to configure the Web Gateway to be mirror-aware. When the Web Gateway is mirror-aware, it assumes responsibility for determining which member is primary. To make a Web Gateway configuration mirror-aware, in the Web Gateway's Server Access section, select Configuration is Mirror Aware and provide the address of one of the mirror members.
Note:
There are situations where it is not appropriate for a Web Gateway configuration to be mirror-aware. For example, a Web Gateway configuration supporting the Management Portal should never be configured to be mirror-aware as the portal must always connect to a specific InterSystems IRIS server regardless of its mirror status.
If a mirror-aware Web Gateway configuration connects to an InterSystems IRIS server that is not a mirror member then the connection fails and the affected client receives a Server Availability error.
The Web Gateway obtains – from the Member that it first connects to – a list of failover members and disaster recovery (DR) members. The Web Gateway persists this list in its local configuration file (CSPRT.ini). If the Web Gateway subsequently cannot connect to the member defined in its configuration then it uses the list previously recorded locally to enable it to identify and connect to alternative members.
The Web Gateway cycles through the members list until it finds the primary. If it cannot find the primary, the Web Gateway defaults to the server defined in the Gateway configuration.
Mirror members appear in the Web Gateway System Status form when the first connection is made. Mirror members are shown named as the current configuration name (as defined under the Web Gateway’s Server Access section) with the mirror set name, mirror, and mirror member name shown as a tooltip.
The columns, Mirror Name and Mirror Status appear in the 'InterSystems IRIS Servers' table. The name of the mirror set and mirror member are shown in the Mirror Name column. The current member status is shown in the Mirror Status column: the Member Type (Failover or Async) is shown and the primary member is labelled as Primary.
Process Affinity and State-Aware Mode (Preserve Mode 1)
The architecture of the web is stateless. In order to get the best out of web architecture in terms of performance, maintainability and scalability web applications should embrace the stateless paradigm.
By default, web applications operate in a stateless environment with respect to the hosting InterSystems IRIS server. The Web Gateway maintains a pool of connections to InterSystems IRIS and distributes the workload amongst them and increases, within configured limits, (or decreases) the size of the connection pool. Each connection is associated with a single InterSystems IRIS process (as identified by the $Job variable).
For a normal web application operating in stateless mode, consider the choice of backend InterSystems IRIS process used to serve each request for a client session to be random. The Web Gateway chooses whichever connection/process happens to be free.
However, in the interests of efficiency, the Web Gateway does implement a form of InterSystems IRIS process affinity. In other words, it attempts, where possible, to route a request for a session to the same InterSystems IRIS process that was used to serve the previous request for that session.
In addition to a measure of process affinity based on session ID, the Web Gateway also attempts to implement process affinity based on namespace. The Web Gateway keeps track of the namespace to which each connection is pointing and delivers, where possible, requests to a connection that is already pointing at the namespace required to process the request. This helps in avoiding the overhead incurred in moving resources between different namespaces on receiving each web request.
In terms of precedence, session affinity always overrides all other considerations in the selection of a connection. If an incoming request cannot be assigned to the same connection previously used to serve the client session, namespace affinity is used instead to influence the final choice.
CSP includes a mode whereby the Web Gateway routes all requests for a session to a reserved (or private) InterSystems IRIS connection/process. This mode of operation provides a state-aware environment with respect to the relationship between web sessions and their corresponding InterSystems IRIS processes.
State-aware mode is implemented as CSP Preserve Mode 1
The original motivation for the provision of a state-aware mode of operation was to make it relatively easy to migrate legacy application code from a fixed client-server environment (e.g. terminal applications) to the web. Support for transactions that spanned several HTTP requests was also a consideration in its introduction. However, the limitations outlined in the following paragraphs should be borne in mind when creating state-aware applications.
State-aware applications do not scale as well as their stateless counterparts and it is therefore recommended that new applications (and modifications to existing ones) be designed to be stateless as far as is practically possible. It is recommended that state-aware mode, if used at all, should be applied sparingly in predominantly stateless applications.
Writing complete applications to operate in state-aware mode is not recommended. Apart from the scalability issues that arise as a consequence of the need to reserve an InterSystems IRIS process for each and every session, state-aware applications are unable to take full advantage of modern load balancing and failover solutions because of the very specific requirements for routing requests. Also, state-aware applications are not as fault-tolerant as their stateless counterparts. For example, the recycling of a web server worker process can happen transparently beneath a stateless application but results in all associated state-aware sessions closing. Of course, you can avoid the latter restriction by using the Web Gateway’s NSD component to separate the management of the Web Gateway process pool from the hosting web server.
Creating a successful state-aware application (or state-aware sections within a predominantly stateless application) requires a certain amount of discipline.
Since all requests for a session must be processed by the same InterSystems IRIS process, a queue must be maintained to serialize access to the private InterSystems IRIS process for cases where the client simultaneously dispatches several requests. The original HTTP v1.1 standard mandated that a client should simultaneously open no more than 2 connections to each server (RFC2616). However, this limit is configurable and, indeed, the latest generation of web browsers support, by default, up to 8 connections to each server. Needless to say, an increase in the maximum number of connections to each server can have a profound effect on state-aware web applications: an application can expect up to 8 requests to be fired concurrently and subsequently held in the queue responsible for controlling access to the single private InterSystems IRIS process.
Another potential pitfall in state-aware mode is the effect of the Server Response Timeout operating between the Web Gateway and InterSystems IRIS. When the Web Gateway does not receive a response within the prescribed time limit imposed by the response timeout it has no option but to close the connection with the consequential loss of the state-aware session.
Finally, the effect of client interrupts can cause problems with applications operating in state-aware mode. When a client interrupts a request at (and beyond) the point at which InterSystems IRIS is generating a response, the Web Gateway attempts to absorb the (now unwanted) response payload in order to retain the connection. If it is unable to do this in a timely fashion it, again, has no option but to interrupt whatever the InterSystems IRIS process is doing by closing the connection and the session is lost. Bear in mind that while the Web Gateway is attempting to absorb the payload for an interrupted request, further requests for the same session may be arriving and placed in the queue.
In summary, follow the following design goals when creating state-aware applications.
Launching State-Aware Mode
Mark a session as state-aware by setting the preserve mode as follows:
Set %session.Preserve = 1
It is recommended that a session be marked as state-aware in the form’s OnPreHTTP method:
<script language=objectscript method=OnPreHTTP arguments="" returntype=%Boolean>
Set %session.Preserve = 1
Quit 1
</script>
Issuing the instruction here means that the CSP engine can mark the session cookie (or token) as state-aware before formulating and dispatching the HTTP response headers to the Web Gateway.
Sessions can be marked as state-aware after the OnPreHTTP method has fired but in this case the session cookie/token has already been formulated. The CSP engine passes the preserve=1 instruction to the Web Gateway in the response footers (dispatched after the response payload) and the Web Gateway marks the connection as private and caches the instruction against the session ID so that it can recognize the unmodified session token as state-aware when subsequent requests arrive.
If the session is marked as state-aware in the OnPreHTTP method, the Web Gateway has no need to cache the transition against the session since the information is carried in the session cookie/token which effectively resides on the client.
Maintaining State-Aware Mode and Responding to Errors
Once a session is marked as state-aware and the Web Gateway has acknowledged the state-transition and marked the connection as private, the session transparently operates in state-aware mode until one of the following events occurs:
If the private connection hosting a state-aware application is prematurely closed (perhaps as a result of an error condition), the Web Gateway routes the request to a free stateless connection in the pool and InterSystems IRIS error number 5974 is returned:
CSP error occurred
Error: The persistent session is no longer available because the server process does not exist
ErrorNo: 5974
CSP Page: /csp/samples/loop.csp
Namespace: %SYS
Class: <Unknown>
At this point the request is operating in stateless mode and it is the application’s responsibility to respond to this error: for example, by directing the user back to the login form for the application.
When operating in state-aware mode, the value of %session.NewSession should be checked in every page. Alternatively, the application should check the validity of user specific authentication data stored in %session.Data when the user was first authorized to access the application. These checks are important for security reasons and to ensure that the user session is still securely locked-in to a state-aware mode of operation. An error condition is not automatically raised under these circumstances because it is possible that the session had already (and legitimately) transitioned out of state-aware mode. For example, consider the situation where an incoming session token is still marked as state-aware but the application had already transitioned to stateless mode – this situation arising as a result of a session token being embedded in a form (as CSPCHD) that was served before the transition was made.
Finally bear in mind that when a session is terminated (for example, after it has timed out) the CSP engine deletes all operational data associated with the session, after which point any further incoming requests for that session are treated as though they are for a new session.
The embedded security mechanisms provided by InterSystems IRIS for web applications offer protection against the eventualities outlined above. Users are automatically directed to the login form in all cases where a loss of continuity within a state-aware application occurs (with respect to InterSystems IRIS process).
Terminating State-Aware Mode
An application can revert back to a stateless mode of operation by setting the preserve mode as follows:
Set %session.Preserve = 0
It is recommended that this code be executed in the form’s OnPreHTTP method:
<script language=objectscript method=OnPreHTTP arguments="" returntype=%Boolean>
    Set %session.Preserve = 0
    Quit 1
</script>
Issuing the instruction here means that the CSP engine can mark the session cookie (or token) as stateless before formulating and dispatching the HTTP response headers to the Web Gateway.
A session can be immediately terminated as follows:
Set %session.EndSession = 1
When you set this property, the session terminates immediately after serving the current request.
You can set a session to timeout as follows:
Set %session.AppTimeout = 900
The session times out and terminates after the prescribed number of seconds of inactivity. The default is 900 seconds (15 minutes).
Web Gateway Registry in InterSystems IRIS
The InterSystems IRIS Web Gateway Registry registers each connected Web Gateway installation with InterSystems IRIS and provides the infrastructure to allow InterSystems IRIS code to interact with those Web Gateway installations. Such programmatically controlled interactions may include reading and modifying the Web Gateway’s runtime configuration and collecting system status and log information. The relevant classes are as follows:
%CSP.Mgr.GatewayRegistry (The Gateway Registry)
%CSP.Mgr.GatewayMgr  (A Connected Gateway)
The following code lists all connected (i.e. active) Web Gateway installations and writes the web server IP address, port and Web Gateway build number to the console window.
Set reqistry = $system.CSP.GetGatewayRegistry()
Set gateways = reqistry.GetGatewayMgrs()
For no=1:1:gateways.Count() {
     Set gateway = gateways.GetAt(no)
     Write !,no, " : "
     Write gateway.IPAddress,":",gateway.Port," ",gateway.Version
}
When InterSystems IRIS is first started this list is empty. As Administrator and User activity increases expect at least two entries to appear: one for the Private Web Server serving the Management Portal and at least one for external web servers supporting applications.
You can find further documentation associated with the classes listed above. Some code examples follow to illustrate common tasks.
List Default Parameters
Kill defaults
Do gateway.GetDefaultParams(.defaults)
ZWrite defaults
Update Default Parameter(s)
Kill newpars
Set newpars("Server_Response_Timeout")=30
Do gateway.SetDefaultParams(.newpars)
List Servers
Set status = gateway.GetServers(.servers)
For no=1:1:$ListLength(servers) {
     Set server = $List(servers,no)
     Write !,no, " : ",server
}
List Server Parameters
Kill serverpars
Do gateway.GetServerParams("LOCAL",.serverpars)
ZWrite serverpars
Update Server Parameter(s)
Kill newpars
Set newpars("Maximum_Server_Connections")=250
Do gateway.SetServerParams("LOCAL",.newpars)
List Application Paths
Set status = gateway.GetApplicationPaths(.paths)
For no=1:1:$ListLength(paths) {
     Set path = $List(paths,no)
     Write !,no, " : ",path
}
List Application Parameters
Kill pathpars
Do gateway.GetApplicationParams("/csp",.pathpars)
ZWrite pathpars
Update Application Parameter(s)
Kill newpars
Set newpars("GZIP_Compression")="Enabled"
Clear Gateway cache
Do gateway.ClearCache("*")
Forcing the Web Gateway to Reload Its Configuration
There are occasions when the Web Gateway’s configuration is modified by external agents (i.e. agents other than the Web Gateway’s own Systems Management Suite).
There are two methods for interactively instructing the Web Gateway to reload its configuration, and in a way that doesn’t require a complete restart.
Using the InterSystems IRIS Web Gateway Registry
The following Registry Method is provided:
Set status = %CSP.Mgr.GatewayMgr.ActivateCSPIni()
When successfully called, the Web Gateway reads its configuration file (CSP.ini) and activates all changes made.
Using Scripts External to InterSystems IRIS
Scripts should add the following line (case-sensitive) to the SYSTEM section of the modified Web Gateway configuration file (CSP.ini):
[SYSTEM]
RELOAD=1
The Web Gateway caretaker daemon checks the RELOAD flag approximately every minute and, if correctly set, reloads and reactivates its configuration and removes the flag from the file. The following message is written to the Event Log after a successful reload operation:
Gateway Management 
Gateway Configuration Reloaded and Reactivated
Using WebSockets (RFC 6455)
The web has been built around the request/response paradigm: the client sends a request to the server and the server reacts by sending a response to the client. This paradigm, and HTTP itself, does not allow for an inverted form of this communication protocol whereby a server initiates a request/response cycle with the client. A number of technologies have been developed to create an illusion that a server can initiate a dialogue with a client. These technologies are generally known as push-based or comet-based technologies and all suffer from problems that make them unsuitable for general deployment over web infrastructure. The three main techniques in current use are described below.
Short Polling
With this technique a client regularly sends HTTP requests to detect changes in server state, and the server is programmed to responds immediately. An empty response signifies no change.
Problems:
Long Polling
With this technique a client sends a HTTP request but the server only responds when the client needs to be notified of a change. The client typically sends another “Long Poll” request as soon as the server sends a response message.
Problems:
HTTP Streaming
This technique takes advantage of the HTTP protocol’s ability to maintain persistent (or ‘KeepAlive’) connections between the client and server. The client sends an HTTP request which is permanently kept open with the server only responding when the client needs to be notified of a change. The server does not terminate the connection after dispatching a response message and the client waits for the next message from the server (or sends a message of its own to the server).
Problems:
WebSockets Protocol
The WebSockets protocol (RFC 6455) addresses the fundamental requirement of allowing servers to proactively push messages to clients by providing a full-duplex message-oriented communications channel between a client and its server. The protocol is designed to operate, and hence be secured, over the standard TCP channel already established between the client and server and used to support the HTTP protocol between a web browser and web server.
The WebSockets protocol and its API are standardized by the W3C and the client part is included with HTML 5.
Intermediaries, such as proxies and firewalls, are expected to be aware of, and to support, the WebSockets protocol.
Browser Support
There have been several iterations in creating the final standard for the WebSockets protocol, each with varying degrees of browser support. The history is summarized below.
The HyBi-17/RFC 6455 section is the most significant for the purpose of developing portable web applications.
Server Support
The latest versions of all major web servers offer WebSockets support as shown below:
Protocol in Detail
Creating a WebSocket involves an ordered exchange of messages between the client and the server. First, the WebSocket handshake must take place. The handshake is based on, and resembles, an HTTP message exchange so that it can pass without problem through existing HTTP infrastructure.
The web server recognizes the conventional HTTP header structure in the handshake request message and sends a similarly constructed response message to the client indicating that it supports the WebSocket protocol - assuming it is able to. If both parties agree then the channel is switched from HTTP (http://) to the WebSockets protocol (ws://).
Typical WebSocket Handshake Message from Client
GET /csp/user/MyApp.MyWebSocketServer.cls HTTP/1.1
Host: localhost
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: chat
Sec-WebSocket-Version: 13
Origin: http://localhost
Typical WebSocket Handshake Message from Server
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat
Note how the client handshake message requests that the protocol be upgraded from HTTP to WebSocket. Note also the exchange of unique keys between the client (Sec-WebSocket-Key) and server (Sec-WebSocket-Accept).
WebSockets Client Code (JavaScript)
In the browser environment the client side of the WebSockets protocol is implemented in JavaScript code. Standard text books describe the usage model in detail. This document briefly describes the basics.
Create a WebSocket
The first parameter represents the URL identifying the server end of the WebSocket application. The second parameter is optional, and if present, specifies the sub-protocol that the server must support for the WebSocket connection to be successful.
var ws = new WebSocket(url, [protocol]);
Example:
ws = new WebSocket(((window.location.protocol == "https:")
     ? "wss:" : "ws:") \
     + "//" + window.location.host
     + /csp/user/MyApp.MyWebSocketServer.cls);
Note how the protocol is defined as either ws or wss depending on whether or not the underlying transport is secured using SSL/TLS.
The read-only attribute ws.readyState defines the state of the connection. It can take one of the following values:
The read-only attribute ws.bufferedAmount defines the number of bytes of UTF-8 text that have been queued using the send() method.
WebSocket Events
The following events are available.
Data received in event.data.
WebSocket Methods
The following methods are available.
WebSockets Server Code
The base InterSystems IRIS class for implementing WebSocket Servers is %CSP.WebSocket
When the client requests a WebSocket connection, the initial HTTP request (the initial handshake message) instructs the CSP engine to initialize the application's WebSocket server. The WebSocket server is the class named in the requesting URL. For example, if your WebSocket server is called MyApp.MyWebSocketServer and is designed to operate in the USER namespace then the URL used to request the WebSocket connection is:
/csp/user/MyApp.MyWebSocketServer.cls
WebSocket Events
The implementation of the WebSocket server is derived from the base %CSP.WebSocket class. There are three key methods to implement as responses to the following events. Note that the web session is unlocked before calling any of these methods.
OnPreServer (optional)
Use this method to invoke code that should be executed before the WebSocket server is established. Changes to the SharedConnection property must be made here.
Server (Mandatory)
The WebSocket server. This is the server-side implementation of the WebSocket application. Messages can be exchanged with the client using the Read() and Write() methods. Use the EndServer() method to gracefully close the WebSocket from the server end.
OnPostServer (optional)
Use this method to invoke code that should be executed after the WebSocket server has closed.
WebSocket Methods
The following methods are provided
Method Read(ByRef len As %Integer = 32656,
     ByRef sc As %Status,
     timeout As %Integer = 86400) As %String
This method reads up to len characters from the client. If the call is successful the status (sc) is returned as $$$OK; otherwise one of the following error codes is returned:
Method Write(data As %String) As %Status
This method writes data to the client.
Method EndServer() As %Status
This method gracefully ends the WebSocket server by closing the connection with the client.
Method OpenServer(WebSocketID As %String = "") As %Status
This method opens an existing WebSocket Server. Only a WebSocket operating asynchronously (SharedConnection=1) can be accessed using this method.
WebSocket Properties
The following properties are provided:
SharedConnection (default: 0)
This property determines whether the communication between the client and WebSocket server should be over a dedicated Web Gateway connection or asynchronous over a pool of shared Web Gateway connections. This property must be set in the OnPreServer() method and may be set as follows:
WebSocketID
This property represents the unique identity of the WebSocket.
SessionId
This property represents the hosting CSP Session ID against which the WebSocket was created.
BinaryData
This property instructs the Web Gateway to bypass functionality that would otherwise interpret the transmitted data stream as UTF-8 encoded text and set the appropriate binary data fields in the WebSocket frame header.
This should be set to 1 before writing a stream of binary data to the client. For example:
Set ..BinaryData = 1
WebSockets Server Example
The following simple WebSocket server class accepts an incoming connection from a client and simply echos back data received.
The timeout is set to 10 seconds and each time the Read() method times-out a message is written the client. This illustrates one of the key concepts underpinning WebSockets: initiating a message exchange with the client from the server.
Finally, the WebSocket closes gracefully if the client (i.e. user) sends the string exit.
Method OnPreServer() As %Status
{
   Quit $$$OK
}

Method Server() As %Status
{
   Set timeout=10
   For  {
      Set len=32656
      Set data=..Read(.len, .status, timeout)
      If $$$ISERR(status) {
                          If $$$GETERRORCODE(status) = $$$CSPWebSocketClosed {
                                        Quit
                          }
         If $$$GETERRORCODE(status) = $$$CSPWebSocketTimeout {
               Set status=..Write(“Server timed-out at “_$Horolog)
         }
      }
      else {
         If data="exit" Quit
         Set status=..Write(data)
      }
   }
   Set status=..EndServer()
   Quit $$$OK
}

Method OnPostServer() As %Status
{
   Quit $$$OK
}
WebSockets Server Asynchronous Operation
The example given in the previous section illustrates a WebSocket server operating synchronously with the client over a dedicated InterSystems IRIS connection. When such a connection is established it is labeled as WebSocket in the status column of the Web Gateways Systems Status form. With this mode, the WebSocket is operating within the security context of the hosting web session and all properties associated with that session can be easily accessed.
With the asynchronous mode of operation (SharedConnection=1), the hosting connection is released as soon as the WebSocket Object is created and subsequent dialogue with the client is over the pool of shared connections: messages from the client arrive via the conventional pool of Web Gateway connections to InterSystems IRIS and messages to the client are dispatched over the pool of Server connections that have been established between the Web Gateway and InterSystems IRIS.
In asynchronous mode, the WebSocket Server becomes detached from the main web session: the SessionId property holds the value of the hosting Session ID but an instance of the session object is not automatically created.
The example given previously can be run asynchronously simply by setting the SharedConnection property in the OnPreServer() method. However, it is not necessary to have an InterSystems IRIS process permanently associated with the WebSocket. The Server() method can exit (and the hosting process halt) without closing the WebSocket. Provided the WebSocketID has been retained, the WebSocket can be subsequently opened in a different InterSystems IRIS process and communication with the client resumed.
Example:
Class MyApp.MyWebSocketServer Extends %CSP.WebSocket
{
    Method OnPreServer() As %Status
    {
        MYAPP.SAVE(..WebSocketID)
        Set ..SharedConnection = 1
        Quit $$$OK
    }

    Method Server() As %Status
    {
        Quit $$$OK
    }

    Method OnPostServer() As %Status
    {
        Quit $$$OK
    }
}
Note that the WebSocketID is retained for subsequent use in the OnPreServer() method. Note also, the setting of the SharedConnection property in the OnPreServer() method and that the Server() method simply exits.
Subsequently retrieving the WebSocketID:
Set WebSocketID = MYAPP.RETRIEVE()
Re-establishing a link with the client:
Set ws=##class(%CSP.WebSocketTest).%New()
Set %status = ws.OpenServer(WebSocketID)
Reading from and writing to the client:
Set %status=ws.Write(message)
Set data=ws.Read(.len, .%status, timeout)
Finally, closing the WebSocket from the server side:
Set %status=ws.EndServer()
Option for Automated Deployment Sites (Such As Cloud)
You can relocate Web Gateway-maintained version/timestamp parameters from the Web Gateway configuration file (CSP.ini) to the runtime parameters file (CSPRT.ini). CSPRT.ini is owned and maintained by the Web Gateway and does not contain configuration settings.
This option satisfies the needs of automated software deployment environments, such as those used to create and maintain cloud-based installations. For these environments, configuration files are maintained outside of their operating environment. When changes are made, redeployment or update operations are triggered. Therefore it is essential that configuration files are not changed (by the Web Gateway) at runtime.
To invoke this option, set the READONLY parameter in the CSP.ini file before initializing the Web Gateway (by starting or restarting the hosting web server).
[SYSTEM]
READONLY=1
The affected parameters are:
Configuration_Initialized
Configuration_Initialized_Build
Configuration_Modified
Configuration_Modified_Build
Examples:
Configuration_Initialized        = Thu May 24 18:02:57 2018
Configuration_Initialized_Build  = 1601.1551
Configuration_Modified           = Thu Nov 15 16:47:40 2018
Configuration_Modified_Build     = 1603.1599
The READONLY parameter takes an additional value:
[SYSTEM]
READONLY=2
This switch makes the configuration file strictly read only. When set, the Web Gateway does not attempt to write to CSP.ini and all configuration parameters are listed in a non-editable form in the Web Gateway Management pages.
The READONLY parameter must be set in the CSP.ini file before initializing the Web Gateway, that is, before starting or restarting the hosting web server. This setting is acknowledged in the Web Gateway's initialization message in the Event Log. For example:
The Web Gateway module 'C:\inetpub\CSPGateway\CSPms.dll' is loaded 
(IPv6 Enabled; MAX_CONNECTIONS=1024; MAX_SERVERS=13; MAX_APPLICATIONS=10; MAX_RESPONSE_BUFFER_SIZE=128000; 
Connection_Allocation=First Free; Nagle_Algorithm=Disabled; SHM=OS; IPC=WNP; READONLY=2) 
This facility helps avoid problems in locked-down Docker or other container-based installations. In such installations it is usual to pre-configure the Web Gateway and mark the supplied CSP.ini file as read-only at the UNIX level.


Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-07-17 06:06:47