Extend Your Web Server Configuration with the Web Gateway

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.

• Apache: https://httpd.apache.org/docs/2.4/Opens in a new tab

• IIS: https://learn.microsoft.com/en-us/iis/get-started/introduction-to-iis/iis-web-server-overviewOpens in a new tab

• Nginx: http://nginx.org/en/docs/Opens in a new tab

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.

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):

RHEL Ubuntu/SUSE

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:

   RHEL Ubuntu/SUSE

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

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.

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

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

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:

• PCRE

  http://www.pcre.org/Opens in a new tab

• OpenSSL (for SSL/TLS)

  https://www.openssl.org/Opens in a new tab

• Zlib

  http://zlib.net/Opens in a new tab

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

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.

location /demo/app {
  CSPFileTypes csp cls;
}

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 silently drops these headers. You must configure your Nginx server to include them. See https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#missing-disappearing-http-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

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

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:

• Microsoft Visual Studio (version 10 or higher): http://www.microsoft.comOpens in a new tab

• MSYS2 (from MinGW): https://www.msys2.org/Opens in a new tab

• Perl (preferably ActivePerl): https://www.activestate.com/products/perl/Opens in a new tab

• Mercurial source control client: https://www.mercurial-scm.org/Opens in a new tab

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:

• PCRE: http://www.pcre.org/Opens in a new tab

• OpenSSL (for SSL/TLS) https://www.openssl.org/Opens in a new tab

• Zlib: http://zlib.net/Opens in a new tab

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

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.

location /demo/app {
  CSPFileTypes csp cls;
}

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 headers with underscores. See https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#missing-disappearing-http-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

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