Installing the Web Gateway

Default Web Gateway Installation and Configuration

When you install InterSystems IRIS and choose a setup typeOpens in a new tab of Development, Server, Custom (selecting the Web Server Gateway component), or Web Server (Windows platforms only), the installer configures your existing production web servers (if the default types: IIS on Windows and Apache on Linux/UNIX®/macOS) and then installs 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 a 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.

In addition to the InterSystems file types (.csp, .cls, .zen, and .cxw), a web server hosting the Management Portal must also route requests for the following additional file types through the Web Gateway: .jpg, .gif, .png, .svg, .css, and .js. See Configuring Apache to Pass Additional File Types to CSP (for Apache) or Using the NSD with Nginx (for Nginx).

Web Gateway Management Modules

Web Gateway architectures that work directly with a hosting web server’s API typically consist of two modules (whose filenames vary by operating system):

• A management module (for example, CSPmsSys.dll), which provides the Web Gateway management pages.

• The runtime module (for example, CSPms.dll), which is responsible for processing requests for CSP files and for loading and routing management requests to the management module.

These files must be in the same directory.

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. 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 because 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 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.

1. 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)
   

   

   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. 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.

2. Executables to be called by the web server (Common Gateway Interface (CGI) modules). Not all configurations require these executables.

   [nph-]CSPcgi[Sys][.exe]
   

   

   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.

3. 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 page does not apply to such configurations.

   JavaScript modules (such as CSPBroker.js, CSPxmlhttp.js, and so on)

   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.

4. The CSP network service daemon (NSD).

   Note:

   Not all configurations require this facility.

   CSPnsd[Sv][.exe]
   

   

   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, 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.

5. The Web Gateway cache, kept in persistent storage.

   The Web Gateway, where possible, locates the content of large files (such as large JavaScript files) together with the accompanying HTTP response headers in permanent storage. The essential control information (expiry time and so on) and the index of all cached files is in the shared memory sector. With this architecture, each cache entry consumes a small amount of cache space (in terms of memory usage) — quite possibly no more than one cache block per entry.

   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 IIS installation, this is in: C:\Inetpub\CSPGateway\temp. The location needs full read/write/delete permissions for the hosting web server worker processes.

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 TypeOpens in a new tab 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. To get the installer, use the following WRC download page: https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab. To show only the Web Gateway kits, type web gateway in the Name column.

  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 or Nginx 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 ContainerOpens in a new tab in Running InterSystems Products in Containers, Role WS: Web ServerOpens in a new tab in the InterSystems Cloud Manager Guide, and webgateway: Define web server nodes in Using the InterSystems Kubernetes Operator.

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 Using Web Applications with a Remote Web Server.