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


Web Gateway Configuration Guide
Web Gateway Operation and Configuration
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This topic describes how to configure the Web Gateway and exploit its functionality in web applications. It contains the following sections:
Web Gateway Management Page
The Web Gateway Management page allows you configure and manage the Web Gateway, including monitoring its operational status. The following table shows the options available on the page menu.
Menu Item Action
System Status Displays the status of active server connections. Also allows you to clear the Web Gateway cache.
Close Connections Closes all connections on all or specified InterSystems IRIS™ servers.
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.
About Web Gateway Shows the Web Gateway version, the hosting web server environment, including the path to the Web Gateway configuration.
The CSP Web Gateway Documentation (online help on configuring the Web Gateway) is available in this section as well as through the Help button on the Web Gateway Management Page in the Management Portal [System] > [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, this takes you to the private web server. To see the Web Gateway Management page for your production web server, substitute localhost for localhost:52773 in the URL, as http://localhost:<port_no>/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 page, you are asked for a username and password. Look for the username in the C:\iris-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 Page
Localization of the Web Gateway Management pages is based on the contents of the CSPres.xml installed (if any). 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.
Alternative languages can be supported by installing the appropriate text resource file (as a file named CSPres.xml) in the Gateway’s home directory. When the Gateway is started (or restarted) the Gateway 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 Page
By default, only clients local to the Gateway’s hosting computer are allowed access to the Web Gateway Management page. 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 C:\iris-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 page. 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 page. 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 page. 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 page 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 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 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.
IP Address IP address of the InterSystems IRIS system.
TCP Port TCP port on the InterSystems IRIS server through which the connection communicates. The default port is 51773.
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.
Activity Number of transactions (hits) the connection has processed.
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 Name Name of the InterSystems IRIS system connected to.
IP Address IP address of the InterSystems IRIS system.
TCP Port TCP port on the InterSystems IRIS server through which the connection communicates. The default port is 51773.
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.
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.
Mirror Status Mirror configuration with Mirror Status of the server, member type (Failover or Async), labelled as Primary as appropriate.
Fourth Table: NSD Internal Status (Where Applicable)
The fourth status table displays internal NSD information. This table only appears for NSD installations or for installations that use the Gateway's response caching facility.
Item Function
Queued Threads Where the concurrent load exceeds the number of threads that are available within the Gateway process, this indicates number of requests that are held in a queue waiting for a thread to become free. Under normal operation the value reported should be zero. If a number of queued requests are consistently reported here, consider allocating more processes to the NSD.
Cached Forms
Number of CSP forms cached by the Gateway.
Cached Data (Bytes) Amount of cached form data held in the Gateway (in Bytes).
Cached Form Activity Number of hits for forms held in the Gateway cache.
Clear
Clear Cache (if available) allows you to manually clear the Gateway form cache.
Clear (if available) allows you to manually clear the individual forms from the Gateway cache.
Total Cache Blocks Total number of cache memory blocks available.
Cache Blocks In Use Total number of cache memory blocks in use.
Refresh Update status screen.
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. From the Web Gateway Management Main Menu, select System Status.
  2. 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 rightmost column) in 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.
Note:
If you are attempting to clear the cache during activities beyond the scope of the Web Gateway Management itself, then, to get to the Web Gateway Management Main Menu, you must first log into the Management Portal and then go to the Web Gateway Management page (System Administration > Configuration > Web Gateway Management).
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 from this option. To close sessions manually:
  1. From the Web Gateway Management Main Menu, select Close Connections.
  2. Select the server from which you wish to disconnect. You can select * (asterisk) to close all connections to all servers.
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 page 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 View Server-side Log to see the CSP error log on the InterSystems IRIS Server.
  4. 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 CSP is installed and working properly. The form just shows the basic parameters returned by the target InterSystems IRIS server (version and process ID).
