Web Access Using the Web Gateway Container
The InterSystems IRIS Web Gateway provides the communications layer between a hosting web server and InterSystems IRIS for any web application, passing HTTP/HTTPS requests to InterSystems IRIS and returning the responses to be passed to the request originators. The webgateway image available from InterSystems includes both the Web Gateway and a web server, providing a containerized web server component for stand-alone InterSystems IRIS containers and containerized InterSystems IRIS clusters.
Each InterSystems IRIS instance served by a Web Gateway is identified by a server access profileOpens in a new tab configured on the Web Gateway; each application to which the Web Gateway sends requests is identified by an application access profileOpens in a new tab, which is associated with an application pathOpens in a new tab (such as /applications/appa) configured on the web server. The application access profile determines whether requests for the associated application go to a specific InterSystems IRIS instance only, fail over to another instance if the first is not available, or are load balanced across multiple instances.
Requests for the Management Portal and other built-in InterSystems IRIS applications, however, always involve the same application path but are intended for a specific InterSystems IRIS instance. For this reason, a different mechanism must be used to route them to the desired instance. For example, if you deploy a containerized distributed cache cluster with a web server tier consisting of Web Gateway containers, each Web Gateway can be configured to load balance application connections across all of the InterSystems IRIS containers serving as application servers, or across a specific subset, but any of the Web Gateway instances must be able to send a Management Portal request to the intended instance.
There are two basic approaches to routing Management Portal and other built-in application requests to specific InterSystems IRIS instances, as follow:
-
One-to-many: A single Web Gateway container to distribute both application connections and Management Portal requests to multiple InterSystems IRIS containers.
This approach uses the instance prefix/CSPConfigName mechanism (described in Structure of an InterSystems Web Application URLOpens in a new tab) to route requests for the Management Portal and other built-in applications to the desired instance while distributing application connections based on the application path. For example, in the following illustration, a single Web Gateway container, wg1, routes requests for /applications/appa to InterSystems IRIS container irisa and for /applications/appb to container irisb based on their application paths, while routing Management Portal requests prefixed by /irisa to irisa and those prefixed by /irisb to irisb — the instances in those container having had their CSPConfigName properties set to irisa and irisb, respectively — even though the application path, /csp/sys, is the same.
A single Web Gateway container directs application connections and Management Portal requests to multiple InterSystems IRIS containers
-
Many-to-many: One or more Web Gateway containers to distribute application connections to multiple InterSystems IRIS containers and a dedicated Web Gateway container for each InterSystems IRIS container to handle Management Portal requests.
In this approach, one or more Web Gateway containers serving as web server nodes distribute application connections as desired, while Management Portal and other built-in application requests for each InterSystems IRIS instance are handled by a Web Gateway container dedicated to that instance. For example, the following illustration shows one Web Gateway container directing application connections as in the previous illustration, while InterSystems IRIS containers irisa and irisb each have a dedicated Web Gateway container directing Management Portal requests to them; the Management Portal URLs are distinguished by the dedicated Web Gateways’ published port numbers (rather than URL prefixes based on CSPConfigName values, as in the first approach).
An application Web Gateway container for application requests and dedicated Web Gateway containers for Management Portal requests
Important advantages of the many-to-many approach include:
-
Separation of responsibilities.
-
Optional customization of permissions and security for different use cases.
-
Distribution of Management Portal requests using Docker hostnames assigned to the InterSystems IRIS instances in deployment. This avoids the step of setting each InterSystems IRIS instance’s CSPConfigName property (as described above) to a value unique within the configuration, which must be done following deployment, after the instance has started inside the container.
The primary advantage of the one-to-many approach is that it is simpler and requires fewer containers, consuming fewer resources and ports.
A compromise solution might be a two-to-many approach, in which one Web Gateway container serves Management Portal requests as in one-to-many, and another Web Gateway distributes application connections across the InterSystems IRIS instances.
You can find examples of both approaches, including all the needed files and some useful scripts, at https://github.com/intersystems-community/webgateway-examplesOpens in a new tab.
The Web Gateway approach you take depends on the containerized configuration involved, the expected amount of application traffic, the needs of your organization, and other factors. Generally speaking, the one-to-many approach works well for less complex configurations and smaller organizations seeking simplicity and a minimal footprint. For larger enterprises and more complex configurations with a focus on stability, resiliency, and availability and a need to separate instance-local connections from the primary application traffic, the many-to-many approach may be preferable. As noted above, there are also various possible combinations; for example, when using the one-to-many approach, you may want to include a dedicated Web Gateway for a particular InterSystems IRIS instance that handles heavy traffic at peak to avoid increasing latency for the others.
When Web Gateway nodes are used in a web server tier distributing application connections across multiple instances, the manner of distribution can depend on the configuration. For example:
-
The general best practice for sharded clustersOpens in a new tab is to distribute application connections equally across all data nodes (and compute nodes if present) in the cluster, so in this case you would configure the application profile(s) to distribute all application connections equally across all of the data node containers defined in the server profiles. Because Management Portal connections to a sharded cluster are typically made only to node 1, however, these can easily be routed by the web server tier without the need for any additional Web Gateway nodes.
-
In a distributed cache clusterOpens in a new tab, on the other hand, you might want to maximize caching efficiency by directing requests for different applications to different application serversOpens in a new tab; in such a case, the application paths would be configured to distribute connections differentially. When this is done and large web server and application server tiers are involved, the use of dedicated Web Gateways may be optimal. This is shown in the following simplified illustration, in which the InterSystems IRIS containers (two application servers and one data server) each has a dedicated Web Gateway container to handle Management Portal and other built-in application requests received over networks separate from the one conveying application requests to the load balancer.
Containerized distributed cache cluster with application connections directed differentially and dedicated Web Gateways
Important:
In versions of InterSystems IRIS prior to 2023.2, the Web Gateway and a preconfigured private web server were installed with InterSystems IRIS by default, including in containers. For this reason, if you are upgrading from a pre-2023.2 version to the current version, you must update all deployment scripts and tools to reflect the new deployment options described by this document. Further, 2023.2 and later InterSystems IRIS containers should be used only with InterSytems Kubernetes Operator 3.6 and later.
For the convenience of those testing and evaluating InterSystems IRIS, the InterSystems IRIS Community EditionOpens in a new tab image continues to include the Web Gateway and preconfigured web server; the web server can be reached (to access the Management Portal, for example) at whatever host port is published for the containerized instance’s web server port, 52773.
InterSystems Web Gateway Images
There are three types of webgateway images available from InterSystems, each of which provides a web server component for containerized deployments:
-
The webgateway image contains the following components, installed by root in the indicated locations within the container:
-
The webgateway-nginx image contains the following components, installed by root:
-
The webgateway-lockeddown image, designed to meet the strictest security requirements, contains the following nonroot components installed, owned, and run by irisowner (UID 51773) :
-
An InterSystems Web Gateway installed in /home/irisowner/webgateway with locked-down security.
-
An Apache web server installed in /home/irisowner/apache and configured to use port 52773 instead of the standard port 80.
Configuring the Web Gateway
The Web Gateway is configured using the Web Gateway management pagesOpens in a new tab, but the configuration is contained in the CSP.ini file (much as an InterSystems IRIS instance’s configuration is contained in the iris.cpf fileOpens in a new tab). The Web Gateway is installed with a minimal default version of the CSP.ini file containing some basic settings. In Web Gateway containers only, the CSP.conf file, which configures the web server to interact with the Web Gateway, is added to the web server’s configuration. For more information about the contents of the CSP.ini file, see Web Gateway Configuration File (CSP.ini) Parameter ReferenceOpens in a new tab; for information about the contents of the CSP.conf files provided in Web Gateway containers, see Recommended Option: Apache API Module without NSD and Using the NSD with NginxOpens in a new tab.
All three webgateway images contain minimal default versions of both the CSP.ini file and an Apache or Nginx-specific CSP.conf file (in the appropriate directory as indicated in the preceding list). However, you can provide your own version of one or both files to overwrite these. There are multiple ways to prepare your initial version of the CSP.ini file. For example, you might modify a file from an existing or previous Web Gateway deployment and use that for one or more Web Gateway containers, or perhaps start in one container with either your own file or the basic default version provided, use the management pages to modify the configuration as needed, then copy the updated file and use it with additional containers. The Web Gateway GuideOpens in a new tab provides comprehensive information on Web Gateway configuration.
A Web Gateway container can optionally be run with a version of the durable %SYS feature, which creates a durable data directory called webgateway within the container in which the Web Gateway’s configuration is stored (see Options for Running Web Gateway Containers). If you use this option, the CSP.ini and CSP.conf files (default or user-provided) are copied to that directory, as is the CSP.log log file; this enables you to upgrade the container without losing the existing configuration, and to simultaneously update multiple Web Gateway configurations, as described in the following section.
Synchronized Reconfiguration of Multiple Web Gateway Containers
In the case of a dedicated Web Gateway container, the Web Gateway’s configuration is relatively simple, including as it does a single server access profileOpens in a new tab for the InterSystems IRIS instance it is dedicated to and application access profilesOpens in a new tab for only the applications that instance is serving. Therefore reconfiguring a dedicated Web Gateway can be as simple as accessing its management pagesOpens in a new tab and making the needed changes.
However, when you deploy multiple Web Gateway containers as part of the same cluster, as in a web server tier and for shared Management Portal access, you will likely need a method for simultaneously updating their configurations, in particular their server access profiles and application access profiles, for example when you add an InterSystems IRIS node or change an application path. The CSP.ini merge feature provides a convenient means of doing this. If you provide your own CSP.ini file at container creation, staged on a mounted external volume as described in Options for Running Web Gateway Containers, it is copied once to either the container’s file system or the durable data directory if it exists. Following that, if the staged file remains in its original location and accessible to the Web Gateway containers, updates to the file are automatically merged to each Web Gateway instance’s active CSP.ini file (in either location), along with the setting [SYSTEM]/RELOAD=1Opens in a new tab, which causes the configuration to be reloaded by the Web Gateway within a minute. Therefore, if you deploy multiple Web Gateway containers by mounting the same staged CSP.ini file on the same external volume for all of them, you can reconfigure them all identically and simultaneously by updating the staged file. This approach works equally well for reconfiguring a dedicated Web Gateway, a single Web Gateway distributing application connections to multiple InterSystems IRIS containers, or a shared Web Gateway for management portal access.
When using this merge update approach, whatever the number of Web Gateway containers involved, it is important to takes steps to avoid changing the instances’ CSP.ini files by other means (such as through the Web Gateway management pages) or, if you do make such changes, do one of the following:
-
Remove fields from the staged CSP.ini file that you have changed by other means, possibly by deleting everything other than the fields you want to update.
-
Apply updates you have made by other means to the staged file. For example, you might change the file using the management pages, then copy the modified file to the staging location, overwriting the original staged file. If you are using the staged file for multiple containers, this would allow you to test the changes you want to make on one instance and then apply them to the rest through a merge update.
Note:
The staged CSP.ini file is never merged unless it has been modified. When the durable data directory is in use, a copy of the last merged file is kept in /webgateway/CSP.ini.last_merge in the durable %SYS directory.
Externally staging your own CSP.conf file allows you to keep the web servers in multiple Web Gateway contains updated in the same fashion as described for CSP.ini, above. As long as the file remains in its original staged location and accessible to the Web Gateway containers, it is monitored by each Web Gateway container for changes, and when these are detected it is recopied to the appropriate directory and the web server reloads the configuration and restarts. This is especially helpful when you update the Web Gateway server access profilesOpens in a new tab in the staged CSP.ini and need to update the application pathsOpens in a new tab configured on the web servers accordingly.
Web Gateway Container Security
Securing a Web Gateway instance involves two primary tasks:
In the default CSP.ini in the Web Gateway container (and by default in locally installed Web Gateways), the CSPSystem predefined user accountOpens in a new tab is used for both purposes. You can, however, use any credentials you want for either purpose. When securing connections to InterSystems IRIS instances, the credentials you configure in each server access profile must be valid on that particular instance; otherwise there are no restrictions on either set of credentials, and using a purpose-made account rather than CSPSystem allows you to more closely restrict information about the credentials.
When deploying a clustered configuration involving multiple Web Gateways interacting with multiple InterSystems IRIS instances, as discussed in Synchronized Reconfiguration of Multiple Web Gateway Containers, using one set of credentials for all connections to InterSystems IRIS and another set for management access to all Web Gateways is more convenient (although using different sets enhances security by reducing credentials reuse). A reasonably convenient and (if other precautions are followed) reasonably secure approach to implementing this is as follows:
-
Deploy the InterSystems IRIS containers using configuration merge [Actions] parameters (as described in Create, Modify and Delete Security ObjectsOpens in a new tab in Automating Configuration of InterSystems IRIS with Configuration Merge) to create an account specifically for Web Gateway authentication, with the password encrypted using the PasswordHash parameter). Stage the merge file on a mounted external volume, as required for continuous monitoring and merging.
-
Deploy the Web Gateway containers with a custom CSP.ini file that specifies:
-
In the server access profiles, the Web Gateway access credentials created during InterSystems IRIS deployment.
-
A different set of credentials for management pages access.
-
A restricted set of IP addresses from which the management pages can be accessed.
Stage the CSP.ini file on a mounted external volumes, as required for continuous monitoring and merging.
Continuous monitoring and merging of the CPF merge and CSP.ini files enables you to use the CSP.ini merge feature for later synchronized reconfiguration of the Web Gateway containers, including the security best practice of regular password changes for both the server access credentials (in both the InterSystems IRIS containers and Web Gateway containers) and the Web Gateway management credentials, or even regularly creating a new account on the InterSystems IRIS instances and updating the CSP.ini accordingly.
Important:
When deploying one or more Web Gateway containers with a custom CSP.ini file, three passwords in the file should always be encrypted before deployment:
The Web Gateway management access password, [SYSTEM]/Password, must be encrypted before you enter it into the CSP.ini file. For the two passwords in each server access profile, you have two options, as follows:
-
Deploy a Web Gateway container with the CSP.ini you want to use.
-
For [<server>]/Password, [<server>]/SSLCC_Private_Key_Password, or both, enter one of the following:
-
A plain text password. When the Web Gateway starts up, or when it is reloaded while running by the addition of the setting [SYSTEM]/RELOAD=1Opens in a new tab to the CSP.ini file, the password is automatically encrypted. (When using scripts and other automated methods, you can use the CSPpwd utilityOpens in a new tab to encrypt all plain text passwords in a CSP.ini file, but note the restrictions on password decryptionOpens in a new tab on Windows platforms.)
-
On UNIX® and Linux systems, a command enclosed in braces, for example Password={sh /tmp/PWretrieve.sh}. When the Web Gateway starts up or is reloaded, the command is executed and the result is stored in memory only as the value of the field. This allows you to retrieve passwords from sources such as cloud platform or third-party secret managers without ever committing them in plain text to durable storage.
As described in Authentication and Passwords, you must change the default password for the predefined accountsOpens in a new tab, including CSPSystem, on any InterSystems IRIS instance as part of deployment or immediately after. If you do choose to make use of CSPSystem or one of the other predefined accounts in your CSP.ini file, be sure to provide yourself with secure access to the encrypted post-deployment password so that you can accurately add it to the CSP.ini file.
