How to Compile Dynamic Modules for NGINX Plus

Editor – The blog post announcing the original release of dynamic module support (in open source NGINX 1.9.11, February 2016) redirects here. The build process described in that post is deprecated.

NGINX version 1.11.5 and NGINX Plus Release R11 introduced binary compatibility for dynamic modules. This article explains how to compile third‑party modules for use with NGINX and NGINX Plus in a development environment. For instructions on building, deploying, and upgrading third‑party dynamic modules in a production environment, see Creating Installable Packages for Dynamic Modules.

For the sake of brevity, the remainder of this post refers to NGINX Plus only, except when the difference between it and the open source NGINX software is relevant. Except as noted, all statements about NGINX Plus also apply to NGINX.

Dynamic Modules Overview

Modules that can be loaded into NGINX Plus are written in C and conform to the API described in Extending NGINX on the NGINX Wiki. There is a large ecosystem of third‑party modules, ranging from language interpreters to security solutions, and some of these are included and supported in NGINX Plus.

Other third‑party modules, and modules that you have created yourself, need to be compiled independently and loaded into NGINX Plus at runtime. You can compile these modules for use with NGINX Plus by building them against the open source NGINX software as illustrated in the two examples below:

Obtain the matching open source NGINX release
Obtain the module sources and change the module’s config file if necessary
Build the dynamic module against the open source NGINX release, with the --with-compat argument to the configure command
Load the resulting dynamic module (the .so file) into NGINX Plus and use it as if it were a built‑in module

Example: A Simple “Hello World” Module

This example uses a simple Hello World module to show how to update the source for a module and load it into NGINX Plus. The “Hello World” module implements a simple directive (hello_world) that responds to requests with a simple message.

Step 1: Obtain the Open Source NGINX Release

Determine the open source NGINX version that corresponds to your NGINX Plus installation. In this example, it’s NGINX 1.11.5.
```
$ nginx -v
nginx version: nginx/1.11.5 (nginx-plus-r11)
```

Download the corresponding open source NGINX package at nginx.org/download:

$ wget http://nginx.org/download/nginx-1.11.5.tar.gz
$ tar -xzvf nginx-1.11.5.tar.gz

Step 2: Obtain the Module Sources

Obtain the source for the ‘Hello World’ NGINX module from GitHub:

$ git clone https://github.com/perusio/nginx-hello-world-module.git

The config shell file for a module defines how it is built, and its format is different for dynamic modules than for modules being built statically into an open source NGINX binary.

Modify the file nginx-hello-world-module/config to contain the following:

ngx_addon_name=ngx_http_hello_world_module

if test -n "$ngx_module_link"; then
    ngx_module_type=HTTP
    ngx_module_name=ngx_http_hello_world_module
    ngx_module_srcs="$ngx_addon_dir/ngx_http_hello_world_module.c"

    . auto/module
else
    HTTP_MODULES="$HTTP_MODULES ngx_http_hello_world_module"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_world_module.c"
fi

For detailed information about compiling dynamic modules, including instructions on updating a module’s config file from the old format, see the NGINX Wiki.

Step 3: Compile the Dynamic Module

Compile the module by first running the configure script with the --with-compat argument, which creates a standard build environment supported by both open source NGINX and NGINX Plus. Then run make modules to build the module:
```
$ cd nginx-1.11.5/
$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module
$ make modules
```

Copy the module library (.so file) to /etc/nginx/modules:

$ sudo cp objs/ngx_http_hello_world_module.so /etc/nginx/modules/

Step 4: Load and Use the Module

To load the module into NGINX Plus, add the load_module directive in the top‑level (main) context of your nginx.conf configuration file (not within the http or stream context):
```
load_module modules/ngx_http_hello_world_module.so;
```
In the http context, add a location block with the hello_world directive provided by the Hello World module. Requests to the location return the response hello world.
```
server {
    listen 80;

    location / {
         hello_world;
    }
}
```
Reload your NGINX Plus configuration and test it with a simple request:
```
$ nginx -s reload
$ curl http://localhost/
hello world
```

Example: The NAXSI Web Application Firewall

NAXSI is an easy‑to‑use, high‑performance web application firewall (WAF) that uses heuristics and a scoring system to identify suspicious requests such as XSS and SQL Injection attacks.

The NAXSI source has been updated to comply with the new format for the config shell file, so building a dynamic module for NGINX Plus is straightforward. The process is based on the NAXSI installation instructions:

$ git clone https://github.com/nbs-system/naxsi.git
$ cd nginx-1.11.5/
$ ./configure --with-compat --add-dynamic-module=../naxsi/naxsi_src
$ make modules
$ sudo cp objs/ngx_http_naxsi_module.so /etc/nginx/modules

