Skip to main content

Nginx for Windows

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