Server Event Log You should receive this page if you selected View Server-side Event Log.
System 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.
Server is currently unavailable The Web Gateway may have timed out while trying to establish a new connection.
No response from the Web Server Check to see if your web server is running. If it is running, shut it down and restart it.
Not Enough Sessions All channels to the server are busy: Please try later You have reached your connection limit and must close some of the connections you have running.
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 Main Menu to read the contents of the Event Log.
By default, each day’s log entry, CSP.log, is renamed CSP.log.old. To save all logs in files named with date and time, check Retain All Log Files on the Default Parameters page. in the 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 Gateway terminates the display and prompt 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 Gateway by time and a unique request ID (assigned by the 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 Gateway are reconstituted because the hosting web server always assumes responsibility for parsing the request headers. The 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 three components:
Web Gateway
This section contains a parameter that is 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 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 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 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 250K. This value can be raised or lowered as required.
Changes to the Maximum Cache Size parameter will 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 will 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 page.
If you forget the password, manually edit the 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 page 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 page using this option. The default is Enabled. When access is Disabled you cannot re-enable access using the Web Gateway Management page. 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 page.
Password
Password required to access the Web Gateway Management page.
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 page.
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 the Gateway Management Suite. 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 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 http.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 Gateway does not apply the No Activity Timeout to the minimal connection pool (as defined by the Minimum Server Connectionsparameter). If this option is checked the 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 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
By default, 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, instead of this daily overwriting, check Retain All Log Files. If you enable this option, then the day’s log is named with the date and time as: CSP_YYYYMMDD_hhmm.log
Event Log Rotation Size
This defines the size after which log rotation should take place. The default value is blank which effectively means that the Gateway will maintain one log file which will grow until such time as 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)
Rotated log files that are not to be retained are named as: CSP.log.old
In order for this facility to work, the Gateway must have create/write access to the directory hosting the Gateway binaries (i.e. the location where the main log file is kept). If, for whatever reason, the Gateway is unable to perform a successful rotation it will continue writing to the current log file: CSP.log.
This field is supplemented with a check box (Retain All Log Files) which, if checked, instructs the Gateway to keep all log files according to the naming scheme outlined above. Otherwise a single rotated file named CSP.log.old is kept.
SSL/TLS Library Path
Specifies the path to the OpenSSL libraries: libssl.so and libcrypto.so. The default position is for the Gateway to source these libraries locally in its home directory. See “Overriding the Library Path If You Use SSL” in the section Kerberos Library in this book for more information.
Preserve Mode Exclude File Types
Allows static files to be served asynchronously in state-aware applications. In stateless applications, statics (files other than csp, cls, csr, and zen) are processed asynchronously with respect to the main session. In other words, requests for these files bypass the session lock and can be processed concurrently outside the main processing stream for the application.
This parameter allows this scheme to be extended to state-aware applications. State-aware applications are not only subject to the conventional session lock but are also subject to the connection lock in the Web Gateway. The connection lock is responsible for ensuring that all requests for the user/session are routed to the same InterSystems IRIS process. For applications that rely on static components being served from InterSystems IRIS, this leads to excessive request queuing which, in turn, can lead to browser instability (such as hangs).
Use this parameter to define a list of (space separated) file types (by extension) to process asynchronously and therefore exempt from connection/session locking in the 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 either 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 This is reserved for future use.
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 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 Gateway home directory, where session_id is the 10-Byte session ID.
  • v9m: Log all multi-part posts in the 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 (CCONNECT).
Instruct the Gateway to record all CCONNECT functions called, the input parameters, and results. 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 C (upper-case C) to record, in addition to the CCONNECT function calls, the contents of the input and output buffers.
t Transmission: Record the contents of the raw data buffers as they are dispatched to InterSystems IRIS. Raising the log level further to T (uppercase T) results in the raw response buffers being captured too. 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 Gateway to the time at which the last Byte of response data leaves the Gateway environment.
  • Obtain [NEW] connection to InterSystems IRIS: Time taken between the request reaching the 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 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.
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 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 Gateway being ready to read the response footer data from InterSystems IRIS. The footer data is part of the internal communication protocol between the 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 will cause the 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 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 Gateway changes the connection to the new primary. If no primary can be found among the failover members, the 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 their 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 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 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
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 Parameters
The following parameters are relevant only to installations using SSL to secure connections between the Gateway and InterSystems IRIS.
SSL Parameter Function
SSL 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:!SSLv"
SSL Key Type
The type of SSL 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 Certificate File
The full path to the SSL/TLS certificate file for the Gateway.
Example: C:\InterSystems\certificates\clicert.pem
SSL Certificate Key File
The full path to the private key associated with the Gateway’s SSL/TLS certificate.
Example: C:\InterSystems\certificates\clikey.pem
SSL CA Certificate File
The full path to the certificate for Certificate Authority (CA) for the Gateway’s certificate.
Example: C:\InterSystems\certificates\cacert.pem
SSL Private Key Password The password to the SSL 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. From the Web Gateway Management Main Menu, select Server Access.
  2. At the Server Access screen, select an existing server name.
  3. Select the Copy Server option.
  4. Select Submit. The second configuration screen appears.
  5. In the Server Name text box, enter a unique, descriptive name for the new server.
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, selectServer 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. On the Web Gateway Management page, select Application Access.
  2. Select Add Application. Note that many parameters have default settings.
  3. 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 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.
  4. Enter the other configuration path and server parameters (described in the tables below) for this application.
  5. 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 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 Gateway will default to using chunked transfer encoding, provided HTTP v1.1 is in use. If an earlier HTTP protocol is in force it will buffer 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 will be generated instead of using chunked transfer.
