Configuration Basics for the Web Gateway
After configuring the web server to work with the Web Gateway, configure the Web Gateway as needed. You can use the management pages to configure default parameters, individual servers, and web applications.
This page provides additional information on some common configuration topics.
Web Gateway Configuration and Log Files
The Web Gateway creates and uses a configuration file and a log file, respectively named CSP.ini and CSP.log. For convenience, the management pages indicate the locations of these files.
It is rarely necessary to edit the configuration file directly, because you normally perform configuration via the management pages. Where necessary, the documentation describes the directives in the configuration. If you need to edit the configuration file directly, see the class reference for %CSP.Mgr.GatewayMgrOpens in a new tab. The methods SetApplicationParams, SetDefaultParms, and SetServerParams provide short descriptions of the parameters.
File Types Automatically Routed to InterSystems IRIS
InterSystems file types are processed in InterSystems IRIS (specifically by the CSP engine). All other files (static files) can be served by the web server or by the CSP engine. The CSP engine can serve any type of file that is placed in the path of the web application (including static files). Setting up the CSP engine to serve static files simplifies the web server configuration for web applications because you, thus, do not need to create aliases in the web server configuration to represent the locations where an application’s static files are held. Setting up the CSP engine to serve static files resolves issues of contention when a single (that is, common) web server serves two different versions of InterSystems IRIS, each requiring different versions of certain static files (for example, hyperevent broker components).
To have the CSP engine serve static files for a particular web application, place the static files in the web application’s file system in the correct location relative to the CSP files that make up the application (not in the web server’s own documents file system).
To run Zen-based applications, you must enable the Serve Files option and properly configure your web server.
Serving Static Files from InterSystems IRIS
You can configure web servers and Web Gateway installations so that InterSystems IRIS assumes responsibility for serving static files. The Management Portal is configured for InterSystems IRIS to serve all components in the application. However, it is still possible to configure the web server so that it retains responsibility for serving static files.
The InterSystems IRIS database server serves all of CSP. It can also serve any kind of static file for a web application via the Web Gateway. In standard web applications, web servers (not database servers) typically serve static content.
Indicating Character Encoding
The CSP engine, via the stream server, handles static files in a manner consistent with major web servers, with respect to determining the character encoding of JavaScript files. The modern convention is for all JavaScript files to marked as Content-Type of application/javascript, and you make sure this is the case with all JavaScript files used on your pages.
With JavaScript files marked this way:
-
If a file contains a BOM (byte-order mark), the browser automatically detects this and uses the correct character set to read it.
-
If the file does not contain a BOM, then the browser assumes the file is UTF-8.
If you need to override this behavior to specify a character set for JavaScript files, set the global ^%SYS("CSP","MimeFileClassify","JS") to the list value $listbuild(contenttype, binary, charset). For example,
SET ^%SYS("CSP", "MimeFileClassify", "JS") = $listbuild("text/javascript", 0 ,"ISO-8859-1")
This sets the older content-type and uses the ISO-8859-1 character set. Also, if the Caché translate table is defined to be something other than an empty string or if the global node ^%SYS("CSP","DefaultFileCharset") is set to a null value, Caché will use this character set for all JavaScript and other text files. By default, neither of these global nodes are set.
Enabling the Serve Files Option
The Serve Files option for a web application has the following values:
-
Always — Serve Files is on.
-
No — Serve Files is off.
-
Always and cached — The Web Gateway can cache static files on the web server. This setting improves efficiency as the system can serve a cached static page without going back to the InterSystems IRIS server.
-
Use InterSystems Security — If the user has the appropriate authorization to access dynamic .csp or .cls pages which an InterSystems IRIS instance serves as part of a web application, then the CSP engine for that instance serves requests for static files at that web application location. If the user does not have appropriate authorization, then the CSP server returns an HTTP 404 response.
Configuring the Web Server to Allow InterSystems IRIS to Serve Static Files
By default, the installation script provided by InterSystems does not look for or configure an external web server. If you run a custom install, you can choose the option to configure any previously-installed IIS or Apache web server to enable support for the CSP engine. The installation script creates the /csp virtual directory and creates mappings for the InterSystems file types to be handled by the Web Gateway. This is sufficient for the CSP engine to function normally via that web server. It does not enable support for the Serve Files feature. You must manually configure your web server to map specific file extensions to be handled via the Web Gateway. This is by design because opening the database server up to exposure via this mechanism is a security risk and should not be done invisibly.
See Mapping Additional File Types for instructions for your web server.
Serving Static Files from the Web Server
You can use a traditional configuration of serving static pages from the web server. In this case, the setting of the Static Files option is irrelevant. This eliminates contention when a common web server serves two different versions of InterSystems IRIS, each requiring different versions of certain static files, for example, hyperevent broker components.
If you have configured the web server itself to serve static files, be sure that the static content is present on every single web server.
Enable Sticky Sessions on Hardware Load Balancer on High Availability Solutions
For High Availability solutions running over CSP, InterSystems recommends that you use a hardware load balancer for load balancing and failover. InterSystems requires that you enable sticky session support in the load balancer; this guarantees that — once a session has been established between a given instance of the Web Gateway and a given application server — all subsequent requests from that user run on the same pair. This configuration assures that the session ID and server-side session context are always in sync; otherwise, it is possible that a session is created on one server but the next request from that user runs on a different system where the session is not present, which results in runtime errors (especially with hyperevents, which require the session key to decrypt the request). See your load balancer documentation for directions on how to enable sticky session support.
It is possible to configure a system to work without sticky sessions but this requires that the web session global be mapped across all systems in the enterprise and can result in significant lock contention so it is not recommended.
Enable Script to Reactivate Web Gateway Configuration
You can enable a script that is external to InterSystems IRIS to reactivate the Web Gateway’s configuration.
Scripts should add the following line (case-sensitive) to the SYSTEM section of the Web Gateway configuration file:
[SYSTEM]
RELOAD=1
The Web Gateway caretaker daemon checks the RELOAD flag approximately every minute and, if correctly set, reloads and reactivates its configuration and removes the flag from the file. The following message is written to the Web Gateway Event Log after a successful reload operation:
Gateway Management
Gateway Configuration Reloaded and Reactivated
Hybrid Multi-Process/Multi-Threaded Web Server Architecture
The Web Gateway contains enhanced support for the hybrid multi-process/multi-threaded web server architecture. Apache version 2.4 under UNIX® is an example of a web server implemented according to this architecture.
The core Web Gateway resources are held in the shared memory sector. All web server worker processes hare a common running configuration, connection table and form cache. The Web Gateway System Status form shows the status for the whole web server installation instead of just that of a single worker process. The status form’s connection table includes an extra column with the web server process ID with respect to each connection to InterSystems IRIS.
Finally, state-aware sessions are supported in the multi-process architecture. Although the connection pool (to InterSystems IRIS) is distributed amongst several web server processes, the Web Gateway uses an InterProcess Communications (IPC) protocol to route requests for state-aware sessions to the correct hosting process in the web server environment.