Load the module into the NGINX Plus core by adding the load_module directive to the main context in your nginx.conf file:

load_module modules/ngx_http_naxsi_module.so;

NAXSI configuration is described in detail in the project documentation. The following NGINX configuration illustrates the module in action:

# Edit this 'include' directive to point to your naxsi_core.rules file
include /home/owen/src/naxsi/naxsi_config/naxsi_core.rules;

server {
    listen 80;

    location / {
        root /usr/share/nginx/html;

        # Enable NAXSI
        SecRulesEnabled;

        # Define where blocked requests go
        DeniedUrl "/50x.html";

        # CheckRules, determining when NAXSI needs to take action
        CheckRule "$SQL >= 8" BLOCK;
        CheckRule "$RFI >= 8" BLOCK;
        CheckRule "$TRAVERSAL >= 4" BLOCK;
        CheckRule "$EVADE >= 4" BLOCK;
        CheckRule "$XSS >= 8" BLOCK;

        # Don’t forget the error_log, where blocked requests are logged
        error_log /tmp/naxsi.log;
    }

    error_page   500 502 503 504  /50x.html;
}

You can verify the correct operation of NAXSI with a pair of simple HTTP requests:

curl http://localhost/ returns the standard NGINX Plus index page stored in /usr/share/nginx/html.
curl "http://localhost/?a=<>" triggers NAXSI’s XSS detection and blocks the request, returning the standard 50x.html error page from /usr/share/nginx/html. It also logs a message to the error_log.

For production deployments, you can also download signed NAXSI releases at https://github.com/nbs-system/naxsi/tags and compile them in a similar fashion.

How We Support Dynamic Modules in NGINX Plus

Note: The information in this section applies to NGINX Plus only. The set of dynamic modules that ships with prebuilt NGINX packages might differ from the ones shipped with NGINX Plus. Dynamic modules used with open source NGINX are supported in the same way as the NGINX source code and prebuilt binaries.

NGINX Plus ships with a number of dynamic modules that you can also download directly from our modules repository. For a list, see the Dynamic Modules page. These modules are of two types:

NGINX Plus modules are written and/or maintained by the NGINX, Inc. engineering team. We don’t include them in NGINX Plus for technical reasons (for example, they have additional dependencies) or because they are in a preview state. Preview modules are in active development and should only be deployed with great care. Otherwise, NGINX Plus modules are fully supported by NGINX, Inc. For a list, filter by author NGINX, Inc. on the Dynamic Modules page.
NGINX Plus certified community modules are popular third‑party modules that NGINX tests and distributes, and for which we provide support with installation and basic configuration. We warrant that these modules do not interfere with the correct operation of NGINX Plus, and we update them as necessary at each NGINX Plus release or when there is a security release. For a list, filter by author Community on the Dynamic Modules page.

In addition, NGINX, Inc. certifies modules from commercial vendors who participate in our NGINX Plus Certified Modules program. These modules are distributed and supported by their vendors. For a list, filter by author Certified Partners on the Dynamic Modules page.

NGINX, Inc. does not test or support modules that you compile yourself (other community modules, modules provided by third‑party vendors that are not part of the NGINX Plus Certified Modules program, and custom modules). If you seek technical support for a problem, the NGINX, Inc. support team may ask you to remove an unsupported module and reproduce the fault as part of our technical support process, so that they can verify whether or not the fault is caused by the unsupported module.

Summary

The dynamic modules build process for NGINX Plus allows you to take advantage of the broad ecosystem of open source NGINX modules, running them on the rich and fully supported NGINX Plus core.

If you are currently using open source NGINX with third‑party extensions, these extensions can most likely be compiled and loaded into NGINX Plus.

If you develop commercial or community modules, the new build process means your users can deploy your modules with NGINX Plus. To learn about certifying a commercial module, see NGINX Plus Certified Modules.

If you need assistance in developing a module or updating its config shell file, please check out the following resources:

Emiller’s Guide to NGINX Module Development by Evan Miller
Dynamic Modules Development by NGINX developer Ruslan Ermilov
Extending NGINX on the NGINX Wiki
Converting Static Modules to Dynamic Modules on the NGINX Wiki
NGINX Tutorial: Developing Modules by Aaron Bedra
Creating Installable Packages for Dynamic Modules on our blog

The NGINX Developers mailing list is the go‑to place for community assistance, and our Professional Services team is also happy to assist.

To try dynamic modules with NGINX Plus yourself, start a free 30-day trial today or contact us.