CSP Gateway Configuration Guide
CSP Gateway Operation and Configuration
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This topic describes how to configure the CSP Gateway and exploit its functionality in CSP applications. It contains the following sections:

CSP Web Gateway Management Page
The CSP Web Gateway Management page allows you configure and manage the CSP Gateway, including monitoring its operational status. The following table shows the options available on the CSP Web Gateway Management page menu.
Menu Item Action
System Status Displays the status of active CSP server connections. Also allows you to clear the CSP Gateway cache.
Close Connections Closes all connections on all or specified Caché servers.
Test Server Connection Tests the connection to a Caché server by opening a stateless session. There is also an option to display the Caché-side Event Log.
View Event Log Allows you to view information in the CSP 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 CSP Gateway.
Default Parameters Allows you to configure the CSP Gateway on a specific web server. Also, it allows you to customize CSP responses to errors and other conditions.
Server Access Configures CSP Gateway access to a specific Caché 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 CSP Gateway Shows the CSP Gateway version, the hosting web server environment, including the path to the Gateway configuration.
The CSP Web Gateway Documentation (online help on configuring the CSP Gateway) is available in this section as well as through the Help button on the CSP Web Gateway Management Page in the Management Portal [Home] > [System Administration] > [Configuration] > [CSP 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 CSP Web Gateway Management page for your production web server, substitute localhost for localhost:57772 in the URL, as http://localhost:<port_no>/csp/bin/Systems/Module.cxw.
For more information on default Caché web server port numbers, see the WebServerPort entry of the Caché Advanced Configuration Settings Reference.
The first time you try to access the CSP Web Gateway Management Page, you are asked for a username and password. Look for the username in the C:\Intersystems\Cache\CSP\bin\CSP.ini file. The password is the one that you entered during the Caché installation. If you forget the password, see the section Security.
Localization of the CSP Web Gateway Management Page
Localization of the CSP Web Gateway Management pages is based on the contents of the CSPres.xml installed (if any). If no localization file is present then the CSP 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 Caché 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 CSP Web Gateway Management Page
By default, only clients local to the Gateway’s hosting computer are allowed access to the CSP 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 CSP 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:\Intersystems\Cache\CSP\bin). The System_Manager parameter represents a comma- (or plus-, + ) separated list of clients (by IP address) who may access the CSP 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 CSP 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 CSP 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 CSP 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 Caché
The first status table (Connections to Caché) displays information on connections to Caché.
Item Function
Connection Number Number that the CSP Gateway assigns to the connection. Your Caché 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 Caché system connected to. Mirror members show current configuration name with mirror member name appended.
IP Address IP address of the Caché system.
TCP Port TCP port on the Caché server through which the connection communicates. The default port is 1972.
Caché PID Process ID on the Caché server.
Status Indicates whether information is being sent to or from the Caché 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 Caché 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: Caché Servers
The second status table (Caché Servers) displays information on Caché servers.
Item Function
Server Name Name of the Caché system connected to.
IP Address IP address of the Caché system.
TCP Port TCP port on the Caché server through which the connection communicates. The default port is 1972.
Total Connections Number of connections to the Caché 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 Caché system has processed.
Queued Requests Number of Web requests that are held in a queue waiting for a free connection to the Caché system. Queued requests are an indication that the Caché 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 CSP Gateway assigns to the application path.
Path The application path.
Server Number The number that the CSP Gateway assigns to the Caché server.
Server Name The name of the Caché 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 CSP 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 CSP 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 CSP 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 > CSP Gateway Management).
Closing Connections Manually
If your Caché 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 Caché 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 Caché system is down.
Testing Server Connections
The Test Server Connection option on the CSP Web Gateway Management page menu is useful to test CSP Gateway connectivity to your Caché 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 Caché system from the displayed list.
  3. Select View Server-side Log to see the CSP error log on the Caché 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. For Caché v5.0 (or earlier) the form lists the variables (both user-defined and CGI Environment) that were passed to the server with the request. The form just shows the basic parameters returned by the target Caché server (version and process ID). The new minimal connection worked form was introduced for security reasons.
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 Caché is unreachable. If there are no additional error messages, check to ensure your Caché system is running.
Server is currently unavailable The CSP 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 CSP Gateway. Note that you must be a system manager to use this option.
When you configure access to a particular Caché 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:
CSP 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 CSP Gateway. The Gateway generates a default value which is shown beneath the text box. The value of this parameter is transmitted to Caché with the request data as system variable CSPIHN. Caché based software 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 Caché that can be created from this Gateway instance. Note that prior to 2012.2, the default value in Caché followed the HTTP 1.1 recommendation and was set to 2. In Cache version 2012.2 and later versions, the default value is set to 6 (since most modern browsers, such as Internet Explorer 8 allow 6 connections per session. 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 Gateway (or hosting web server) restart.
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 – which is the amount of memory typically required to cache the static components used in the CSP/Zen samples. 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 CSP 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 Cache 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 CSP 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 CSP 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 CSP Web Gateway Management page using this option. The default is Enabled. When access is Disabled you cannot re-enable access using the CSP 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 CSP Web Gateway Management page.
Password
Password required to access the CSP 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 CSP 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 CSP Gateway (that is, the web server host) can configure CSP.
This field is supplemented with a checkbox (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>CSP Gateway Management</title>
</head>
<h2>CSP 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 Caché
This section contains parameters related to maintaining connections to Caché.
Server Response Timeout
The maximum number of seconds allowed for the target Caché 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 Caché 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 Caché 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, Caché 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 checkbox (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
Allowsr static files to be served asynchronously in state-aware applications. In state-less 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 CSP Gateway. The connection lock is responsible for ensuring that all requests for the user/session are routed to the same Cache process. For applications that rely on static components being served from Cache, 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 Cache. 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 state-less 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 2013 ...GET /csp/samples/zenutils.js       
     State-Aware Session (preserve == 1)     
     Process this request concurrently in the pool of state-less 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 CSP 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/cspgateway/home/
If the server is used to server CSP applications then the broker components should be installed under:
/opt/cspgateway/home/broker/
The static files used to support the CSP samples:
/opt/cspgateway/home/samples/
The static files used to support the Caché Management Portal:
/opt/cspgateway/home/sys/
Custom Error Pages
The Error Pages section of the global configuration screen allows you to customize CSP Gateway error messages and system responses. These can be set on a global or per-Caché 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 web applicationage that you wish to replace the corresponding Gateway page with. Enter the full physical path to your web applicationage, or enter a path relative to that of the CSP Gateway.
The CSP Gateway system responses that you can customize are as follows:
Server Error
Page to display when the CSP Gateway encounters an internal error. For example, an error occurs if there is a problem communicating with a Caché server. The specific error is always recorded in the CSP Gateway Event Log.
Server Busy
Page to display when all available CSP connections are in use.
Server Unavailable
Page to display when the Caché 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 CSP 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 Caché servers); however, you may set a different value for individual Caché Servers.
The CSP Gateway writes the Event Log to the serial file named CSP.log. This file is placed in the same directory as the CSP 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 CSP Gateway and a Caché system. Use this option to record the strategic points of communication between the CSP Gateway and a Caché 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 CSP Gateway and Caché (Start and Close points for each connection).
  • Transmission interrupts received from the browser.
  • Cases where connections to Caché are forcefully closed (Due to no response from Caché 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: Caché 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 Caché.
  • Request Data from the Web Server (except multipart attachments).
  • Headers to the data blocks received from Caché.
V7 In addition to the information specified for previous levels, this level records: The full content returned from Caché.
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 Caché.
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 Caché 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 Caché. 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 Caché: Time taken between the request reaching the Gateway and a connection to Caché 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 Caché: Time taken between the first and last Byte of request data being read from the web server and dispatched to Caché.
  • Processing request in Caché: Time taken between the last Byte of request data being dispatched to Caché and the first Byte of response data being received by the Gateway.
  • Receive response from Caché: Time taken between the first and last Byte of response data being received from Caché and dispatched to the web server.
pp[n]
Provides detailed timing information as follows:
  • Pre-processing of request: Time taken to identify the target Cache server; includes the initial handover from the web server and basic request processing to identify the server.
  • Obtain [NEW] connection to Cache: Time taken to allocate a connection to the appropriate Cache 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 Cache.
  • Send request to Cache: Time taken between the first and last byte of request data read from the web server and dispatched to Cache.
  • Processing request in Cache: Time taken between the last byte of request data dispatched to Cache 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 Cache. The footer data is part of the internal communication protocol between the Gateway and Cache and includes control information (For example: instructions to change the preserve setting for the session).
  • Receive footers from Cache: Time taken to receive the response footer data from Cache.
  • Post-processing of footers: Time taken to process footer data and respond to instructions received.
  • Release connection to Cache: Time taken to release the active connection to Cache.
  • 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 Caché system accessed by the CSP Gateway must be defined here. Any unspecified optional parameters or custom system forms are automatically inherited from the CSP Gateway global configuration.
Adding a Server Configuration
To configure access to a Caché 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 Caché server to connect to.
Superserver TCP Port The TCP port number on which the Caché server is listening for incoming connections. This is the TCP port number of the Caché superserver which is usually 1972.
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 CSP gateway, which will cause the Gateway to ignore the VIP. Instead, simply configure the CSP Gateway to connect to the VIP like any other client. In general, use of a mirror aware CSP 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 CSP Gateway implements process affinity. This means that it always attempts to reconnect sessions to the same Caché process that serviced their previous request if possible. This parameter specifies the minimum number of connections that the CSP Gateway should make to the Caché 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 Caché server. If concurrent usage exceeds this number, the CSP Gateway starts to queue requests. Requests remain in the queue until a Caché 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 Caché that can be concurrently used by an individual session.
Connection Security
Connection Security settings are required by the Gateway to access the Caché 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 Caché server. Select one of the options:
  • Password
  • Kerberos
  • Kerberos with Packet Integrity
  • Kerberos with Encryption
  • SSL
Username Username required by the CSP Gateway for connecting to the Caché server.
Password Password required by the CSP Gateway for connecting to the Caché server.
Password (Confirm) When you create a new password, confirm the new password by entering it again.
Product Product being connected to, either Caché or Ensemble.
Service Principal Name Service principal name. A Generate button is provided for creating a default name with respect to the target Caché 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 Caché.
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 CSP Gateway global configuration described in the section Connections to Caché.
Error Pages
The Error Pages parameters let you customize the CSP 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 Caché 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 CSP application must have the path to its CSP files configured. The configuration for each path identifies the Caché 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 CSP 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 CSP 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:
    A Caché 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 Caché. 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 CSP Gateway. In this example: /csp/samples/menu.csp/csp/aaa/bbb/ccc.cls, the CSP 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 Caché 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 CSP Gateway to send all Environment Variables supplied by the web server to the Caché 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. For example, you could build your own WebDAV server by creating a WebDAV class and defining it here. There is a WebLink emulation class which makes use of this facility: %CSP.WebLink.
GZIP Compression Enable or disable GZIP compression for all CSP pages returned in this path (default is Disabled). (Not available on OpenVMS.)
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
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 Cache 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 checkbox 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 Caché 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 Caché 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 asEnabled 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 CSP Gateway Page
This is the default page displayed when you first enter the CSP Web Gateway Management page. It shows the Gateway build number, the version of the Caché distribution with which the Gateway was supplied, the version of the hosting web server, and the name and location of the Gateway configuration file (CSP.ini)
Example:
Version: 2015.1.0.205.0 
Gateway Build: 1501.1457
Web Server Name: 127.0.0.1 
Web Server Type: Microsoft (or ISAPI-compliant) Web Server: Microsoft-IIS/5.1 
Cache-Server-Pages/2015.1.0.205.0-1501.1457 
Active Interface: IIS ISAPI
Configuration:            \\?\C:\inetpub\CSPGateway\CSP.ini
CSP Gateway Build Numbers
The Gateway build number is made up of two numeric components. The first number indicates the version of Caché with which the Gateway modules were supplied. For example:
The second number is the internal Gateway build number. This number is incremented every time a modification is made to the Gateway modules and, because of this, it is the critical factor in determining whether or not a particular feature is included in a particular version.
CSP Gateway and Security
This section describes how the CSP Gateway relates to Caché security features. For more details on CSP authentication, see the chapter Authentication in the Caché Security Administration Guide.
Gateway connections to Caché can be protected according to the following levels of security:
  1. Minimal connection security (as was the case with early versions of the Gateway and Caché).
Remember that security applied here is solely for the purpose of authenticating the Gateway host to the Caché server. It protects against the unauthorized creation of connections to the CSP engine (%cspServer). It does not, however, identify an individual user of a CSP application. A user of a CSP 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 Gateway connection to Caché and an individual user of a web application. Many users share the same connection.
Authenticating the CSP Gateway to Caché at connection time is important. If an attacker can impersonate a CSP 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 CSP application. The CSP Gateway's Caché username and password, Windows network credentials, or UNIX® Kerberos key table should never be used by ordinary users.
Gateway Security Parameters
Maintain the following security parameters using the CSP 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 Gateway and Caché. This mode of operation is the default scenario if an older version of the Gateway is used (that is, an installation without the additional security parameters). It is also the mode of operation if a newer Gateway is used to connect to an earlier version of Caché (pre version 5.1).
If this mode of operation, ensure that the CSP service (%Service_CSP) 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 Gateway and Caché.
It should be remembered that Caché passwords are a weak form of authentication since they must be sent over the network as plain text for authentication in Caché. 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 Gateway configuration file (CSP.ini) in accordance with the following guidelines.
In all cases, the default username and password used for the CSP 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 using functionality provided by Microsoft’s Data Protection API (DPAPI). The CSP Web Gateway Management page handles the encryption of passwords.
Occasionally, you need to introduce a password outside the context of the CSP Web Gateway Management page, for example, if the Gateway configuration is set up by custom configuration scripts. In this case, the password should be filed as plain text and the Gateway encrypts it when it is started for the first time.
A form of password encryption is used for Windows because ordinary Windows user accounts are occasionally granted membership in the Administrators Group. This is not recommended practice for production systems but it does happen. Encrypting the password offers a higher level of protection for all Windows installations.
It is not possible to move a CSP.ini file containing encrypted passwords to another computer: The passwords must be reentered and, then, re-encrypted on the new machine. This can be a problem in clustered environments that share a CSP.ini on a shared drive. For information on how to handle this, see the Caché and Windows Clusters chapter in the Caché High Availability Guide.
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 Gateway (or hosting web server) operates. The access mode should be set to 600.
OpenVMS
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 Gateway (or hosting web server) operates. The file protection should be set to: (s:rwed, o:rwed, g:, w:)
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 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 Gateway installation.
The 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: CSP 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 Gateway and Caché)
If the 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 Gateway and Caché, the Gateway is the Kerberos client.
The procedure for configuring the Gateway to use Kerberos is in the following two sections — Windows and UNIX and OpenVMS.
Overriding the Library Path If You Use SSL
By default, the Gateway expects dependent security libraries (shared objects) to be installed in its home directory (that is, the directory with the Gateway binaries).
If you use SSL connectivity between the Gateway and Caché, these libraries include the CCONNECT library and SSL/TLS libraries (libssl.so and libcrypto.so). When the 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 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 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/  
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 Caché.
For practical purposes the 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 Gateway to Caché.
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.
Gateway Configuration
Set the Service Principal Name to that of the target Caché server that the Gateway is connecting to. Leave the Username, Password, and Key Table fields empty.
The client principal name (or client username) is that of the Gateway host. This is the Kerberos name representing the Gateway hosts' network service session:
<computer_name>$
Assign this principal the necessary privileges in the Caché server to allow the Gateway’s service to operate.
UNIX® and OpenVMS
These Operating Systems support Kerberos Key Tables. The Gateway configuration is conceptually more straightforward for these systems.
Gateway Configuration
Set the Service Principal Name to that of the target Caché server that the 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 Gateway host. This is the name used to identify the key in the Kerberos Key Table. Assign this principal the necessary privileges in the Caché server to allow the Gateway’s service to operate.
SSL-based Authentication and Data Protection
You can use the SSL protocol to secure communications between the Gateway and Caché.
In this mode, the SSL transport, as configured for this host, secures connections to Caché. 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 Caché systems, see the chapter Configuring the CSP Gateway to Connect to Caché Using SSL/TLS in the Caché 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 CSP Gateway transmits the common environment variables to Caché with each and every request. If extra environment variables are required by the application, they must be explicitly requested in the CSP Gateway configuration (via the Extra CGI Environment Variables setting in the Application Access section of the configuration). On the [Home] > [Configuration] page, select CSP 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. See also the section CgiEnvs Property and CGI Environment Variables in Using Caché Server Pages.
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 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 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 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=Cache 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 CSP 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 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 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
Making a CSP Page the Home Page for the Web Server
This section describes how to set CSP page as the web server’s default page (or home page). As an example, the procedure for making the CSP samples menu (/csp/samples/menu.csp) the server’s default page is described. The web server’s default page is accessed via:
http://<web_server>/
Note that when a CSP page is served in this way, embedded URLs must be specified in full. If relative URLs are used for embedded hyperlinks, the browser interprets these as relative to the documentation root directory and not the CSP root. For example, taking our samples menu as the home page, the URL to, say, the inspector option should be:
http://<web_server>/csp/samples/inspector.csp
If relative URLs are used, then the browser incorrectly interprets this link as:
http://<web_server>/inspector.csp
Internet Information Services
  1. Open the Internet Services Manager window.
  2. In the left-hand window, navigate to the Default Web Site.
  3. Right-click Default Web Site and select Properties from the menu to display the Default Web Site Properties window.
  4. Select the Documents tab.
  5. Select Add to display the Add Default Document Name window.
  6. Enter the document name (/csp/samples/menu.csp) for the Default Document Name window.
  7. Select OK .
  8. Ensure that the Enable Default Document check box is selected.
  9. In the Directories tab, use the arrow keys to move the new default document (/csp/samples/menu.csp) to the top of the list.
  10. Select Apply and OK to save and activate all changes.
The new default page (/csp/samples/menu.csp) must physically exist relative to the web server’s documentation root directory. It is only necessary to create an empty file. For example, if your document’s root is c:\inetpub\wwwroot proceed as follows:
cd c:\inetpub\wwwroot
md csp
cd csp
md samples
cd samples
copy con menu.csp
^Z
Sun Web Servers
The procedure described in this section is only available with Gateway build 663.763 (and later).
The following directive specifies the home page for a Sun server in the default section of obj.conf:
NameTrans fn="home-page" path="/csp/samples/menu.csp"
This directive, however, does not result in the CSP form menu.csp becoming the home page for the server. The reason for this is that the server does not update the environment variables relating to the page requested before transferring control to the CSP Gateway. The Gateway sees the incoming request as a request for / instead of /csp/samples/menu.csp. Netscape-based servers expect NSAPI extensions to accept the responsibility for recognizing this scenario and update the variables identifying the page requested and its path accordingly. You can work around this behavior as follows:
  1. Define the CSP home page in the default section of obj.conf:
  2. The section that describes the mapping between CSP files and the Gateway modules must be modified to include the home-page-path directive as follows:
    <Object ppath="*/*.[Cc][Ss][Pp]">
    Service method=(GET|HEAD|POST) fn=csp_req home-page-path="/cache-install-dir/csp/samples" 
    </Object> \
    <Object ppath="*/*.[Cc][Ll][Ss]">
    Service method=(GET|HEAD|POST) fn=csp_req home-page-path="/cache-install-dir/csp/samples" 
    </Object> \
    <Object ppath="*/*.[Zz][Ee][Nn]">
    Service method=(GET|HEAD|POST) fn=csp_req home-page-path="/cache-install-dir/csp/samples"
    </Object> 
    <Object ppath="*/CSPn3Sys.so">
    Service method=(GET|HEAD|POST) fn=csp_req_sys
    </Object> 
    <Object ppath="*/CSPn3.so">
    Service method=(GET|HEAD|POST) fn=csp_req
    </Object>
    
It is not entirely necessary to specify the path to the home page in the home-page-path property within the Service directive, but if you do, it results in the PATH_TRANSLATED environment variable taking the value that it would have done had /csp/samples/menu.csp been requested directly. In other words, PATH_TRANSLATED for the home-page (/) is returned as:
/install-dir/csp/samples/inspector.csp
instead of:
/csp/samples/inspector.csp
Apache Servers
Find the DirectoryIndex directive in the Apache configuration file. For example:
DirectoryIndex index.html index.html.var
Add the new default page for the web server at the head of the list:
DirectoryIndex /csp/samples/menu.csp index.html index.html.var
Compressing the Response to Requests for CSP Forms (GZIP/ZLIB)
Note:
The CSP Gateway does not support GZIP compression on OpenVMS.
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 CSP Gateway are as follows:
The 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 Gateway is supported. It is implemented as a DLL for Windows (zlib.dll), a shared object (or shared library) for UNIX® systems (libz.so or libz.sl) and a ZLIB library is available as a shareable image for OpenVMS. 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 Gateway dynamically links to the ZLIB library when response compression is requested for the first time. Thereafter the ZLIB library remains loaded until the 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 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 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:
CSP Gateway Initialization
The ZLIB library is loaded - Version 1.2.3.
       (This library is used for the optional GZIP compression facility)
If the 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 Gateway implements two modes of operation (1 and 2) for compressing the response data using the ZLIB library:
  1. In this mode, the Gateway streams all data received from Caché into the compressor. When all the data has been processed, the compressor streams the compressed data back to the 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 Gateway streams all data received from Caché into the compressor. On each and every call, the compressor makes as much compressed data as it can available to the 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 CSP applications where it’s usually not possible to know, in advance, how much data a CSP response contains.
If (and only if) the Gateway is able to successfully compress the data stream returned from Caché, 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: Fri, 15 Aug 2003 10:05:18 GMT 
EXPIRES: Thu, 29 Oct 1998 17:04:19 GMT PRAGMA: no-cache Content-Encoding: gzip
Before attempting to compress response data, the Gateway always checks the value of the Accept-Encoding HTTP request header (the HTTP_ACCEPT_ENCODING CGI environment variable). The 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 Gateway attempts to compress the response.
<script language=Cache 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=Cache 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). (Not available on OpenVMS.)
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
Separate additional types or extensions with a space.
Monitoring
An Event Log level of V3 instructs the 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)
CSP Page Output Caching
Most web developers are familiar with the way web browsers support a client cache of previously requested web pages. Client-side page caching can improve the performance for individual users by allowing previously accessed pages to be retrieved from local storage (memory or local hard drive) rather than as a result of fetching the document from the original server.
CSP Page Output Caching provides the option to maintain a cache of frequently accessed pages within the CSP Gateway. Since the Gateway is a core component residing on the web server, its cache can be shared amongst all users of that CSP installation. For example, if a single user requests a page that is configured to be placed in the Gateway cache, then all subsequent requests for that page can use the cached copy. Cached pages are available to all users. This facility can have a dramatic effect on performance for two reasons: Firstly, from a user’s perspective, pages retrieved from the cache are served extremely quickly and, secondly, the Caché system is not involved in the delivery of cached pages so its work load is significantly reduced.
The Page Output Caching facility implemented for CSP is based on the equivalent mechanism provided by Microsoft’s ASP.NET product. This choice of design was made in order to reduce the amount of learning involved in getting to grips with this facility. Most developers are familiar with ASP.NET.
Page caching is controlled by settings within the CSP %response object. Two properties are available for controlling which pages should be cached and for how long. The default behavior of CSP is that pages should not be placed in the cache.
%response.Expires Property
The standard Expires property controls how long a page should reside in the cache.
For example, if a page is set to expire in one minute, the Gateway removes the page after it has resided in the cache for 60 seconds.
%response.Expires=[60 seconds time]
The equivalent ASP.NET directive would be:
<%@ OutputCache Duration="60"%>
%response.VaryByParam Property
This property allows you to control how many cached versions of the page should be created based on name-value pairs sent through HTTP POST/GET. The default value is None. None implies that only one version of the page is added to the cache, and all HTTP GET/POST parameters are simply ignored. The opposite of the None value is *. The asterisk implies that all name-value pairs passed in are to be used to create cached versions of the page. The granularity can be controlled, however, by explicitly naming parameters (multiple parameter names are separated using semicolons).
The use of the VaryByParam property is best illustrated by means of an example. Let's say we're building a web application that is capable of displaying the weather forecast for the 50 United States. This application is completely encapsulated in one page: Weather.csp.
Weather.csp presents the user with a drop-down list of states. A state is selected from the drop-down list and the value of the state is sent back to Weather.csp. For example, State=WA or State=TX. For the sake of simplicity, let's assume that we're using HTTP GET to send the data. Once an item (i.e. State) is selected, the request is sent to the server:
Weather.csp?State=WA.
Let's assume that the forecast is only updated once a day and that there’s a significant overhead in generating the forecast.
We could add the following directives to the %response object of Weather.csp:
%response.Expires=[2 hours time]
%response.VaryByParam="State"
The ASP.NET equivalent would be:
<%@ OutputCache Duration="10800" VaryByParam="State" %>
This would result in every single page, for each state, being cached independently of one another for two hours:
Weather.csp
Weather.csp?State=WA
Weather.csp?State=TX
...etc.
Now suppose that we add further functionality to show the weather for a specific city. In order to cache pages based on the state and city parameter, we would change the cache directives to:
%response.Expires=[2 hours time]
%response.VaryByParam="State;City"
The ASP.NET equivalent would be:
<%@ OutputCache Duration="10800" VaryByParam="State;City" %>
The VaryByParam property allows us to cache multiple versions of the same page based on parameters sent through HTTP GET/POST. Be extremely careful when using *, as this can potentially fill the output cache with pages that are not frequently accessed. Remember, the more specific we make the VaryByParam property, the more frequently the Gateway can serve pages from the cache. For example, when only specifying a state, we have 51 versions of the page in the cache (50 states + the version with no parameters). When the city parameter is added, and assuming that we have an average of 15 cities per-state, we suddenly increase the number of potentially cached pages to 751.
The Gateway automatically evicts pages from the cache if it becomes constrained by memory as a result of the total volume of the cache becoming too large.
Preserving the User’s Session ID for Cached Pages
The requesting user’s session ID must be preserved within pages retrieved from the cache, regardless of whether the session is being maintained via a Cookie (CSPSESSIONID) or via the token (Form/URL variable: CSPCHD).
When a page is cached it is cached against the identity of the user that actually retrieved the page from Caché. This page contains the session ID as either the CSPSESSIONID cookie or as the CSPCHD token. Before serving a cached page to the user, the Gateway replaces all occurrences of both variables with the requesting user’s session token. In fact, the session cookie is actually removed from the cache, which achieves the same thing because the Cookie is preserved on the requesting user’s browser.
For example, let’s suppose that a page is cached by user xxxxxxx. The page is cached with the following identity:
Set-Cookie: CSPSESSIONID=xxxxxxx;
Now, when another user aaaaaaa subsequently retrieves this page from the cache, the cookie is, theoretically, changed to:
Set-Cookie: CSPSESSIONID=aaaaaaa;
In fact, as mentioned previously, the cookie is simply left alone on the requesting user’s browser.
The Gateway must, however, take action for pages that maintain the user’s session through the session token, CSPCHD. In this case, the initial cached page contains references to the original user as shown below:
<A HREF="/csp/page.csp?CSPCHD=xxxxxxx">
<INPUT TYPE=SUBMIT NAME="CSPCHD" VALUE="xxxxxxx">
The Gateway automatically changes the value of the session token to reflect the identity of the requesting user. For example, when user aaaaaaa subsequently requests this page from the cache, the Gateway modifies these lines as follows:
<A HREF="/csp/page.csp?CSPCHD=aaaaaaa">
<INPUT TYPE=SUBMIT NAME="CSPCHD" VALUE="aaaaaaa">
CSP with Microsoft Active Server Pages (ASP) and VBScript
You can mix CSP pages with ASP pages and vice versa provided the integrity of the user's session is maintained for both environments. Both environments maintain their sessions using identifiers stored in cookies. CSP stores its session ID in a cookie named with a prefix of CSPSESSIONID and ASP uses a cookie named with a prefix of ASPSESSIONID.
For example:
CSPSESSIONID=00200001000614eX37yi00363806761900000000000000000000000000
ASPSESSIONIDCCATBQCQ=DPLBEBECJLCJKIHKIKEFCCOA
Provided the session ID for each environment is protected when serving pages from the other environment, the application should be able to seamlessly and transparently swap between CSP and ASP based applications.
Client-side VBScript in CSP
VBScript, to be executed in the client’s Internet Explorer environment, can be added to CSP pages in the same way that JavaScript is used.
For example:
<script language=vbscript>
        document.write "The time is: ",time
