Using the InterSystems Web Gateway Container

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 of InterSystems IRIS-based applications:

• The webgateway image contains the following components, installed by root in the indicated locations within the container:

  • An InterSystems Web Gateway in /opt/webgateway.

  • An Apache web server in /etc/apache2.

• The webgateway-nginx image contains the following components, installed by root:

  • An InterSystems Web Gateway in /opt/webgateway.

  • An Nginx web server in /opt/nginx.

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

  Note:

  For details about nonroot installation and locked-down security, see Security for InterSystems IRIS Containers.

Configuring the Web Gateway

As described in Configuring the Default Parameters for the Web GatewayOpens in a new tab in the Web Gateway Guide, the Web Gateway is configured using the Web Gateway management pages, but the configuration is contained in the CSP.ini file (much as an InterSystems IRIS instance’s configuration is contained in the iris.cpf file). As installed, the Web Gateway is configured to communicate with the local InterSystems IRIS instance.

For testing purposes, all three webgateway images contain basic versions of the CSP.ini file (which contains the Web Gateway configuration) and the CSP.conf file (which contains the Web Gateway’s Apache or Nginx-specific configuration), in the directories indicated in the preceding list. However, you can provide your own version of one or both files to overwrite these.

All three types of 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, enabling you to upgrade the container without losing the existing configurations. If you use this feature, the CSP.ini and CSP.conf files (default or user-provided) are copied to that directory, as is the CSP.log log file.

There are multiple ways to prepare your initial version of the configuration 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.

Synchronized Reconfiguration of Multiple Web Gateway Containers

When you deploy multiple Web Gateway containers as part of the same cluster (as in a web server tier), you will likely need a method for simultaneously updating their configurations, especially their server access configurations. 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 to the durable %SYS directory if the latter exists. If the staged file remains in its original location, however, updates to the file are automatically merged to the 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.

When using this merge update approach, whether for a single Web Gateway container or multiple containers, 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 make the changes you want on one instance and then apply them to the rest through a merge update.

Web Gateway Security

The predefined CSPSystem account on an InterSystems IRIS instance is used for communication between an InterSystems IRIS instance and the local InterSystems Web Gateway instance installed with it, and by default is used for access to the local Web Gateway’s configuration through its management pages. For effective security, you must change the default password for this account (along with the other predefined accounts) on both an InterSystems IRIS instance and its local Web Gateway instance either as part of deployment or immediately after; Authentication and Passwords provides details on this topic and instructions for making these changes in an InterSystems IRIS container. In the case of a Web Gateway container, you must independently secure management access; the steps required to do this differ depending on whether you are using the provided basic CSP.ini configuration file or replacing it with your own, as follows:

• The default CSP.ini file provided in the container does not require authentication for management access, which is not secure. If you start with this file and plan to modify the basic Web Gateway configuration it provides through the management pages, do the following immediately after deployment::

  1. In your browser, load the Web Gateway’s management pages URL, which is http://container-host:host-port/csp/bin/Systems/Module.cxw, where host-port is the host port that was published for container port 80 when the container was created.

  2. Select Default Parameters in the menu on the left and, in the Security section of the page, enter a username and password. Once you save your changes, those credentials will be required for access to the management pages following the end of your current session.

• If you provide your own CSP.ini file, as described earlier in this section:

  1. Prior to deployment, verify that the password specified for the management access account, if any, is encrypted, not in plain text, so that the password is not vulnerable on disk or on the network.

  2. Immediately after deployment, access the Security section of the Web Gateway’s management pages, as described in the previous item, and verify that if CSPSystem (or any other predefined accountOpens in a new tab) is specified as the management access account, the password is not SYS; if it is, change it. You can also change the access credentials to any username and password you choose.

When securing connections between a containerized Web Gateway and InterSystems IRIS instances with TLS (as described in Configuring Server AccessOpens in a new tab and “Overriding the Library Path If You Use SSL/TLSOpens in a new tab” in the Web Gateway Guide and Configuring the Web Gateway to Connect to InterSystems IRIS Using TLSOpens in a new tab in the TLS Guide) or using SSL mode to secure the Apache web server, the best practice for providing a certificate is to generate a passwordless server key and mount both the key and the certificate as Docker secretsOpens in a new tab (or Kubernetes secretsOpens in a new tab if applicable). When you need to update the certificate, you can simply update the secrets. This practice avoids having to manually provide a server key password, which compromises resiliency, or recording the password so it can be automatically retrieved, which compromises security.

Options for Running Web Gateway Containers

The only required option when creating and starting a webgateway container is publishing container ports 80 (or 52773 if webgateway-lockeddown) and 443 to host ports so that other entities can contact the Web Gateway and the web server, as in the following commands:

docker run -d --publish 80:80 --publish 443:443 
  containers.intersystems.com/intersystems/webgateway:2023.1.0.299.0

docker run -d --publish 52773:52773 --publish 443:443 
  containers.intersystems.com/intersystems/webgateway-lockeddown:2023.1.0.299.0

The following additional options are optional:

• Durable data directory — To create a durable data directory called webgateway within the container, in which the Web Gateway’s configuration is stored, use the --volume option to mount a persistent data volume and the ISC_DATA_DIRECTORY environment variable to specify a location on it for the directory. For example, the following command would create a durable data directory at /dur/webgateway inside the container and /nethome/rrodriguez/dur/webgateway on the host’s file system.

  docker run -d --name wg11 --publish 80:80 --publish 443:443
    --volume /nethome/rrodriguez/dur:/dur --env ISC_DATA_DIRECTORY=/dur 
     containers.intersystems.com/intersystems/webgateway:2023.1.0.299.0
  

  

  This is equivalent to the procedure for enabling the durable %SYS feature for InterSystems IRIS containers; for detailed information about using these options and durable %SYS generally, see Durable %SYS for Persistent Instance Data.

  Important:

  Because the webgateway-lockeddown image contains a Web Gateway instance and web server installed and owned by user irisowner (UID 51773), the host file system location you specify for the durable data directory of a locked down container must be writable by irisowner. (You will most likely need root privileges to effect this.)

  When you run a webgateway container with the durable data options, the following occurs:

  • The specified external volume is mounted.

  • If the webgateway directory does not exist in the location specified by ISC_DATA_DIRECTORY, it is created and the configuration files are copied there for use by the Web Gateway, as follows:

    • Configuration files you provide are copied to the webgateway directory, with links to their default locations in the container.

    • Configuration files you do not provide are copied from the default locations within the container, with links to those locations.

  • If the webgateway directory already exists in the location specified by ISC_DATA_DIRECTORY, it is assumed to be the data directory for a previous webgateway container, and

    • If it contains the expected Web Gateway configuration files, these are linked to their locations in the container and are used by the Web Gateway; options specifying user-provided configuration files (as described below) are ignored.

      Important:

      Because you cannot provide your own configuration files (as described below) when deploying a webgateway container using an existing durable webgateway directory, you cannot upgrade and reconfigure a containerized Web Gateway in the same operation. Instead, start by deploying a new version of the container using the previous container’s durable webgateway directory, then reconfigure the Web Gateway as needed.

    • If one or more of the expected Web Gateway configuration files are not present, the webgateway is assumed to be corrupted; an error is logged and the container fails to start.

    Important:

    When upgrading a webgateway container that uses a durable data directory to version 2021.2 or later using a webgateway-lockeddown image, you must make the existing durable directory writable by user irisowner.

  The default, if you do not use the ISC_DATA_DIRECTORY variable to specify a location on writeable persistent storage accessible to the Web Gateway within the container, is to not create a durable data directory and maintain the configuration files in their default locations (as previously described).

• User-defined configuration files — To provide your own CSP.ini file, use the --volume option to mount a persistent data volume (Separate from the durable %SYS volume, if in use), stage the file on that volume, and use the ISC_CSP_INI_FILE environment variable to indicate its location. If you also create a durable webgateway directory, as described in the preceding, the file is copied to that directory and linked to its original location within the container; if not, it is copied to the original location, overwriting the default file.

  Important:

  If you want to use the merge update approach, as described in Configuring the Web Gateway, the staged CSP.ini file must remain in place and accessible to the container.

  To supply your own CSP.conf file, do the same and use the ISC_CSP_CONF_FILE environment variable to specify its location. For example, to create a durable webgateway directory and provide your own CSP.ini and CSP.conf files to be used for the Web Gateway’s configuration, you would use a command like the following:

  docker run -d --name wg11 --publish 80:80 --publish 443:443
    --volume /nethome/rrodriguez/dur:/dur --env ISC_DATA_DIRECTORY=/dur 
    --volume /nethome/rrodriguez/config:/config --env ISC_CSP_INI_FILE=/config/CSP.ini 
    --env ISC_CSP_CONF_FILE=/config/CSP.conf 
    containers.intersystems.com/intersystems/webgateway:2023.1.0.299.0
  

  

  The default, if one of these variable is not specified, is to use the basic default file located within the container.

• To enable the Apache web server’s SSL module, add the --ssl entrypoint option (following the image specification). The default, if the option is omitted, is not to enable the Apache SSL module.

• To identify the Web Gateway’s server to Apache, use the --server server-name entrypoint option. The default, if the option is omitted, is to use the container’s ID (unless the Docker --hostname option is included, in which case the value provided is used).

The following is an example of a docker run command using all the options described:

docker run -d --name wg11 --publish 80:80 
  --volume /nethome/rrodriguez/dur:/dur --env ISC_DATA_DIRECTORY=/dur 
  --env ISC_CSP_INI_FILE=/dur/CSP.ini --env ISC_CSP_CONF_FILE=/dur/CSP.conf 
  containers.intersystems.com/intersystems/webgateway:2023.1.0.299.0
  --ssl --server webgateway11