Compiling Third-Party Dynamic Modules for NGINX and 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.

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

This post provides step-by-step instructions for compiling third‑party dynamic modules which can be loaded by NGINX 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 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.

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:

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.

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 makemodules to build the module:

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

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:

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:

Have a Cookie? :)

Our site uses cookies to provide functionality and performance as well as for social media and advertising purposes. Social media and advertising cookies of third parties are used to offer you social media functionalities and personalized ads for NGINX content and offers. To get more information about these cookies and how we process personal data, check our Privacy Policy. Do you accept the use of cookies and the processing of personal data involved?

Your Cookie Settings

Site functionality and performance

These cookies are required for NGINX site functionality and are therefore always enabled. These include cookies that allow you to be remembered as you explore the NGINX site, help make the shopping cart and checkout process possible as well as assist in security issues and conforming to regulations. To use the NGINX website, you have to consent to these cookies and the processing of personal data according to the NGINX website terms of use and privacy policy.

Social media and advertising

Social media cookies offer the possibility to connect you to your social networks and share content from our website through social media. Advertising cookies (of third parties) collect information to help better tailor NGINX advertising to your interests, both within and beyond NGINX websites. De-selecting these cookies may result in seeing advertising that is not as relevant to you or you not being able to link effectively with Facebook, Twitter, or other social networks and/or not allowing you to share content on social media.