Compiling Third-Party Dynamic Modules for NGINX and NGINX Plus

NGINX | October 25, 2016

Owen GarrettSr. Director, Product Management

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

This post is part of a two‑part series on using third‑party dynamic modules with NGINX Open Source and NGINX Plus.

This post provides step-by-step instructions for compiling third‑party dynamic modules which can be loaded by NGINX Open Source or NGINX Plus at runtime.
The second post provides guidance and tooling for automating third‑party dynamic module builds for a production environment. It explains how to create installable packages for third‑party dynamic modules that include version dependency checking.

NGINX Open Source 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 Open Source 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 NGINX Open Source is relevant. Except as noted, all statements about NGINX Plus also apply to NGINX Open Source.

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 dynamically loaded into NGINX Plus at runtime. You can compile these modules for use with NGINX Plus by building them against NGINX Open Source as illustrated in the two examples below:

Obtain the matching NGINX Open Source release
Obtain the module sources and change the module’s config file if necessary
Build the dynamic module against the NGINX Open Source 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 NGINX Open Source Release

Determine the NGINX Open Source version that corresponds to your NGINX Plus installation. In this example, it’s NGINX 1.11.5.
Download the corresponding NGINX Open Source package at nginx.org/download:

Step 2: Obtain the Module Sources

Obtain the source for the ‘Hello World’ NGINX module from GitHub:
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 NGINX Open Source binary. Modify the file nginx-hello-world-module/config to contain the following:

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 NGINX Open Source and NGINX Plus. Then run make modules to build the module:
Copy the module library (.so file) to /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):
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.
Reload your NGINX Plus configuration and test it with a simple request:

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:

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

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

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 Open Source packages might differ from the ones shipped with NGINX Plus. Dynamic modules used with NGINX Open Source 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 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. For a list, filter by author NGINX 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 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 Partner on the Dynamic Modules page.

NGINX 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 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 NGINX Open Source modules, running them on the rich and fully supported NGINX Plus core.

If you are currently using NGINX Open Source 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: