Compiling Dynamic Modules for NGINX Plus

Compiling Dynamic Modules for NGINX Plus

NGINX Plus Release R11 introduces binary compatibility for dynamic modules. This article describes the build process, explaining how to compile third‑party NGINX modules so that they can be used in the NGINX Plus product.

NGINX Modules Overview

NGINX modules 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 described below:

1. Obtain the matching open source NGINX release
2. Obtain the module sources, and update the config shell script if necessary to support the NGINX dynamic modules capability introduced in NGINX 1.9.11
3. Build the dynamic module against the open source NGINX release, with the ‑‑with‑compat argument to the configure command
4. 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 in 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:

$ nginx -v

nginx version: nginx/1.11.5 (nginx-plus-r11)

In this example, it’s NGINX 1.11.5. Download the corresponding open source NGINX package from build repository at nginx.org:

$ 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

When dynamic modules were introduced, it was necessary to change the config shell file that defines parameters for the module build process. It’s straightforward to update old‑style config shell files to support the new parameters, as documented on the NGINX Wiki.

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

Step 3: Compile the Dynamic Module

Compile the module by first running the configure script with the new ‑‑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;

The module provides a hello_world directive that returns the response ‘hello world’ from a location block:

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 2: 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 configuration 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

Using the NAXSI Module with NGINX Plus

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

NGINX Plus ships with a number of dynamic modules that you can install directly from our modules repository. There are two types:

• NGINX‑Authored Modules are written and maintained by the NGINX, Inc. engineering team. We don’t include them in NGINX Plus for technical reasons (they have additional dependencies) or because they are in a preview state. Preview modules – currently, nginScript and ModSecurity – are in active development and should only be deployed with great care. The other modules of this type – currently GeoIP, Image‑Filter, Perl, and XSLT – are fully supported by NGINX, Inc.
• NGINX‑Certified Community Modules are popular third‑party modules that NGINX tests and distributes, and for which we provide installation and basic configuration support. 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.

Modules that you compile yourself (community modules, modules provided by third‑party partners, and custom modules) are not tested or supported by NGINX. If you seek technical support for a problem, the NGINX technical 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.

If you need assistance in developing a module or updating it to support the newer config shell file format, please check out the following resources:

• Emiller’s Guide to NGINX Module Development by Evan Miller
• Dynamic Modules Development for NGINX by 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

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

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

The post Compiling Dynamic Modules for NGINX Plus appeared first on NGINX.

Source: Compiling Dynamic Modules for NGINX Plus