</script>
Server-side VB-Script in CSP (Serving ASP Content through CSP)
Sometimes you want to construct and serve complete ASP pages from a CSP application. In this case, the pages generated by CSP contain VBScript that is executed on the web server host (in the ASP engine) as opposed to in the client’s browser.
The ASP (and ASP.NET) engine, in common with the CSP Gateway, is implemented as an ISAPI extension to IIS. However, there is no mechanism through which the CSP Gateway can route ASP content generated by CSP ‘sideways’ through the ASP engine.
The facility for serving ASP content through CSP is implemented in the CSP Gateway by saving the ASP page returned by CSP as a physical file under the IIS documents root. Having done this, the client is then redirected to that page. The second redirection step results in the newly created ASP page being processed by the ASP engine, at which point the server-side VBScript is executed before the final page is delivered to the client.
The CSP Gateway manages the redirection to the ASP resource in one of two ways.
Temporary ASP files are named according to the following convention:
CSPASP[n].asp
Where n is a unique number, incremented for each new ASP page created and reset to 1 when the Gateway is restarted.
Web Server and Gateway Configuration
To configure the web server and CSP Gateway to serve ASP pages from a CSP application
  1. First, create a physical location for the temporary ASP files under the IIS documents root. For example:
  2. For many Windows installations (particularly Windows 2000 and later), the default privileges assigned to the web server are not sufficient to allow the CSP Gateway to write to directories under the document root.
    You must, therefore, assign the web server write privileges to the asptemp directory, or grant the web server Administrator privileges.
    You can modify file-access privileges through Windows Explorer. Alternatively, you can use the following command:
    Where IUSR_xxx is the web server’s user authority. The xxx component is usually the computer name. You can find the specific name in the Internet Service Manager by navigating to the Authentication methods dialog as follows:
    1. Open the Internet Services Manager.
    2. In the left-hand window, navigate to the Default Web Site.
    3. Right-click the Default Web Site. Select Properties from the menu to display the Default Web Site Properties window.
    4. Select the Directory Security tab.
    5. Select Edit under the Anonymous access and authentication control panel. This displays the Username in the Authentication methods dialog.
  3. Modify the execute permissions assigned to the asptemp directory such that IIS is able to execute ASP pages in that directory.
    1. Open the Internet Services Manager.
    2. In the left-hand window, navigate to the Default Web Site.
    3. Right-click the Default Web Site. Right-click the temporary ASP directory (asptemp) and select Properties from the menu to display the Default Web Site Properties window.
    4. Select the Home Directory tab.
    5. Select Apply and OK.
    6. Set the following two parameters in the Gateway configuration (Default Parameters).
      Web Document Root:C:\Inetpub\wwwroot
      Temp ASP Directory:/asptemp
  4. Restart IIS.
