Skip to main content

Extend Your Web Server Configuration with the Web Gateway

After you install the files for the InterSystems Web Gateway, you must add the Web Gateway to your web server configuration as an extension. Once you have done so, your web server can invoke the Web Gateway to handle requests which are intended for your InterSystems IRIS® web applications.

This page describes the recommended way to add the Web Gateway extension to a web server configuration for each supported web server. For each web server, it also summarizes the method InterSystems has implemented for specifying which requests should be routed through the Web Gateway. (Refer to Choose Which URL Paths Route Requests Through the Web Gateway as you consider how you should route application requests.)

In many cases, the installer can perform the configuration steps on this page automatically for Apache (on UNIX®/Linux/macOS) or IIS (on Windows). You can then simply customize the resulting configuration to suit the needs of your own system.

Once you have configured the web server, use the Web Gateway management pages to connect your InterSystems IRIS instances and associate application paths with them.

Files to Consider

Web Gateway Files

The Web Gateway files are installed in one of the following locations:

  • /opt/webgateway/bin on UNIX®/Linux/macOS. InterSystems recommends using Web Gateway files in this common location instead of within an InterSystems IRIS installation directory, because they will not be affected by modifications to an InterSystems IRIS installation.

  • C:\Inetpub\ on Windows when Internet Information Services (IIS) is configured. InterSystems recommends using Web Gateway files in this common location instead of within an InterSystems IRIS installation directory, because they will not be affected by modifications to an InterSystems IRIS installation.

  • <installDir>/csp/bin or <installDir>/bin when:

    • You have installed an InterSystems IRIS instance in <installDir>

    • The web server is not configured.

  • <installDir> or <installDir>/bin:

    • You have installed a stand-alone Web Gateway in <installDir>

    • The web server is not configured.

In general, InterSystems implements the Web Gateway as a pair of binary files: one file implements the runtime functionality and the other implements the Web Gateway management pages. The management binary is distinguished from the runtime binary by the addition of Sys to the end of the filename.

Web Server Files

The installation location of a web server varies depending on the web server and the operating system; see your web server documentation for help finding where your web server is installed.

Note:

The Web Gateway documentation sometimes specifies a web server installation location—usually the default—in its examples, for maximum clarity. This location may not match its location on your system; substitute the location of the file on your system instead.

Static Files

An InterSystems IRIS instance can serve static files as part of its web application responses, provided that you configure the web server to allow the Web Gateway to handle requests which are sent to the application’s relative URL path for all the required file types.

The static files which an InterSystems IRIS CSP web application serves are located in the <installDir>/csp/ directory which corresponds with the web application, where <installDir> is the installation directory for the InterSystems IRIS instance.

For example:

  • <installDir>/csp/broker contains files shared by several built-in system applications.

  • <installDir>/csp/sys contains files used by the Management Portal

By default, an InterSystems IRIS CSP web application is configured to serve static files itself, from its associated directory.

However, the web application can allow the web server to serve these static files instead. For example, if you have a system where a single web server serves multiple remote InterSystems IRIS instances, it may be expedient to serve these files from a common location local to the web server machine. Note, however, that this may cause problems: for example, if the common web server serves different versions of InterSystems IRIS, the web server may encounter a conflict between two different versions of the same file.

To configure your web server to serve and cache static files for an InterSystems IRIS web application, you must create a mapping between the path for an application (to which requests for the application’s static files are directed) and a local file system location that the web server has adequate permission to access, where the static files are stored.

Here and elsewhere, the Web Gateway documentation describes ways of creating this optional mapping for each web server. For further instructions on how to configure your web server to serve static files from a local file system location it manages itself, refer to your web server’s documentation.

Apache for UNIX®/Linux/macOS

The Apache HTTP web server is supplied by the Apache Group and can be downloaded free of charge from http://www.apache.orgOpens in a new tab. Many systems are shipped with Apache preinstalled, configured and ready to go. For guidance installing Apache on a supported UNIX® or Linux system, refer to this Developer Community article: https://community.intersystems.com/post/how-install-apache-iris-supported-operating-systemsOpens in a new tab.

Note:

On macOS, the InterSystems IRIS installer cannot automatically configure the preinstalled version of Apache. However, it can automatically configure the version of Apache installed using Homebrew (https://formulae.brew.sh/formula/httpd#defaultOpens in a new tab).

This page describes how to deploy the Web Gateway in Apache with the dynamic module csp_module_sa, which InterSystems implements using Apache’s native API.

The csp_module_sa module implements the Web Gateway using two dynamic shared object (.so) files:

  • CSPa24.so — the runtime binary.

  • CSPa24Sys.so — the Web Gateway management binary.

This is the recommended deployment option for Apache; it is effective for the vast majority of use cases.

Note:

State-aware connectivity (preserve mode 1) should not be used with this module.

If you are configuring the Web Gateway on a system which uses a security-restricted version of Apache (such as RHEL with SELinux), see Add the Web Gateway to a Locked-Down Apache Installation for supplementary instructions. Alternative Options for Apache describes other options for deploying the Web Gateway with Apache, including options which use the Network Service Daemon (NSD).

Apache Considerations provides some guidance for administering an Apache web server connected to a Web Gateway. For detailed guidance, consult the Apache documentation (https://httpd.apache.org/docs/Opens in a new tab).

Verify That Apache Can Manage Shared Object Modules

Before you attempt to add the Web Gateway to your Apache configuration using Apache’s proprietary API, check that your build of Apache includes the built-in module for managing shared objects: mod_so.

To perform this check on Red Hat Linux, issue the following command from the command line (select the command appropriate for your operating system):

httpd -l
apache2 -l

This command displays the list of modules included in your current Apache installation. If mod_so is not included in this list, follow the instructions provided within the Apache documentation (https://httpd.apache.org/docs/2.4/Opens in a new tab) to compile a new build of Apache that includes this module.

Add the Web Gateway Modules to Your Web Server Configuration

  1. Note the file system location of the Web Gateway module files. These instructions use the most common location, /opt/webgateway/bin.

  2. Open the Apache web server configuration file (httpd.conf) in a text editor. This file is located in your Apache installation directory, within the /conf subdirectory. The most common installation locations are:

    /etc/httpd/conf
    
    /usr/apache2/conf
    
  3. Append directives to the end of the file which add the Web Gateway module. These directives should accomplish the following:

    • Load the module using the LoadModule directive, providing the name of the module and the location of the .so file for the Web Gateway’s runtime functions.

    • Issue the CSPModulePath directive, providing the full path for the directory that contains the .so file for the Web Gateway’s runtime functions.

    • Issue the CSPConfigPath directive, providing the full path for the directory that contains the .so file for the Web Gateway management functions.

    • Configure access settings for the directory that contains the Web Gateway binaries. To do so, add a <Directory> directive block for that directory as follows (the example assumes the most common installation location):

      <Directory "/opt/webgateway/bin">
          AllowOverride None
          Options MultiViews FollowSymLinks ExecCGI
          Require all granted
          <FilesMatch "\.(log|ini|pid|exe)$">
              Require all denied 
          </FilesMatch>
      </Directory>
      
  4. Optional: if you want the web server to serve static files for your web applications, append directives to map the appropriate /csp paths to file system locations accessible to your web server. The Apache Alias directive provides one such method to accomplish this.

    For example: if the application /dashboard is served by a remote InterSystems IRIS instance but you want to serve static files for the application from the directory C:\iris\csp\dashboard on the web server’s machine, you could add the following directive:

    Alias /dashboard/ "C:/iris/csp/dashboard"
    
  5. Issue directives which invoke the Web Gateway to handle requests intended for your InterSystems IRIS applications. InterSystems provides the following directives for this purpose:

    • CSPFileTypes, which invokes the Web Gateway for requests for the set of file types you specify. (Because REST API endpoints are often paths and not files, this directive is not sufficient to invoke requests for REST applications.)

    • CSP On and CSP Off, which enable or disable the Web Gateway as the handler for all requests.

    By issuing these directives within <Location> blocks, you can configure your web server in a granular way, invoking the Web Gateway only for those relative URL paths which correspond with your InterSystems IRIS web applications.

    The following location block would invoke the Web Gateway exclusively for requests directed to the Management Portal for an InterSystems IRIS instance named iris3:

    <Location "/iris3/csp/sys/">
        CSP On
    </Location>
    
    Note:

    To access the management pages for a Web Gateway without access to an InterSystems IRIS instance, enable the Web Gateway for the /csp path.

  6. Save the httpd.conf file.

  7. Restart Apache to allow the configuration changes to take effect.

The installer employs this procedure when it automatically configures an Apache web server. See Automatic Configuration Example for an example.

Microsoft Internet Information Services (IIS) for Windows

Microsoft IIS (https://www.iis.net/Opens in a new tab) is preinstalled with many distributions of Windows. However, it is usually disabled by default. See Enable IIS.

This page describes how to deploy the Web Gateway as a Native Module using an IIS proprietary API.

The Web Gateway Native Module implements the Web Gateway using two dynamic linked library (.dll) files:

  • CSPms.dll — the runtime binary

  • CSPmsSys.dll — the Web Gateway management binary

This is the recommended deployment option; it is effective for the vast majority of use cases.

Alternative Options for IIS describes other options for deploying the Web Gateway with IIS, including options which use ISAPI and options which use the Network Service Daemon (NSD).

Enable IIS

To enable IIS:

  1. Open the Windows Features manager by searching for Turn Windows features on or off, or by opening the Control Panel and selecting Programs > Programs and Features > Turn Windows Features on or off.

  2. Select Internet Information Services.

  3. To enable redirection of documentation links, HTTP Redirection must also be enabled within IIS. To enable it, ensure that Internet Information Services > World Wide Web Service > Common HTTP Features > HTTP Redirection is selected.

  4. To enable debugging sessions in a supported IDE, the WebSocket Protocol must also be enabled within IIS. To enable it, ensure that Internet Information Services > World Wide Web Service > Application Development Features > WebSocket Protocol is selected.

  5. Select OK.

If you would like the installer to automatically configure a new or upgraded InterSystems IRIS instance to serve its web applications over IIS, IIS must be enabled prior to installation. However, the HTTP Redirection and WebSocket Protocol features of IIS can be enabled at any time.

Set Permissions for the Web Gateway Components

By default, IIS does not allow the user of a web application access to anything outside of the web document root directory (usually C:\Inetpub\wwwroot). To provide access to web application resources located in a directory outside of the web document root, the following user groups must possess Read, Write, and Execute permissions for the directory:

  • [machine_name]\IIS_IUSRS, the user group under which IIS worker processes and applications controlled through IIS (such as the Web Gateway) operate.

  • [machine_name]\Users

You must manually set these permissions for the Web Gateway directory (usually C:\Inetpub\CSPGateway) and for any directory containing static files which a web application serves. To do so:

  1. In the Windows File Explorer, navigate to the directory’s parent directory. For example: if you are configuring the C:\Inetpub\CSPGateway directory, navigate to navigate to C:\Inetpub.

  2. Right-click the directory name and select Properties.

  3. Select the Security tab.

  4. Select Edit.

  5. Select Add.

  6. In the Enter the object names to select text box enter:

    [machine_name]\IIS_IUSRS

  7. Select Check Names and OK.

  8. Select [machine_name]\IIS_IUSRS in the Group or Usernames window, then:

  9. Assign Read & Execute and Write permissions in the Permissions window.

  10. Select Apply and OK.

  11. Repeat the above process for the [machine_name]\Users user group.

If the Web Gateway configuration file (CSP.ini) or the Web Gateway log file (CSP.log) is located elsewhere within your file system, you must also ensure that the IIS_IUSRS group has full read and write permissions for these files.

Register the Native Modules

Before you can use the Web Gateway Native Modules, you must register them within IIS. To do so:

  1. Open the Internet Information Services (IIS) Manager.

  2. Select your localhost connection from the Connections panel.

  3. Within the Features View for the connection’s Home page, open (double-click) the Modules feature configuration item.

  4. Select the Configure Native Modules... action from the Actions panel.

  5. Select Register and enter the following in the Register Native Module dialog:

    Name: CSPms (or similar)

    Path: C:\Inetpub\CSPGateway\CSPms.dll

  6. Select OK.

  7. Within the Connections panel, expand the contents of your localhost connection to select Sites > Default Web Site.

  8. Ensure that the Web Gateway module is enabled:

    1. Within the Features View for the Default Web Site Home page, open (double-click) the Modules feature configuration item.

    2. Select the Configure Native Modules... action from the Actions panel.

    3. Within the Configure Native Modules dialog, if CSPms appears in the list, select it and then select OK.

Configuring the Web Application Path

For each InterSystems IRIS web application you want to serve, configure its relative path (/csp or /irisinstance2) as an IIS Application.

Note that configuring an IIS Application creates the path mapping which is required to allow the web server to serve static files, provided that the web server has adequate permissions to access the physical path.

For each application path you want to configure, perform the following steps:

  1. Open the Internet Information Services (IIS) Manager.

  2. Within the Connections panel, expand the contents of your localhost connection to select Sites > Default Web Site.

  3. Select View Applications from the Actions panel.

  4. Select Add Application... from the Actions panel.

  5. In the Add Application dialog, provide the following information:

    • Alias: the relative base URL path for the application. For example: /irisinstance2 for applications hosted by the instance IRISinstance2, or csp for the application /csp/sys and its sibling applications.

    • Physical path: the directory which contains the static files associated with the application. If you want IIS to serve static files from a different directory for applications with paths subordinate to the application path you are currently configuring, define an IIS Virtual Directory for the child directory.

  6. Select OK.

  7. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

Note:

To access the management pages for a Web Gateway without access to an InterSystems IRIS instance, enable the Web Gateway for the /csp path.

If you are using a Web Gateway solution based on an alternative option, set up an application called /bin under the /csp application. Map this to the physical directory holding the Web Gateway binaries. In most cases, this would be a mapping between the application path /csp/bin and the physical path C:\Inetpub\CSPGateway

Define a Virtual Directory

IIS Virtual Directories enable users to serve some static content from a file system location outside of the file system location specified for the application. For example, the administrator of a static web site which hosts its images at domain.com/images can store most of the web site’s content in C:\Inetpub\wwwroot but store images in C:\siteimg by mapping the Virtual Directory images to that physical path.

You can use IIS Virtual Directories if you maintain different static file storage locations for different InterSystems IRIS applications within one parent path directory (for example, /csp).

To configure an IIS Virtual Directory:

  1. Within the Internet Information Services (IIS) Manager, locate the IIS Application for which you want to configure a subordinate Virtual Directory in the Connections panel, and select it.

  2. Select View Virtual Directories from the Actions panel.

  3. Select Add Virtual Directories from the Actions panel.

  4. In the Add Virtual Directory dialog, provide the following information:

    • Alias: the subordinate part of the application URL path. For example: sys for the path /csp/sys

    • Physical path: the alternative location of static files for this path.

  5. Select OK.

  6. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

Set Handler Mappings for Application Requests

For each IIS Application you have configured, direct IIS to invoke the Web Gateway as a handler for some (or all) requests sent to the application path by creating Handler Mappings.

To invoke the Web Gateway as a handler for all requests sent to an application path: follow the steps below to create a Handler Mapping for the Request Path * (wildcard).

To invoke the Web Gateway exclusively for certain file types: follow the steps below for each file type, specifying *.xxx as the Request Path, where xxx is the file extension. To serve InterSystems specific file types, create Handler Mappings for the following request paths: *.csp, *.cls, *.zen, and *.cxw. You must also create Handler Mappings for any static file types you want your application to serve. (Because REST API endpoints are often paths and not files, this file type-specific approach is not sufficient to invoke requests for REST applications.)

Perform the following steps to create a Handler Mapping for an IIS Application:

  1. Open the Internet Information Services (IIS) Manager.

  2. Within the Connections panel, expand the contents of your localhost connection and select the name of your Application from the list available within Sites > Default Web Site.

  3. Within the Features View for the connection’s Home page, open (double-click) the Handler Mappings feature configuration item.

  4. Within the actions panel, select Add Module Mapping....

    Note:

    Do not use the Add Wildcard Script Mapping... action to set the Web Gateway as the handler for all requests at an application path. Attempting to do so yields an error. Instead, add a module mapping for the wildcard (*) character.

  5. In the Add Module Mappings dialog, specify the following:

    • Request Path — provide an expression that specifies the set of requests which the Web Gateway should handle. (See the beginning of this section for examples of valid expressions.)

    • Module — from the drop-down menu, select the name you provided for the Web Gateway module (CSPms).

    • Name — provide a descriptive name for this mapping, such as WebGateway_*.

  6. Select Request Restrictions and ensure that the box next to Invoke handler only if request is mapped to is cleared (not selected). This action sets the value of Path Type to Unspecified, as shown in the Handler Mappings table.

  7. Select OK to return to the Add Module Mappings dialog, and then select OK again.

  8. Repeat the above process to add all desired Handler Mappings for the IIS Application.

  9. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

Enable URLs with /bin

By default, IIS does not serve resources from request paths which contain the directory /bin. You must disable this filter to serve the Web Gateway management pages.

If the installer configured the Web Gateway automatically, this step was done automatically for you. If you are installing the Web Gateway manually, you must perform this configuration manually.

The following procedure enables IIS to serve the Web Gateway management pages specifically:

  1. Open the applicationHost.config file in a text editor. The file is usually located in the C:\Windows\System32\Inetsrv\Config directory. To find the location of this file on your system:

    1. Select (double-click) the Configuration Editor from the Home page for your localhost connection or any site item within that connection in the Connections panel.

    2. Select Search Configuration... from the Actions panel.

    3. In the Hierarchy View, select ApplicationHost.config (or any of its child items). When you do so, the Configuration Search dialog displays the location of the ApplicationHost.config file.

  2. At the end of the <configuration> block (but within it), append the following <Location> tag:

    <location path="localhost/csp/bin/Systems/Module.cxw">
        <system.webServer>
            <security>
               <requestFiltering>
                  <hiddenSegments>
                     <remove segment="bin" />                    
                   </hiddenSegments>
               </requestFiltering>
            </security>
         </system.webServer>
     </location>
    
    
  3. Save the file.

  4. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

Configure the Launcher for Remote Web Server Connections

To enable the InterSystems IRIS launcher to construct valid URLs for an InterSystems IRIS instance’s built-in web, you must specify the connection details for the instance within the InterSystems IRIS Server Manager. These connection details should match your web server configuration. See Define a Remote Server Connection in System Administration Guide.

Configuring IIS to Return SOAP Fault Details

An InterSystems IRIS web service that encounters an error may return an HTTP 500 error without the associated SOAP fault details. By default, IIS returns extended error information only to local clients. However, you can modify this behavior in the <httpErrors> element within the configuration file web.config. To do so, add the following section to instruct IIS to dispatch detailed error information to all clients.

<configuration>
    <system.webServer>
       <httpErrors errorMode="Detailed" />
    </system.webServer>
</configuration>

Use caution with this approach as sensitive information about the hosting environment may be revealed to clients. An alternative approach that avoids the security concerns of using errorMode="Detailed” is to instead use the existingResponse="PassThrough" directive.

<configuration>
    <system.webServer>
       <httpErrors existingResponse="PassThrough" />
    </system.webServer>
</configuration>

Restart IIS after making changes to the configuration.

You can make these changes manually to the IIS web.config file. Or, for a better, less error prone, approach, use the Configuration Editor built into the IIS Manager.

  1. In the IIS Manager, from the Connections panel on the left, select the path which corresponds to the web service. For example: Default Web Site, then csp.

  2. In the middle panel, below the Management heading at the bottom, double-click on Configuration Editor.

  3. In the Configuration Editor dropdown at the top labeled Section, expand system.webServer and click httpErrors.

  4. Click on the value next to existingResponse and use the dropdown to view the options. Select PassThrough.

  5. In the Actions pane on the right, click Apply.

  6. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

Further information about error handling in IIS can be found at:

https://docs.microsoft.com/en-us/iis/configuration/system.webServer/httpErrors/Opens in a new tab

Restarting IIS

This section describes what happens when IIS is restarted via the various control panels.

Most configuration changes can be made in real-time to an active IIS installation. However, the Internet Information Services (IIS) Manager control panel provides stop, start, and restart options. These are useful for the refreshing the web server configuration. However, it does not reinitialize a Web Gateway installation.

When you have made modifications to a Web Gateway installation, restart IIS in one of the following ways:

  • Open the Windows Services manager and restart the World Wide Web Publishing service.

  • From the command line, run the following command to stop IIS:

    sc stop W3SVC
    

    After the web server stops, run the following command to restart it:

    sc start W3SVC
    

Troubleshooting

This section describes problems that commonly occur in configuring third-party modules (both Native and ISAPI) to work with IIS.

The most common problem likely to be encountered is that, after reconfiguring, requests to IIS fail with the following error:

Service Unavailable

HTTP Error 503. The service is unavailable.

This usually indicates that the default Application Pool has terminated.

  1. Open the Internet Information Services (IIS) Manager window.

  2. In the left panel expand the top level to reveal the Application Pools section.

    [MACHINE_NAME] ([machine_name]\[user_name])

    Application Pools

  3. Check that the Default Application Pool (DefaultAppPool), or whatever application pool your server is configured to use, is marked with a Status of Started.

  4. Restart the application pool if necessary (using the options in the right panel).

  5. If problems persist, look for clues in the main Windows Event Log (in the Applications section). In particular, check for the following error message:

    Failed to find the RegisterModule entrypoint in the module DLL C:\Inetpub\CSPGateway\CSPms.dll. The data is the error.

    This, for example, indicates that the version of Web Gateway DLLs that you are using do not implement the Native Modules interface. Either obtain later DLLs from InterSystems or configure the Web Gateway to work through the conventional ISAPI interface.

As with all software, restarting often clears transient problems: To completely restart IIS, restart the World Wide Web Publishing service via the main Windows Services control panel.

Do not use the Add Wildcard Script Map utility to map file extensions. If you do, you may see this error: The specified module required by the handler is not in the modules list. If you are adding a script map handler mapping, the IsapiModule or the CgiModule must in the modules list. Instead use Add Module Mapping for * to map file extensions using a wildcard.

If URLs with /bin in them do not work, see Manual Step for Enabling URLs with /bin

Nginx for UNIX®/Linux/macOS

Introduction

This page describes how to build and configure an Nginx web server for use with the InterSystems Web Gateway on UNIX®, Linux, or macOS.

Nginx is an Open Source product and the source code can be downloaded free of charge from: http://nginx.org/Opens in a new tab

Some prebuilt kits are available for Linux which are, generally, a few builds behind the latest Nginx build. However, given that extensions must be compiled into the Nginx core, it is necessary to build the web server locally from the source code in order to include support for CSP.

After the steps in this page, you can use the Web Gateway management pages to further configure the Web Gateway.

Assumptions

This page assumes that:

  • CSP/Web Gateway web server components are installed in /opt/webgateway/bin/

  • InterSystems IRIS, if installed locally, is in /opt/iris/

  • The web server is installed under /opt/nginx/

If the layout is different on your system, modify the configuration directives as appropriate.

Installation

The Web Gateway components and the CSP static files should be installed as follows:

  1. Web Gateway Network Service Daemon (NSD)

    • CSPnsd

    The default location for this binary is /opt/webgateway/bin/

  2. HyperEvents Components

    CSPBroker.js

    CSPxmlhttp.js

    The default location for these files is /opt/iris/csp/broker

    If these files are to be served as static components directly by the web server, copy them to /opt/nginx/html/csp/broker

  3. Miscellaneous static resources used by the Management Portal

    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is /opt/iris/csp/sys

    If these files are to be served as static components directly by the web server, copy them to /opt/nginx/html/csp/sys

Building the Nginx Web Server for CSP

Most of the Web Gateway functionality is provided by the NSD (CSPnsd). For CSP access, Nginx can be built and configured to communicate with the NSD through a small compiled-in module, ngx_http_csp_module.c. For convenience, all Web Gateway installations include this source file.

The build instructions given here are based on the official documentation for building Nginx under UNIX® systems:

http://nginx.org/en/docs/configure.htmlOpens in a new tab

The Nginx documentation stipulates that the following third party add-ons are also required:

Important:

The OpenSSL toolkit you use should be compatible with your version of InterSystems IRIS; see Which TLS Versions Does My Instance of InterSystems IRIS Support?

However, it is possible to create a fully functional server without these components, provided the final installation doesn’t require the functionality that would otherwise be provided by them.

A typical configuration script for building Nginx, including all optional modules listed above, is as follows:

./configure --prefix=/opt/nginx --with-http_ssl_module

This results in a default Nginx build installed under: /opt/nginx

The build process can be modified to exclude optional modules:

  • OpenSSL - Remove SSL/TLS capability:

    Remove directive: --with-http_ssl_module

  • Zlib - Remove GZIP capability:

    Add directive: --without-http_gzip_module

  • PCRE - Remove HTTP rewrite capability:

    Add directive: --without-http_rewrite_module

Procedure for building Nginx for CSP

  1. Unpack the source distribution under a location of your choice. For example:

    /opt/

    After unpacking, if you specify /opt/, the source code distribution is under:

    /opt/nginx-n.n.n/

  2. Create a directory for the CSP extension:

    /opt/nginx-n.n.n/csp/

  3. Copy the module source code (ngx_http_csp_module.c) to the directory created above.

  4. In that same directory, create a configuration file called config. This file should contain the following lines:

    ngx_addon_name=ngx_http_csp_module
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module.c"
    CORE_LIBS="$CORE_LIBS -ldl"
    
  5. Working in /opt/nginx-n.n.n/, configure the Nginx build environment:

    ./configure --prefix=/opt/nginx
                --with-http_ssl_module
                --add-module=/opt/nginx-n.n.n/csp
    

    Alternatively, without the optional functionality provided by OpenSSL, ZLIB and PCRE:

     ./configure --prefix=/opt/nginx
                 --without-http_rewrite_module
                 --without-http_gzip_module
                 --add-module=/opt/nginx-n.n.n/csp
    

    Note the final line containing the instructions to include the CSP module.

  6. Compile Nginx:

    make
    
  7. Install Nginx:

    make install
    

    If successful, you should find the complete server installation under:

    /opt/nginx/

Using the NSD with Nginx

You must configure the web server so that it recognizes requests your InterSystems IRIS application must serve and then passes those requests to the NSD.

To do so, edit the web server configuration file (nginx.conf) which is found in /opt/nginx/conf

This section describes the server configuration directives which the CSP extension module provides for configuring the web server. Issuing any of these directives within the context of a location block applies the directive to traffic at the path specified.

CSPNSD_pass hostname:portNum;

(Required.) Specifies the address (hostname and port) where the NSD is listening.

If you do not specify an NSD address for a particular path, the NSD listens at the address 127.0.0.1:7038 by default.

CSP on; and CSP off;

Enables or disables routing to CSP servers through the Web Gateway for all requests.

If you do not issue a CSP directive which applies to a particular path, no requests sent to that path are routed through the CSP off, and the web server does not route any requests sent to that path through the Web Gateway.

CSPFileTypes filetype1[ filetype2...];

Enables the routing of requests for particular file types (filetype1, filetype2, and so on) to CSP servers through the Web Gateway.

For example, if you want the Web Gateway to route requests sent to the /demo/app path if (and only if) they are requesting .csp or .cls files, issue the following directive block:

location /demo/app {
  CSPFileTypes csp cls;
}

Issuing the directive CSPFileTypes * enables the routing of requests for all file types.

This directive does not route requests for URLs which do not request files. Therefore, this directive is inappropriate for most APIs, which often specify paths at endpoints.

CSPNSD_response_headers_maxsize size;

Specifies the maximum size of headers for an HTTP response. If response headers exceed this size, the web client receives an error.

By default, the CSP extension module applies the directive CSPNSD_response_headers_maxsize 8k.

CSPNSD_connect_timeout time;

Specifies the timeout for connecting to the NSD when a request is received from the web client.

By default, the CSP extension module applies the directive CSPNSD_connect_timeout 300s.

CSPNSD_send_timeout time;

Specifies the timeout for a single send operation request (such as POST or PUT). The timeout is applied only between successive send operations; it does not apply to the completion of a single transmission once it has begun.

By default, the CSP extension module applies the directive CSP_send_timeout 300s.

CSPNSD_read_timeout time;

Specifies the timeout for a single read operation (such as GET) upon delivery of a response. The timeout is applied only between successive read operations; it does not apply to the completion of a transmission once it has begun.

By default, the CSP extension module applies the directive CSP_read_timeout 300s.

Example: Enable CSP Routing for All Traffic at a Particular Path

Place the following section within the appropriate server configuration block to route all traffic sent to the /csp path to the Web Gateway:

location /csp {
CSP On;
CSPNSD_pass localhost:7038;
}

Example: Route Requests for InterSystems IRIS File Types to the Web Gateway

Place the following section within the appropriate server configuration block to enable CSP routing for requests sent to the /csp path for the InterSystems IRIS file types (.csp, .cls, .zen, and .cxw) as well as file types required to serve static elements of the Management Portal interface:

location /csp {
CSPFileTypes  csp cls zen cxw .jpg .gif .png .svg .css .js;
CSPNSD_pass localhost:7038;
}

Additional Configuration Required to Use IDEs

To use VS Code with the InterSystems ObjectScript extensionsOpens in a new tab (or any IDE which uses the /api/atelier web application) as an ObjectScript IDE, you must perform the following additional modifications to your Nginx configuration:

  1. The /api/atelier web application uses HTTP headers which include underscores. By default, Nginx’s underscores_in_headers directive instructs Nginx to silently drop these headers. You must configure your Nginx server to include them. See http://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headersOpens in a new tab.

  2. Features such as the debugger require a WebSocket connection. By default, Nginx is not configured to support WebSockets. For information on enabling WebSockets, refer to the Nginx documentation: (http://nginx.org/en/docs/http/websocket.htmlOpens in a new tab).

Start and Stop Nginx and the NSD

To start Nginx:

/opt/nginx/sbin/nginx

To stop Nginx:

/opt/nginx/sbin/nginx –s stop

See Operating the NSD for instructions on how to operate the NSD.

Deprecated: Building Nginx to Work with the Universal Modules

Important:

Use of the Universal Modules with Nginx has been deprecated due to stability issues. Deployments of the Web Gateway which connect to Nginx using the NSD fully support all features, including WebSockets.

If you are currently using the Universal Modules with Nginx, InterSystems recommends upgrading to the most recent version of the Web Gateway and rebuilding your Nginx server to work with the NSD. Be sure to remove the CSPModulePath directive from your server configuration when you edit the server configuration file.

The following instructions serve as a reference for existing installations only.

Nginx can be built to work with the dynamically-linked Universal Modules CSPx.so (runtime) and CSPxSys.so (Web Gateway systems management). The procedure for building and configuring Nginx to work with the Universal Modules varies from the NSD-based deployment as follows:

  • In step 3, copy the module source code ngx_http_csp_module_sa.c, cspapi.h, and ngx_http_csp_common.h to the specified directory, instead of ngx_http_csp_module.c.

  • In step 4, the configuration file for CSP (/opt/nginx-n.n.n/csp/config) should read as follows:

    ngx_addon_name=ngx_http_csp_module_sa
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module_sa"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module_sa.c"
    
  • Add the CSPModulePath directive from the http configuration block to specify the path to the Universal Gateway Modules.

    CSPModulePath /opt/webgateway/bin;
    
  • The following directives are not supported:

    • CSPNSD_pass

    • CSPNSD_response_headers_maxsize

    • CSPNSD_connect_timeout

    • CSPNSD_send_timeout

    • CSPNSD_read_timeout

  • The following directives are supported:

    • CSP

    • CSPFileTypes

Nginx for Windows

Introduction

This page describes how to build and configure an Nginx web server for use with the InterSystems Web Gateway on Windows.

Nginx is an Open Source product. The source code can be downloaded free of charge from: http://nginx.org/Opens in a new tab

Some prebuilt kits are available for Windows which are, generally, a few builds behind the latest Nginx build. However, given that extensions must be compiled into the Nginx core, it is necessary to build the web server locally from the source code in order to include support for CSP.

After the steps in this page, you can use the Web Gateway management pages to further configure the Web Gateway.

Assumptions

This page assumes that

  • The CSP/Web Gateway components are installed in install-dir\csp\

  • The web server is installed in C:\nginx\

If the layout is different on your system, modify the configuration directives as appropriate.

Installation

The Web Gateway components and the CSP static files should be installed as follows:

  1. Web Gateway Network Service Daemon (NSD)

    • CSPnsd.exe (main binary)

    • CSPnsdSv.exe (Windows service)

    The default location for these files is install-dir\bin

    The configuration file and log file are written in this directory.

  2. HyperEvents Components

    • CSPBroker.js

    • CSPxmlhttp.js

    The default location for these files is install-dir\csp\broker

    If these files are to be served as static components directly by the web server, copy them to C:\nginx\html\csp\broker

  3. Miscellaneous static resources used by the Management Portal

    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is install-dir\csp\sys

    If these files are to be served directly by the web server, copy these to C:\nginx\html\csp\sys

Building the Nginx Web Server for CSP

Most of the Web Gateway functionality is provided by the NSD (CSPnsd[Sv].exe). For CSP access, Nginx can be built and configured to communicate with the NSD through a small compiled-in module: ngx_http_csp_module.c. For convenience, all Web Gateway installations include this source file.

Prerequisites for building Nginx:

The build instructions given here are based on the official documentation for building Nginx under Windows:

http://nginx.org/en/docs/howto_build_on_win32.htmlOpens in a new tab

The Nginx documentation stipulates that the following third party add-ons are also required:

Important:

The OpenSSL toolkit you use should be compatible with your version of InterSystems IRIS; see Which TLS Versions Does My Instance of InterSystems IRIS Support?

However, it is possible to create a fully functional server without these components, provided the final installation doesn’t require the functionality that would otherwise be provided by them.

The default configuration script for building Nginx, including all optional modules listed above, is as follows:

auto/configure \
 --with-cc=cl \
 --with-debug \
 --prefix= \
 --conf-path=conf/nginx.conf \
 --pid-path=logs/nginx.pid \
 --http-log-path=logs/access.log \
 --error-log-path=logs/error.log \
 --sbin-path=nginx.exe \
 --http-client-body-temp-path=temp/client_body_temp \
 --http-proxy-temp-path=temp/proxy_temp \
 --http-fastcgi-temp-path=temp/fastcgi_temp \
 --http-scgi-temp-path=temp/scgi_temp \
 --http-uwsgi-temp-path=temp/uwsgi_temp \
 --with-cc-opt=-DFD_SETSIZE=1024 \
 --with-pcre=objs/lib/pcre-8.44 \
 --with-zlib=objs/lib/zlib-1.2.12 \
 --with-openssl=objs/lib/openssl-1.1.1k \
 --with-openssl-opt=no-asm \
 --with-http_ssl_module

The build process can be modified to exclude optional modules:

  • OpenSSL - Remove SSL/TLS capability:

    Remove directive: --with-http_ssl_module

  • Zlib - Remove GZIP capability:

    Add directive: --without-http_gzip_module

  • PCRE - Remove HTTP rewrite capability:

    Add directive: --without-http_rewrite_module

Procedure for Building Nginx for CSP

  1. Working in a MSYS2 shell, create the working directory structure suggested in the Nginx documentation:

    /opt/

  2. Working in /opt, check-out the Nginx source code using the following command:

    hg clone http://hg.nginx.org/nginx
    

    This places the Nginx source code under: /opt/nginx/

  3. Create a directory for the CSP extension:

    mkdir /opt/nginx/objs/lib/csp/
    
  4. Copy the module source code (ngx_http_csp_module.c) to the directory created in the previous step.

  5. In the same directory, create a configuration file called config. This file should contain the following lines:

    ngx_addon_name=ngx_http_csp_module
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module.c"
    
  6. Working in /opt/nginx/, configure the Nginx build environment:

    auto/configure --with-cc=cl --builddir=objs --prefix=
                   --conf-path=conf/nginx.conf --pid-path=logs/nginx.pid
                   --http-log-path=logs/access.log --error-log-path=logs/error.log
                   --sbin-path=nginx.exe
                   --http-client-body-temp-path=temp/client_body_temp
                   --http-proxy-temp-path=temp/proxy_temp
                   --http-fastcgi-temp-path=temp/fastcgi_temp
                   --with-cc-opt=-DFD_SETSIZE=1024 --without-http_rewrite_module
                   --without-http_gzip_module
                   --with-select_module --with-ipv6
                   --add-module=objs/lib/csp
    

    Note the final line containing the instructions to include the CSP module.

  7. Compile Nginx. This can be done in either the current MSYS2 shell or a Visual Studio developer command prompt.

    To use the MSYS2 shell, locate the vcvarsall.bat script corresponding to your desired Visual Studio build environment and compile Nginx.

    cd /c/path/to/vcvarsall
    vcvarsall.bat
    cd -
    nmake -f objs/Makefile
    

    Alternatively, if you do not know where to find vcvarsall.bat, you can open a Visual Studio developer command prompt, which will set up the build environment for you. First, convert the MSYS2 path to an equivalent Windows path in the current MSYS2 shell.

    cygpath –m $(pwd)
    

    Then, open a Visual Studio command prompt for your desired build environment and navigate to that Windows path. Compile Nginx.

    nmake -f objs/Makefile
    

    If successful, you should find the server (nginx.exe) in: /opt/nginx/objs/

  8. Install Nginx: The easiest way to do this is to first download and install a pre-built version of Nginx for Windows to obtain the directory structure (usually under C:\nginx\) then replace the nginx.exe file in that installation with the one created locally.

    The typical directory structure for an operational Nginx installation is as follows:

    Directory of C:\nginx
    
    03/07/2017  09:09    <DIR>          .
    03/07/2017  09:09    <DIR>          ..
    26/06/2017  10:14    <DIR>          conf
    26/06/2017  10:14    <DIR>          contrib
    10/05/2018  12:53    <DIR>          csp
    26/06/2017  10:14    <DIR>          docs
    26/06/2017  10:14    <DIR>          html
    10/05/2018  15:57    <DIR>          logs
    04/07/2017  15:52           715,264 nginx.exe
    26/06/2017  10:17    <DIR>          scgi_temp
    26/06/2017  10:17    <DIR>          temp
    26/06/2017  10:17    <DIR>          uwsgi_temp
    

    Replace the copy of nginx.exe in this directory with the version created by the build procedure.

Configure Nginx to Invoke the NSD

You must configure the web server so that it recognizes requests for InterSystems file types and passes those requests (as well as requests for any other static files your InterSystems IRIS application serves) to the NSD for processing.

To do so, edit the web server configuration file (nginx.conf), which is found in C:\nginx\conf

This section describes the server configuration directives which the CSP extension module provides for configuring the web server. Issuing any of these directives within the context of a location block applies the directive to traffic at the path specified.

CSPNSD_pass hostname:portNum;

(Required.) Specifies the address (hostname and port) where the NSD is listening.

If you do not specify an NSD address for a particular path, the NSD listens at the address 127.0.0.1:7038 by default.

CSP on; and CSP off;

Enables or disables routing to CSP servers through the Web Gateway for all requests.

If you do not issue a CSP directive which applies to a particular path, no requests sent to that path are routed through the CSP off, and the web server does not route any requests sent to that path through the Web Gateway.

CSPFileTypes filetype1[ filetype2...];

Enables the routing of requests for particular file types (filetype1, filetype2, and so on) to CSP servers through the Web Gateway.

For example, if you want the Web Gateway to route requests sent to the /demo/app path if (and only if) they are requesting .csp or .cls files, issue the following directive block:

location /demo/app {
  CSPFileTypes csp cls;
}

Issuing the directive CSPFileTypes * enables the routing of requests for all file types. However, REST APIs must support receiving requests at endpoints which do not specify a file (and therefore do not specify a file type). For such applications, it is not possible to invoke the Web Gateway for requests based on the file type, and you must enable the Web Gateway as the handler for all requests at the path (using CSP on;).

CSPNSD_response_headers_maxsize size;

Specifies the maximum size of headers for an HTTP response. If response headers exceed this size, the web client receives an error.

By default, the CSP extension module applies the directive CSPNSD_response_headers_maxsize 8k.

CSPNSD_connect_timeout time;

Specifies the timeout for connecting to the NSD when a request is received from the web client.

By default, the CSP extension module applies the directive CSPNSD_connect_timeout 300s.

CSPNSD_send_timeout time;

Specifies the timeout for a single send operation request (such as POST or PUT). The timeout is applied only between successive send operations; it does not apply to the completion of a single transmission once it has begun.

By default, the CSP extension module applies the directive CSP_send_timeout 300s.

CSPNSD_read_timeout time;

Specifies the timeout for a single read operation (such as GET) upon delivery of a response. The timeout is applied only between successive read operations; it does not apply to the completion of a transmission once it has begun.

By default, the CSP extension module applies the directive CSP_read_timeout 300s.

Example: Enable CSP Routing for All Traffic at a Particular Path

Place the following section within the appropriate server configuration block to route all traffic sent to the /csp path to the Web Gateway:

location /csp {
CSP On;
CSPNSD_pass localhost:7038;
}

Example: Route Requests for InterSystems IRIS File Types to the Web Gateway

Place the following section within the appropriate server configuration block to enable CSP routing for requests sent to the /csp path for the InterSystems IRIS file types (.csp, .cls, .zen, and .cxw) as well as file types for static files which the Management Portal interface uses:

location /csp {
CSPFileTypes  csp cls zen cxw jpg gif png svg css js;
CSPNSD_pass localhost:7038;
}

Start and Stop Nginx and the NSD

To start Nginx:

C:\nginx\nginx

To stop Nginx:

C:\nginx\nginx –s stop

See Operating the NSD for instructions on how to operate the NSD.

For VS Code Users: Additional Configuration Needed

If you want to connect VS Code with the InterSystems ObjectScript Extensions to an InterSystems IRIS instance which uses an Nginx web server, you must configure Nginx as follows:

  1. Supported ObjectScript IDEs connect to InterSystems IRIS using the /api/atelier web application. This web application sends requests which include HTTP headers with underscores. By default, Nginx silently drops these headers. Enable Nginx to retain them. See http://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headersOpens in a new tab.

  2. Features such as the debugger require a WebSocket connection. By default, Nginx is not configured to support WebSockets. Enable Nginx to support WebSockets; see http://nginx.org/en/docs/http/websocket.htmlOpens in a new tab

Deprecated: Building Nginx to Work with the Universal Modules

Important:

Use of the Universal Modules with Nginx has been deprecated due to stability issues. Deployments of the Web Gateway which connect to Nginx using the NSD fully support all features, including WebSockets.

If you are currently using the Universal Modules with Nginx, InterSystems recommends upgrading to the most recent version of the Web Gateway and rebuilding your Nginx server to work with the NSD. Be sure to remove the CSPModulePath directive from your server configuration when you edit the server configuration file.

The following instructions serve as a reference for existing installations only.

Nginx can be built to work with the dynamically-linked Universal Modules CSPx.dll (runtime) and CSPxSys.dll (Web Gateway systems management) instead of the NSD. The procedure for building and configuring Nginx to work with the Universal Modules varies from the NSD-based deployment as follows:

  • In step 4, copy the module source code ngx_http_csp_module_sa.c and ngx_http_csp_common.h to the specified directory, instead of ngx_http_csp_module.c.

  • In step 5, the configuration file for CSP (/opt/nginx/objs/lib/csp/config) reads as follows:

    ngx_addon_name=ngx_http_csp_module_sa
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module_sa"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module_sa.c"
    
  • Add the CSPModulePath directive to the http configuration block to specify the path to the Universal Gateway Modules.

    CSPModulePath install-dir/bin;
    
  • For Windows, the thread stack size must be increased to 2MB. Add the following directive to the top of the Nginx configuration file (before the http section).

    thread_stack_size 2000000;
    
  • The following directives are not supported:

    • CSPNSD_pass

    • CSPNSD_response_headers_maxsize

    • CSPNSD_connect_timeout

    • CSPNSD_send_timeout

    • CSPNSD_read_timeout

  • The following directives are supported:

    • CSP

    • CSPFileTypes

FeedbackOpens in a new tab