Skip to main content

Building and Configuring Nginx (UNIX®/Linux/macOS)

This article describes how to build and configure an Nginx web server for use with the InterSystems Web Gateway on UNIX®, Linux, or macOS. (On these operating systems, the other option is Apache; options are different on Windows.)

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 article, you can use the Web Gateway management pages to further configure the Web Gateway.

Assumptions

This article 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

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:

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

The web server should be configured such that it recognizes InterSystems file types and passes them to the NSD for processing

The web server configuration file (nginx.conf) is found in /opt/nginx/conf

The following configuration directives are provided for the CSP extension:

Syntax: CSP on|off;

Default: CSP off;

Context: location, if in location

Whether CSP is enabled for all requests to a particular path.

Syntax: CSPFileTypes [filetype ... ];

Default: —

Context: location, if in location

The file types for which CSP is enabled. To enable CSP for particular file types such as .csp or .cls, use the following directive.

CSPFileTypes csp cls;

To enable CSP for all file types, use *.

CSPFileTypes *;

Syntax: CSPNSD_pass hostname:port;

Default: —

Context: location, if in location

The hostname/IP and port where the NSD is listening. By default, the NSD listens at 127.0.0.1:7038. This directive is required.

Syntax: CSPNSD_response_headers_maxsize size ;

Default: CSPNSD_response_headers_maxsize 8k;

Context: location, if in location

The maximum size of the HTTP headers in a response. An error is returned to the web client if the response headers exceed this size.

Syntax: CSPNSD_connect_timeout time;

Default: CSPNSD_connect_timeout 300s ;

Context: location, if in location

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

Syntax: CSPNSD_send_timeout time ;

Default: CSPNSD_send_timeout 300s;

Context: location, if in location

Timeout for a single send operation to the NSD when sending a request. The timeout is set only between two successive write operations, not for the transmission of the whole request.

Syntax: CSPNSD_read_timeout time ;

Default: CSPNSD_read_timeout 300s;

Context: location, if in location

Timeout for a single read operation from the NSD when reading a response. The timeout is set only between two successive read operations, not for the transmission of the whole response.

Enabling CSP for a Particular Path

Place the following section within the appropriate server configuration block:

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

Mapping InterSystems IRIS File Extensions

Place the following section within the appropriate server configuration block:

location /csp {
CSPFileTypes  csp cls zen cxw;
CSPNSD_pass localhost:7038;
}

Starting and Stopping 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.

Building Nginx to Work with the CSP NSD Component

Nginx can be built to work with the Universal Modules CSPx.so (Run-time) and CSPxSys.so (Web Gateway systems management). The Universal Modules are dynamically linked modules that can be loaded by a CSP-enabled Nginx installation. Use of the Universal Modules is now deprecated and not recommended due to stability issues. Everyone using the Universal Modules should rebuild and reconfigure Nginx to use the NSD instead. The following instructions serve as a reference only for existing installations. To build Nginx to work with the Universal Modules, modify the build and configuration procedure as follows:

  • In step 3, copy the module source code ngx_http_csp_module_sa.c, cspapi.h, and ngx_http_csp_common.h 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

FeedbackOpens in a new tab