Usage
To tell the CSP Gateway that the page should be further processed by the ASP engine,
  1. Set the %response.UseASPredirect property to true in the OnPreHTTP method of the page.
    <script language=Cache method=OnPreHTTP arguments=""
               returntype=%Boolean>
            Set %response.UseASPredirect=1 Quit 1
    </script>
  2. Declare VBScript in the CSP page:
Then, you can add both in-line VBScript and complete scripted sections to the page.
Examples:
<% Response.Write("<BR><B>ASP inline</B><BR>") %>

<script language=vbscript runat=server>
      Response.Write("<br><b>Message from ASP script</b><br>")
</script>

<%
    Dim n
    For n = 1 To 10 Step 1
    Response.write("<BR>These lines were generated by a 'for' loop in VBSCRIPT: <B>Line # " & n & "</B>")
    Next
%>
Complete example:
<script language=Cache method=OnPreHTTP arguments=""
        returntype=%Boolean>
     Set %response.UseASPredirect=1 Quit 1
</script>
<html>
<head>
<title> CSP/VBScript demonstration </title>
</head>
<body>
<h2> CSP/VBScript demonstration page </h2>
<script language=vbscript>
     msgbox "Message from client-side vbscript"
     document.write "The time is ",time
</script>
<% Response.Write("<BR><B>Message from ASP inline</B><BR>") %>
<SCRIPT LANGUAGE=VBScript RUNAT=Server>
     Response.Write("<BR><B>Message from ASP script</B><BR>")