There are scenarios in which it is desirable to instruct the 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 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:
  • Use Load-Balancing and Failover . If the first server fails, use a server that is configured as either failover or load-balancing.
  • Use Failover . If the first server fails (becomes unavailable), use an alternative.
  • Use First Server Only Use only the first server in the list. Do not use another server under any circumstances.
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 contains 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 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 page, 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:
UNIX®
Passwords are stored in CSP.ini as plain text. Access to the configuration file should be protected by setting the file owner to be the account from which the Web Gateway (or hosting web server) operates. The access mode should be set to 600.
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 CCONNECT 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 cconnect 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
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 connectivity between the Web Gateway and InterSystems IRIS, these libraries include the CCONNECT library and SSL/TLS libraries (libssl.so and libcrypto.so). When the Web Gateway and CCONNECT libraries, loaded in the web server's process space, load a copy of the SSL 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 libraries are loaded in the web server process space, the Web Gateway must instruct the CCONNECT library to source the SSL libraries from the same location as those used by the hosting web server.
To do this, specify a path for the SSL libaries in the Web Gateway configuration file (CSP.ini) in the SYSTEM section with the CCONNECT_LIBRARY_PATH parameter. Restart the hosting web server after modifying this parameter. For example:
[SYSTEM] 
CCONNECT_LIBRARY_PATH=/lib/amd64/  
Important:
You must use the SSL 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-based Authentication and Data Protection
You can use the SSL protocol to secure communications between the Web Gateway and InterSystems IRIS.
In this mode, the SSL transport, as configured for this host, secures connections to InterSystems IRIS. The SSL 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 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” in the section Kerberos Library on setting a path for the SSL 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). On the [System] > [Configuration] page, select Web Gateway Management and Go. 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).
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 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
OR:
Server: Sun-ONE-Web-Server/6.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 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:
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
You can download the GZIP/ZLIB library from the following site:
http://www.zlib.net/
This resource was developed by Jean-loup Gailly and Mark Adler (Copyright (C) 1995-2006).
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), and a shared object (or shared library) for UNIX® systems (libz.so or libz.sl). The library libz.so (or libz.sl) is usually pre-installed on all Linux systems (it is usually installed in /usr/lib/ or /usr/local/lib).
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 Windows, the ZLIB library should be installed in the Windows System32 directory:
C:\WINDOWS\SYSTEM32\ZLIB.DLL
It should be noted that in the latest distributions, the library is named as ZLIB1.dll. This must be renamed to ZLIB.DLL in order for the Web Gateway to find it.
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.3.
       (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 (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’s usually not possible to know, in advance, how much data a CSP 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 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. The default is 500 bytes.
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
This enhancement extends 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 does not, at least in the first instance, be 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 enhancement 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 is not dependent on the latest modifications to the CSP module. 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 authorisation 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:
http://httpd.apache.org/docs/2.0/mod/mod_auth.html
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 
AuthCSPEnable On 
# The following directive is necessary for Apache v2.2 (and later)
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.
For InterSystems IRIS systems v5.1 (and later), users 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 Select.
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 
# The following directive is necessary for Apache v2.2 (and later)
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 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 page (System Administration > Configuration > Web Gateway Management).
A list of InterSystems IRIS servers may be defined for an application (path). Use the Servers parameter to check the purpose for which they are to be used. There are three options:
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 Page.
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 neither option is selected, is to use the first InterSystems IRIS server defined in the list.
Following is the list of 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 connection fails and the affected client receives a Server Availability error.
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.
Two new columns, Mirror Name and Mirror Status have been added to 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 privateand cache 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 terminate 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 will list all connected (i.e. active) Web Gateway installations and write 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 will be 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.
Further documentation will be found 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. In other words, the channel already 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 expected 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 final highlighted section is the most significant for the purpose of developing portable web applications.
Server Support
The server-oriented JavaScript-based Node.js technology arguably offers the most sophisticated, and currently most mature, implementation of the WebSockets protocol. And for this reason, WebSockets have been closely associated with Node.js up until the time of writing (March 2013). However, other web server technologies are quickly catching up and the latest versions of all major web servers now offer WebSockets support as shown below.
The highlighted section is the most significant for the purpose of developing portable web applications with CSP.
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 WebSocket protocol is implemented in JavaScript code. Standard text books describe the usage model in detail. This document will briefly describe 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 asynchronously over a pool of shared 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 echo 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 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)
This build provides an option to 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