Installing the Web Gateway
The Web Gateway provides the communications layer between the hosting web server and InterSystems IRIS data platform for any InterSystems IRIS web applications. This chapter covers the following topics:
The InterSystems IRIS installation directory, as described in Installation Directory in the Installation Guide, is referred to as install-dir. When following instructions presented in this document, replace the install-dir placeholder with the correct path for your instance.
The recommended platform for web applications is REST. See “First Look: Developing REST Interfaces in InterSystems Products”.
Default Web Gateway Installation and Configuration
When you install InterSystems IRIS and choose a setup type of Development, Server, Custom (selecting the Web Server Gateway component), or Web Server (Windows platforms only), installation includes configuration of installed production web servers (IIS on Windows and Apache on Linux/UNIX®) and the Web Gateway. If this is suitable for your use case, installing the web server and then installing InterSystems IRIS provides a working Web Gateway configuration for InterSystems IRIS instances without requiring any adjustment.
However, if you are using different combination of web server and platform, have an atypical web server architecture, or are an advanced user who wants to customize your environment, be sure to review this document, which provides procedures for configuring a web server and the Web Gateway to connect to InterSystems IRIS and for using the services that the Web Gateway provides.
Web Gateway Components and Physical Installation Paths
Later sections in this guide describe how the Web Gateway components should be configured with all supported web servers. You should regard installation paths for components as examples rather than taking them literally. Also, the InterSystems installers create and maintain separate Web Gateway installations for the Private Web Server and any third-party web server that might be present on the same host. In this context ‘third-party web server’ refers to a web server that is not part of the software installed by InterSystems.
The precise installation location of Web Gateway components is not particularly critical provided:
The physical installation paths match those given in the hosting web server configuration where appropriate.
The security settings, in relation to required access for individual components, are adjusted appropriately. This is particularly important for Web Gateway components that are accessed directly by the web server since web servers are usually locked down to the extent that the files they are able to access (and executables that can be run) are carefully controlled. You should bear in mind that security considerations are also important for any Web Gateway configuration (and log) files that are accessed by Web Gateway binaries that are themselves bound to the web server core executable.
The security policy of the hosting web server is respected. Some web servers – notably those shipped with Secure Linux (SELinux) – are configured such that it is not possible for them to access files that lie outside their own file system. This restriction clearly has an impact on where certain web-server-facing Web Gateway components can be installed.
There are four types of Web Gateway component to consider.
Binaries to be loaded by the web server (API based extensions).
This includes Windows DLLs, and UNIX Shared Objects:
CSPms[Sys].dll CSPn3[Sys].(dll|so|exe) CSPa*[Sys].(dll|so) CSPx[Sys].(dll|so) mod_csp*.(dll|so)Copy code to clipboard
The physical location where these are installed should match the corresponding configuration directives in the hosting web server configuration. This includes directives indicating which third-party modules should be loaded. The web server requires permission to read and load these modules. Modules named CSP* require permission to read and write to the Web Gateway configuration and log files (CSP.ini, CSP.log). These are usually created in the same location as the Web Gateway binaries.
When considering access control for these modules, bear in mind that it is the web server worker processes that need to be able to access the modules together with any dependent configuration and log files. For example, in the case of Apache, the server is usually started with superuser permissions but the worker processes that actually serve web requests run with a much lower level of authority (as indicated by the User and Group directives in the Apache configuration file). It is the User and Group specified for the worker processes that should be granted permission to load the Web Gateway modules and (where appropriate) the ability to read and write to the configuration and log files (CSP.ini and CSP.log).
Executables to be called by the web server (Common Gateway Interface (CGI) modules). Not all configurations require these executables.
[nph-]CSPcgi[Sys][.exe]Copy code to clipboard
The physical location where these are installed should match the corresponding configuration directives in the hosting web server configuration. This includes directives indicating which web requests should be processed by these CGI modules.
The worker processes of the hosting web server require execute permission for these modules. There are no further dependencies.
Static files to be returned by the web server.Note:
With current Web Gateway configurations, CSP is often configured to serve static files directly from InterSystems IRIS as opposed to having the web server return them. This section does not apply to such configurations.
Java applets (such as CSPBroker.class, CSPBroker.jar, and so on)
Images (such as created-with-csp.gif, and so on)
The worker processes of the hosting web server require Read permissions for these files.
The CSP network service daemon (NSD).Note:
Not all configurations require this facility.
CSPnsd[Sv][.exe]Copy code to clipboard
The NSD can be installed anywhere and the web server does not need to be aware of its physical location since communication between these two points is over TCP, usually port 7038.
The NSD requires permission to read and write to the Web Gateway configuration and log files, CSP.ini and CSP.log, which are usually created in the same location.Note:
For security reasons, do not install this module in a location that is accessible by the web server. This module should not share a location with the modules listed in steps 1, 2 or 3. Many web server configurations described in this document explicitly exclude this module from the list of accessible files that can be accessed by the web server. However, it is much safer to physically install the NSD elsewhere in the file system.
The Web Gateway cache, kept in persistent storage.
Cached content is stored in files of type .dat in the Web Gateway's temp directory, placed by the install script directly beneath the Web Gateway's installation directory. For example, in a typical Internet Information Services (IIS) installation this is in: C:\Inetpub\CSPGateway\temp. The location needs full read/write/delete permissions for the hosting web server worker processes.
Supported Web Servers
The following summarizes the web servers supported by InterSystems IRIS.
More detailed information on supported web servers can be found in the section “Supported Web Servers” in the online InterSystems Supported Platforms document for this release.
The Web Gateway provides high-performance connectivity solutions for Microsoft, Apache, and Nginx web servers. In addition to these solutions, connectivity to InterSystems IRIS through the CGI is available for all supported Operating Systems.
Microsoft web servers support a multi-threaded API which allows extensions, in the form of dynamically bound libraries, to be made to the web server’s core functionality. Current versions of the Web Gateway make full use of these APIs in order to bring high-performance web connectivity to the InterSystems IRIS system. The Windows version of Apache also operates in an exclusively multi-threaded mode and, as such, can also take advantage of the Web Gateway implemented as a dynamically bound library.
The UNIX versions of Apache are architecturally different from the Microsoft Windows based web servers in that they are not exclusively multi-threaded. Apache version 2.4 is implemented using a hybrid model made up of threads and multiple processes. In this model, each UNIX process is effectively a multi-threaded server in its own right.
The Apache web server publishes a proprietary API in addition to supporting extensions implemented as CGI modules. Extra functionality can be added to Apache by means of user-defined modules (compiled C programs). In fact, a large part of Apache’s core functionality is implemented as a set of modules. You can add modules to Apache by one of two methods. First, the source to the module can be compiled directly into the Apache core. This option arguably offers the best performance but, unfortunately, involves reconfiguring and rebuilding the web server. As an alternative to building the module source directly into the Apache core, Apache versions 1.3 onwards support extensions implemented as dynamically linked libraries. This facility allows you to take advantage of the high performance of Apache modules without the need to physically build the module into the core of Apache. The CSP module is distributed as a Windows Dynamic Link Library (DLL), and as a UNIX Dynamic Shared Object (DSO). UNIX Shared Objects are conceptually similar to a Windows Dynamic Link Library (DLL) and are linked at run time. The overhead involved in linking to a library at run time is very low on modern operating systems.
A more recent addition to the set of web servers supported by CSP is Nginx. Unlike other web servers, Nginx is based on an asynchronous event-driven architecture. With the event-driven architecture, notifications or signals are used to mark the initiation and completion of each individual operation. A consequence of this design is that while web requests are being processed, resources can be temporarily released and used by other operations. Resources can be allocated and released dynamically and are only associated with the processing of a web request while they actually required. This leads to a highly optimized use of memory and CPU. The asynchronous nature of this architecture results in threads executing concurrently without blocking each other, thus further enhancing the sharing of resources that might otherwise be associated with a thread waiting on a blocking operation. Nginx is supplied with an API to allow extensions, such as CSP, to be added to its core functionality. However, unlike other web servers, extension modules must be built into the web server core at compilation time. Nginx does not support dynamically loaded extension modules.
An alternative architecture is also provided in which the functionality of the Web Gateway is implemented as a stand-alone executable, operating in its own process and not directly connected to a web server. This version of the Web Gateway is known as the NSD. In this context, the NSD is responsible for providing the Web Gateway’s core functionality and maintaining persistent connections to InterSystems IRIS. The web server communicates with the NSD via small modules of which there are two types: modules that work to the hosting web server’s proprietary API and modules implemented as CGI executables. The NSD-based architecture is therefore used in cases where there is a requirement to extend the web server by means of the CGI standard, or in cases where it is desirable to disengage the functionality of the Web Gateway from that of the hosting web server.
Deploying the Web Gateway as a Stand-alone Component
In some cases, such as when you want to locate the Web Gateway on the system hosting the web server for use by one or more remote InterSystems IRIS instances, you can deploy the Web Gateway as a stand-alone component in the following ways:
As described in Setup Type in the “Preparing to Install InterSystems IRIS” chapter of the Installation Guide, you can use the InterSystems IRIS installer to install the Web Gateway separately by selecting a Web Server setup on Microsoft Windows systems, or by selecting a Custom setup on any platform and including the Web Server Gateway component.
You can also install the Web Gateway independently using a stand-alone installer. The stand-alone installers for UNIX®/Linux and Windows are available on the WRC distribution site under Components. As with the InterSystems IRIS installers, the Web Gateway stand-alone installer is provided as an executable and the UNIX stand-alone installer is provided as a command line script. The defaults for the Windows stand-alone installer assume that you are using the IIS web server, and the defaults for the UNIX stand-alone installer assume you are using the Apache web server. If you have an atypical web server architecture, or want to customize your environment you should read this document carefully to understand the configuration options.
The webgateway container image available from InterSystems includes both the Web Gateway and an Apache web server, thereby providing a containerized web server for InterSystems IRIS-based applications. For more information about deploying Web Gateway containers from the webgateway image, see Using the InterSystems Web Gateway Container in Running InterSystems Products in Containers.
Note that you need a separate installation of the Web Gateway for each web server. For more information on configuring a remote web server, see the appendix “Using Web Applications with a Remote Web Server” in this book.
Upgrading the Web Gateway
If you need to upgrade the Web Gateway to a more recent version, you can replace the *.dll or *.so files and restart the web server, or use the stand-alone installer. If using the installer, stop the server before running the installer, and start it again after installation is complete.
If the CSP Gateway is already installed on your system and you want to replace it with the Web Gateway, simply install the Web Gateway with an InterSystems IRIS installer or stand-alone installer; the Web Gateway installation process automatically upgrades the CSP Gateway to the Web Gateway. For more information, see Preexisting CSP Gateway in the Installation Guide.
Configuring the Web Server and the Web Gateway
After installing InterSystems IRIS and the Web Gateway, consult the sections in this book relevant to your system to map file extensions for your system. The appendices in this book have configuration information for atypical Web Gateway configurations.
To prevent runtime errors, for High Availability configurations running over CSP, InterSystems recommends that you use a hardware load balancer with sticky session support enabled. For more information, see the section “Enable Sticky Sessions on Hardware Load Balancer on High Availability Solutions”.
Web Gateway Management Module Configuration
Web Gateway architectures that work directly to a hosting web server’s API typically consist of two modules: A Management Module (for example, CSPmsSys.dll) and a runtime module (for example, CSPms.dll). The runtime Module is responsible for processing requests for CSP files and the Management Module provides the Web Gateway’s Management interface. In the Web Gateway, the runtime Module assumes responsibility for loading and routing management requests to the Management Module. All requests for the Web Gateway (CSP and management) are processed by the Runtime Module. The Management Module must be installed in the same location as the Runtime Module.
File Types Served by CSP
Files of type .csp, .cls and .zen are processed in InterSystems IRIS by CSP. All other files (static files) can be served by the web server or CSP. CSP can serve any type of file that is placed in the web applications path (including static files). Setting up CSP 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 CSP 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 CSP 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). (Note that if you are serving files containing Unicode text, CSP uses the byte-order mark (BOM) to determine the correct encoding to use. The BOM must be present in Unicode text files.)
Consult the sections in this book for your platform.
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 statics.
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.
Web Gateway Registry
The Web Gateway is supplied with the InterSystems IRIS Gateway Registry. All web server and Web Gateway installations are registered with InterSystems IRIS as they connect. The registry contains the infrastructure to allow InterSystems IRIS code to interact with connected Web Gateway installations for the purpose of reading and writing the configuration and monitoring the system status and Event Log.
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 an external (external to InterSystems IRIS) script 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:
The Web Gateway caretaker daemon checks the RELOAD flag approximately every minute and, if correctly set, reloads and reactivates its configuration and removes the flag from the file. The following message is written to the Event Log after a successful reload operation:
Gateway Management Gateway Configuration Reloaded and Reactivated
Private Web Server and Management Portal
A minimal build of the Apache web server is supplied for the purpose of running the Management Portal. This server is known as the Private Web Server (PWS) and is built and configured to meet the management needs of InterSystems server products and is configured to only connect to InterSystems IRIS. The options selected to create the PWS are not, in general, suitable for production use. In particular, security is minimal and the configuration deployed is generally unsuitable for applications for which a high volume of HTTP requests is anticipated. Testing (by InterSystems) of the PWS only covers the use of this server for managing InterSystems IRIS. However many developers find it useful to use the PWS for testing their own CSP and Zen applications.
To access the Management Portal, enter the following URL, which resolves to the port number on your private web server for the current InterSystems IRIS instance:
If you are using a web server other than the PWS to manage an instance of InterSystems IRIS, you must configure the web server so that links to the documentation continue to work. To do this, configure the web server so that it includes a redirection from /csp/docbook/ to the correct URL for the documentation. You can find this information in the file install_dir/httpd/conf/httpd-doc.conf, which Apache uses to redirect /csp/docbook/. For information on creating a redirection, consult the documentation for the web server that you are using.
When installing InterSystems IRIS, this private version of Apache is installed to ensure that:
The Management Portal runs out of the box.
An out-of-the-box testing capability is provided for development environments.
The PWS is not supported for any other purpose.
For deployments of http-based applications, including REST, CSP, Zen, and SOAP over http or https, you should not use the private web server for any application other than the Management Portal; instead, you must install and deploy one of the supported web servers. For information, see the section “Supported Web Servers” in the online InterSystems Supported Platforms document for this release.
The PWS is responsible for supporting the Management Portal for InterSystems IRIS. However, customers are not required to use this web server to manage InterSystems products: customers may run the Management Portal through a web server of their own choosing.
Finally, the PWS is self contained and configured to listen on a TCP port other than the usual, well known, HTTP server port of 80. It does not interfere with any other web server installation operating on the same host.
The PWS is available for UNIX, Linux, macOS and Windows. See the section “Building the Private Web Server” for more information.
The entry point for the Management Portal is normally via the following CSP path and file: /csp/sys/UtilHome.csp. For example: http://127.0.0.1:8972/csp/sys/UtilHome.csp
Building the Private Web Server
The (default) full Apache server is usually created with the following sequence of commands:
./configure --prefix=<install-dir> make make install
The minimal Apache build is typically created as follows:
./configure --prefix=/usr/iris/httpd --with-port=57773 --with-pcre=$srcdir/pcre --enable-mods-static="log_config mime alias unixd authz_core" --disable-ssl --enable-so --without-gdbm --without-ndbm --without-berkeley-db --with-included-apr --with-expat=builtin --with-mpm=prefork --disable-shared make make install
Notice that many of the services that are normally required for a production grade installation are excluded.
While this server can be used to host other web applications it is strongly recommended that a full, independent web server installation is used for this purpose. It should be remembered that any changes made to the configuration of the Management Portal Apache installation are overwritten when the hosting InterSystems IRIS installation is upgraded.
The Management Portal Apache installation uses the following Web Gateway modules for communicating with InterSystems IRIS:
Windows: CSPa24.dll and CSPa24Sys.dll
UNIX: CSPa24.so and CSPa24Sys.so
Managing the Private Web Server
The configuration file for the PWS is located at: install_dir/httpd/conf/httpd.conf. However, edits made to this file do not persist through a software upgrade. The configuration file install_dir/httpd/conf/httpd-local.conf is provided for configuration changes you want to retain on upgrade. It is created on a new install or on upgrade if it does not already exist. If it does exist, upgrade makes no changes to its content.
Under normal operational conditions, the Management Portal Web Server for a particular instance of InterSystems IRIS is started when InterSystems IRIS is started and closed down when InterSystems IRIS is closed down. Occasionally it may be necessary to restart the Management Portal Web Server without disrupting the corresponding InterSystems IRIS server. For example, a web server restart is necessary if a configuration change is made to the web server (httpd.conf).
Use the following commands to start and stop the Management Portal Web Server.
Start the Management Portal Web Server:
<install-dir>\httpd\bin\httpd -k start -n <instname>httpd -c "Listen port"
Stop the Management Portal Web Server:
<install-dir>\httpd\bin\httpd -k stop -n <instname>httpd
InterSystems IRIS installed in: C:\iris
InterSystems IRIS instance name: IRIS
TCP port for Apache: 57773
C:\iris\httpd\bin\httpd -k start -n IRIShttpd -c "Listen 57773"
C:\iris\httpd\bin\httpd -k stop -n IRIShttpd
Start the Management Portal Web Server:
<install-dir>/httpd/bin/httpd -d <install-dir>/httpd -c "Listen port"
Stop the Management Portal Web Server:
kill `cat <install-dir>/httpd/logs/httpd.pid`
InterSystems IRIS installed in: /usr/iris
TCP port for Apache: 8972
/usr/iris/httpd/bin/httpd -d /usr/iris/httpd -c "Listen 8972"
kill `cat /usr/iris/httpd/logs/httpd.pid`
On AIX, LD_LIBRARY_PATH must include the install-dir/bin directory in order to manually run httpd in this way.
Limitations of the Private Web Server
This section discusses the differences between the configuration of the PWS and that of a typical production grade Apache installation.
Windows-based Apache installations use a special multi-threaded form of the Apache Multi-Processing Module (MPM) which is better suited to the way the operating system is optimized. Therefore, the behavior of the PWS under Windows is similar to that of a production grade Apache build as far as the ability to handle concurrent load is concerned.
If high availability and production-grade security is a requirement, or there is a need to integrate with other sources of web information, or a need for a high degree of control over the web server, a separate production-grade build of Apache is recommended - ideally operating on its own server. If, on the other hand, low volumes of HTTP traffic are expected, and there are limited demands for high availability and security, then the PWS may be suitable for deployment under these circumstances.
The PWS defaults to using the Apache Group’s prefork Multi-Processing Module (MPM). This is a non-threaded server model: the number of requests that can be concurrently served is directly related to the number of Apache worker processes in the pool.
The PWS is configured to occupy the smallest possible footprint by allowing a maximum of two worker processes to be created for the pool. The following settings are found in the Apache configuration (httpd.conf) for the PWS:
MinSpareServers 1 MaxSpareServers 2
By contrast, the default Apache configuration for a production grade build is usually as follows:
StartServers 5 MinSpareServers 2 MaxSpareServers 20 ServerLimit 256 MaxRequestWorkers 256
This configuration allows Apache to create 5 worker processes at start-up, increasing to a maximum of 256 as the concurrent load increases. Because of these differences in configuration, the performance of the PWS is noticeably inferior to that of a production grade Apache build. This performance deficit becomes more noticeable as the concurrent load increases. However, it is possible to change the configuration of the PWS to match that of a full Apache installation (shown above). Apache must be completely restarted after changing these parameters.