</SCRIPT>
<script language=cache runat=server>
     set x="message from Cach&eacute"
</script>
<br>Message from CSP #(x)# <br>
</body>
9</html>
Implementing HTTP authentication for CSP applications
This enhancement extends the Apache modules (mod_csp*.so/dll and CSPa*[Sys].so/dll) to allow HTTP authentication to be controlled by Caché/CSP.
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 Caché/CSP environment for Apache-hosted CSP 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 CSP 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 Caché for authentication. The CSP 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 Cache 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 Caché 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 Caché security control layer is deployed.
Authenticating in CSP before the Request is Processed.
This is an alternative method for implementing HTTP authentication in Caché. It is intended primarily for cases where performing authentication at request-processing time in the CSP application would be awkward or time consuming. For example, for existing applications running under Caché v5.0 (or earlier), it might be impractical to add authentication checks to all public pages in the absence of a standard login page.
In this method, the user is authenticated by calling a dedicated authentication class. The CSP Gateway performs this check before dispatching the original request to Caché. When the user's details have been successfully checked by the authentication class, the CSP application need not perform any further Select.
Of course, this method bears the overhead of processing two requests (to Caché) 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 CSP 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 Caché server instances, such as in a Caché ECP configuration, each web server (and by implication, Gateway instance) should be configured to connect to a specific Caché 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 CSP applications. It is essential that each user session ‘sticks’ to the same back-end Caché server for the lifetime of the session – unless, of course, a failover event occurs.
Although the above approach is primary recommendation, the Gateway contains a basic (software-based) system for implementing load balancing and failover between multiple Cache servers. In this configuration a Gateway installation is configured to connect to a number of Cache servers. This facility is described in the remainder of this section.
Gateway load balancing and failover is configured in the Application Access section of the CSP Gateway Management page (System Administration > Configuration > CSP Gateway Management).
A list of Caché 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 Caché Server Instances
In configurations with multiple (equivalent) Caché server instances, such as in a Caché ECP configuration, the Gateway provides a basic (software-based) facility for implementing load balancing and failover between those Caché instances for web applications. An external solution like those described previously is the primary recommendation, however.
The failover mechanism provided by the Gateway is not necessary to implement failover between multiple Caché database servers in a typical High Availability configuration, such as failover clustering or Caché mirroring. Those technologies provide Virtual IP based failover and the 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 Gateway.
Gateway load balancing and failover is configured in the Application Access section of the CSP Gateway Management Page.
A list of Caché 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 Caché server defined in the list.
Following is the list of Caché 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 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 Caché configurations, a database is duplicated (or mirrored)between participating mirror members. A Caché mirror set configuration represents the set of participating mirror members for an installation. For a complete description of Caché mirroring, see the chapter Mirroring in the Caché High Availability Guide.
If Mirror Virtual IP (or an equivalent technology) is used to provide network redirection to the primary member, then configure the CSP 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 CSP Gateway to be mirror-aware. When the Gateway is mirror-aware, it assumes responsibility for determining which member is primary. To make a Gateway configuration mirror-aware, in the CSP 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 Gateway configuration to be mirror-aware. For example, a Gateway configuration supporting the Caché Management Portal should never be configured to be mirror-aware as the portal must always connect to a specific Caché server regardless of its mirror status.
If a mirror-aware Gateway configuration connects to a Caché server that is not a mirror member then the connection fails and the affected client receives a Server Availability error.
The Gateway obtains – from the Member that it first connects to – a list of failover members and disaster recovery (DR) members. The Gateway persists this list in its local configuration file (CSPRT.ini). If the 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 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 Gateway System Status form when the first connection is made. Mirror members are shown named as the current configuration name (as defined under the 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 'Caché 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 state-less. In order to get the best out of web architecture in terms of performance, maintainability and scalability web applications should embrace the state-less paradigm.
By default, CSP applications operate in a state-less environment with respect to the hosting Caché server. The CSP Gateway maintains a pool of connections to Caché 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 Caché process (as identified by the $Job variable).
For a normal CSP application operating in state-less mode, consider the choice of backend Caché process used to serve each request for a client session to be random. The Gateway chooses whichever connection/process happens to be free.
However, in the interests of efficiency, the Gateway does implement a form of Caché process affinity. In other words, it attempts, where possible, to route a request for a session to the same Caché 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 Gateway also attempts to implement process affinity based on NameSpace. The 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 Gateway routes all requests for a session to a reserved (or private) Caché connection/process. This mode of operation provides a state-aware environment with respect to the relationship between CSP sessions and their corresponding Caché 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 state-less counterparts and it is therefore recommended that new applications (and modifications to existing ones) be designed to be state-less as far as is practically possible. It is recommended that state-aware mode, if used at all, should be applied sparingly in predominantly state-less 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 a Caché 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 state-less counterparts. For example, the recycling of a web server worker process can happen transparently beneath a state-less application but results in all associated state-aware sessions closing. Of course, you can avoid the latter restriction by using the CSP Gateway’s NSD component to separate the management of the Gateway process pool from the hosting web server.
Creating a successful state-aware application (or state-aware sections within a predominantly state-less application) requires a certain amount of discipline.
Since all requests for a session must be processed by the same Caché process, a queue must be maintained to serialize access to the private Caché 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 CSP 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 Caché process.
Another potential pitfall in state-aware mode is the effect of the Server Response Timeout operating between the Gateway and Caché. When the 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 Caché is generating a response, the 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 Caché process is doing by closing the connection and the session is lost. Bear in mind that while the 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=Cache 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 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 Gateway in the response footers (dispatched after the response payload) and the 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 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 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 Gateway routes the request to a free state-less connection in the pool and Caché 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 state-less 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 state-less 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 Caché for CSP 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 Caché process).
Terminating State-Aware Mode
An application can revert back to a state-less 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=Cache 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 state-less before formulating and dispatching the HTTP response headers to the 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).
Gateway Registry in Caché
The Caché based CSP Gateway Registry registers each connected Gateway installation with Caché and provides the infrastructure to allow Caché code to interact with those Gateway installations. Such programmatically controlled interactions may include reading and modifying the Gateway’s run-time 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) Gateway installations and write the web server IP address, port and 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 Caché 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 Caché 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 Gateway to Reload Its Configuration
There are occasions when the Gateway’s configuration is modified by external agents (i.e. agents other than the Gateway’s own Systems Management Suite).
There are two methods for interactively instructing the Gateway to reload its configuration, and in a way that doesn’t require a complete restart.
Using the Caché-Based Gateway Registry
The following Registry Method is provided:
Set status = %CSP.Mgr.GatewayMgr.ActivateCSPIni()
When successfully called, the Gateway reads its configuration file (CSP.ini) and activates all changes made.
Using Scripts External to Caché
Scripts should add the following line (case sensitive) to the SYSTEM section of the modified Gateway configuration file (CSP.ini):
[SYSTEM]
RELOAD=1
The Gateway caretaker daemon checks the RELOAD flag approximately every minute and, if correctly set, reloads and reactives 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 respond 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 (CSP)
The base Caché 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 CSP 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 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 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 to 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 Caché 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 CSP 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 Gateway connections to Caché and messages to the client are dispatched over the pool of Server connections that have been established between the Gateway and Caché.
In asynchronous mode, the WebSocket Server becomes detached from the main CSP 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 a Caché 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 Caché 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 Gateway-maintained version/timestamp parameters from the Gateway configuration file (CSP.ini) to the run-time parameters file (CSPRT.ini). CSPRT.ini is owned and maintained by the CSP 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 CSP Gateway) at run-time.
To invoke this option, set the READONLY parameter in the CSP.ini file before initializing the CSP 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 Nov 12 18:02:57 2015
Configuration_Initialized_Build  = 1601.1551
Configuration_Modified           = Thu Jul 14 16:47:40 2016
Configuration_Modified_Build     = 1603.1599